RequestStatusCodes

The RequestStatusCodes method requests the current state (Delivered, Complete, Voided, etc.) of the specified envelopes.

Note: The SOAP API calls RequestStatusCodes and RequestStatusChanges were created to provide a high-efficiency way to determine envelope status changes. These calls are the preferred methods for determining status. Generally, customers should poll as infrequently as possible. But for customers that generate a large number of envelopes, frequent polling using these calls is an acceptable option. However, when polling at frequent intervals, the call should include an appropriately short time range for StatusChangedSince. For example, if you are checking for status changes every 15 minutes, do not use a StatusChangedSince of 7 days ago.

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.

// Create the status change filter to specify the scope of your search
// Here, we are limiting the search to envelopes changed today
// You can also limit by user and status
DocuSignWeb.EnvelopeStatusFilter filter =
    new DocuSignWeb.EnvelopeStatusFilter();
filter.AccountId = _accountId;
DocuSignWeb.EnvelopeStatusFilterBeginDateTime begin =
    new DocuSignWeb.EnvelopeStatusFilterBeginDateTime();
begin.Value = DateTime.Today;
filter.BeginDateTime = begin;
// Now, make the call with the filter we created
DocuSignWeb.FilteredEnvelopeStatusChanges codes =
    _apiClient.RequestStatusCodes(filter);
if (codes.ResultSetSize > 0)
{
    // Loop through and print out some information about the results
    Console.WriteLine("Changes since today are:");
    foreach (DocuSignWeb.EnvelopeStatusChange code
        in codes.EnvelopeStatusChanges)
    {
        Console.WriteLine("\tEnvelope {0} has status: {1}\n",
            code.EnvelopeID, code.Status);
    }
}

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

Schema

FilteredEnvelopeStatusChanges

This is the response for RequestStatusCodes. It returns the current state of the requested envelopes in an array.