> You are reading the Docusign Developer Documentation. For clean Markdown of any page, append .md to the page URL.
>
> Documentation indexes by section:
> - APIs and SDKs: https://docusign.docs.buildwithfern.com/docs/llms.txt
> - Platform 101: https://docusign.docs.buildwithfern.com/platform/llms.txt
> - Extension Apps: https://docusign.docs.buildwithfern.com/extension-apps/llms.txt
> - Docusign CLI: https://docusign.docs.buildwithfern.com/docusign-cli/llms.txt
>
> Authentication (OAuth, JWT Grant, M2M): https://docusign.docs.buildwithfern.com/platform/auth
> Webhooks and Connect: https://docusign.docs.buildwithfern.com/platform/webhooks
>
> OpenAPI specifications: https://docusign.docs.buildwithfern.com/openapi.json
> MCP server: https://docusign.docs.buildwithfern.com/_mcp/server

# RequestStatuses and RequestStatusesEx

This method is used to request the status of multiple envelopes in a single call. Up to 1,000 envelopes can be retrieved within a single call. If more results are available, subsequent calls can be used to retrieve the next 1,000, etc.

### Request Envelope Statuses Notes

The SOAP calls for RequestStatuses(Ex) and RequestStatusCodes use certain filters to find results. In some cases requests are check for “any status change” instead of the just the single status requested. In these cases, more envelopes might be returned by the request than otherwise would be. For example, for a request with the begin date is set to Jan 1st, an end date set to Jan 7th and the StatusQualifier set to “Delivered” – the response set might contain envelopes that were created during that time period, but not delivered during the time period.

To avoid unnecessary database queries, the Docusign system checks requests to ensure that the added filters will not result in a zero-size response before acting on the request. The following table shows the valid envelope statuses (in the Valid Current Statuses column) for the status qualifiers in the request. If the status and status qualifiers in the API request do not contain any of the values shown in the valid current statuses column, then an empty list is returned.

For example, a request with a StatusQualifier of “Delivered” and a status of “Created,Sent”, Docusign will always return an empty list. This is because the request essentially translates to: find the envelopes that were Delivered between the begin and end dates that have a current status of Created or Sent, and since an envelope that has been delivered can never have a status of Created or Sent, a zero-size response would be generated. In this case, Docusign does not run the request, but just returns the empty list.

**`RequestStatuses C#`**

```csharp title="RequestStatuses C#"
// Create a filter using account ID and today as a start time
DocuSignWeb.EnvelopeStatusFilter filter = new DocuSignWeb.EnvelopeStatusFilter();
filter.AccountId = _accountId;
filter.BeginDateTime = new DocuSignWeb.EnvelopeStatusFilterBeginDateTime();
filter.BeginDateTime.Value = DateTime.Today;

// Request all envelopes that match the filter
DocuSignWeb.FilteredEnvelopeStatuses statuses = _apiClient.RequestStatuses(filter);

Console.WriteLine("We have {0} statuses that match account ID {1}",
        statuses.EnvelopeStatuses.Length, _accountId);

foreach (DocuSignWeb.EnvelopeStatus eStatus in statuses.EnvelopeStatuses)
{
    Console.WriteLine("\tEnvelope with ID {0} has status {1}", eStatus.EnvelopeID,
        eStatus.Status.ToString());
}
```

**`RequestStatuses PHP`**

```php title="RequestStatuses PHP"
// Create a filter using account ID and today as a start time
$envStatusFilter = new EnvelopeStatusFilter();
$envStatusFilter->AccountId = $AccountID;
$beginDateTime = new EnvelopeStatusFilterBeginDateTime();
$beginDateTime->_ = todayXsdDate(); // note that this helper function
                                    // is in CodeSnippets/include/utils.php
                                    // in the PHP SDK
$envStatusFilter->BeginDateTime = $beginDateTime;

// Send
$requestStatusesparams = new RequestStatuses();
$requestStatusesparams->EnvelopeStatusFilter = $envStatusFilter;
$response = $api->RequestStatuses($requestStatusesparams);
```

**`RequestStatusesEx C#`**

```csharp title="RequestStatusesEx C#"
// Create a filter using account ID and today as a start time
DocuSignWeb.EnvelopeStatusFilter filter
    = new DocuSignWeb.EnvelopeStatusFilter();

filter.AccountId = _accountId;
DocuSignWeb.EnvelopeStatusFilterBeginDateTime begin
    = new DocuSignWeb.EnvelopeStatusFilterBeginDateTime();

begin.Value = DateTime.Today;
filter.BeginDateTime = begin;

// Request all envelopes that match the filter
DocuSignWeb.FilteredEnvelopeStatuses statuses = _apiClient.RequestStatusesEx(filter);

// Display information about the statuses
Console.WriteLine("We have {0} statuses that match account ID {1}",
        statuses.EnvelopeStatuses.Length, statuses.EnvelopeStatusFilter.AccountId);

foreach (DocuSignWeb.EnvelopeStatus eStatus in statuses.EnvelopeStatuses)
{
    Console.WriteLine("\tEnvelope with ID {0}", eStatus.EnvelopeID);
    foreach (DocuSignWeb.DocumentStatus dStatus in eStatus.DocumentStatuses)
    {
        Console.WriteLine("\t\tDocument with ID {0} has name {1}", dStatus.ID,
          dStatus.Name);
    }
}
```

**`RequestStatusesEx PHP`**

```php title="RequestStatusesEx PHP"
// Create a filter using account ID and today as a start time
$envStatusFilter = new EnvelopeStatusFilter();
$envStatusFilter->AccountId = $AccountID;
$beginDateTime = new EnvelopeStatusFilterBeginDateTime();
$beginDateTime->_ = todayXsdDate(); // link to Helper Functions
$envStatusFilter->BeginDateTime = $beginDateTime;

// Send
$RequestStatusesExparams = new RequestStatusesEx();
$RequestStatusesExparams->EnvelopeStatusFilter = $envStatusFilter;
$response = $api->RequestStatusesEx($RequestStatusesExparams);
```

Client applications should check that the statuses they are requesting make sense for a given status qualifier.

| BeginDateTime - StatusQualifier         | Effective Status Qualifier | Valid Current Statuses                                                      |
| --------------------------------------- | -------------------------- | --------------------------------------------------------------------------- |
| Any (changed)                           | StatusChanged              | Any, Created, Sent, Delivered, Signed, Completed, Declined, Voided, Deleted |
| Created                                 | Created                    | Any, Created, Sent, Delivered, Signed, Completed, Declined, Voided, Deleted |
| Sent                                    | Sent                       | Any, Sent, Delivered, Signed, Completed, Declined, Voided, Deleted          |
| Signed                                  | StatusChanged              | Any, Signed, Completed, Declined, Voided, Deleted                           |
| Completed                               | Completed                  | Any, Completed, Declined, Voided, Deleted                                   |
| Declined                                | Declined                   | Any, Declined, Deleted                                                      |
| TimedOut - Always returns zero results. | StatusChanged              | Any, Voided, Deleted                                                        |
| Voided                                  | Voided                     | Any, Voided, Deleted                                                        |
| Deleted                                 | StatusChanged              | Any, Deleted                                                                |

### Schema

**RequestStatuses**

![](/_fern-files/_img/7c41d9d6730398a9949b0d79f8096c0de756f60ed330b87d298e390215e75adf.webp)

**RequestStatusesEx** (EnvelopeStatusFilter is the same as above)

![](/_fern-files/docusign.docs.buildwithfern.com/a3bfeb3fd25abc01674a4c642053b0b10fe9d31a92d31aa10d374236b5764eee/docs/assets/soap/RequestStatusesEx.png)

| Name          | Schema Type          | Description                                                                                                                                                                                                                                                                                                                                                         |
| ------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| UserInfo      | UserInfo             | This would be the username Email pair of the person whose envelope details are requested.                                                                                                                                                                                                                                                                           |
| AccountId     | DSXId                | Account Id for which envelope status is requested.                                                                                                                                                                                                                                                                                                                  |
| BeginDateTime | dateTime             | Specifies the start date of the date range for which envelopes are requested. Has a status qualifier attribute which specifies envelope with what status needs to be requested. The StatusQualifier options are: Completed, Created (the default and what is used if Template or Processing is passed in), Sent, and Voided; any other value becomes StatusChanged. |
| EndDateTime   | dateTime             | Specifies the end date of the date range for which envelopes are requested.                                                                                                                                                                                                                                                                                         |
| Statuses      | EnvelopeStatusCode   | Specifies the status of the envelope at the time of request. This is enumerator controlled.                                                                                                                                                                                                                                                                         |
| EnvelopeIds   | DSXId                | Specifies the envelope Ids of envelopes for which status request. There is a maximum of 200 different EnvelopeIds for each request.                                                                                                                                                                                                                                 |
| StartAtIndex  | nonNegativeInteger   | If envelope status result sets exceed 1000 envelopes, this element can be used to specify that the method should return envelopes at the specified index. The first index is 0, and should be used in the first call to RequestStatuses. Typically this number is a multiple of 1000.                                                                               |
| ACStatus      | EnvelopeACStatusCode | Specifies the Authoritative Copy Status for the envelopes. The possible values are: Unknown, Original, Transferred, AuthoritativeCopy, AuthoritativeCopyExportPending, AuthoritativeCopyExported, DepositPending, Deposited, DepositedEO, or DepositFailed.                                                                                                         |