RequestStatus Methods
This walkthrough covers the RequestStatus family of methods. These methods are used to get the status of existing DocuSign Envelopes for electronic signature and are probably the most frequently used methods.
Of course, you should already be comfortable with working with webservices to follow along here. There will be code samples displayed in both C# (using .NET 3.5) and PHP, but you should already know how to get your local proxy class setup and your credentials entered.
Getting Status
So, let’s say that you’ve gone through the electronic signature code walkthrough on using the CreateAndSendEnvelope method and sent your first envelope. After sending the envelope, you should receive the return value of the method, an EnvelopeStatus object containing a property called EnvelopeID, which is the DocuSign unique identifier for an envelope. You should always save this value somewhere in your application, because it is the primary means used to identify an envelope. If you want to get the status of an envelope, you need the EnvelopeID. If you want to download an envelope, you need the EnvelopeID. If you want to void an envelope, you need the EnvelopeID. You always want to keep the EnvelopeID.
Here’s the RequestStatus method call:
//.NET
string EnvelopeID = "Your EnvelopeID";
EnvelopeStatus envStatus = apiService.RequestStatus(EnvelopeID);
//PHP
$RequestStatusParams = new RequestStatus();
$RequestStatusParams->EnvelopeID = "Your EnvelopeID";
$result = $api->RequestStatus($RequestStatusParams);
$envStatus = $result->RequestStatusResult;
Pretty simple; you send in the EnvelopeID, and you get back an EnvelopeStatus object. The EnvelopeStatus object has a lot of information in it, so let’s take a look at it. The top level of the EnvelopeStatus object contains information about the Envelope itself – for example, the EnvelopeID, the Subject of the Envelope, the Username and Email of the Envelope Sender, timestamps for key events in the Envelope’s lifetime, etc. You will probably be most interested in the Status property. This is a string value that indicates where the Envelope is in the signing process. The values for Status are:
| Status |
Description |
| Created |
The envelope was created but has not been sent yet. You typically see this on draft envelopes. |
| Sent |
The envelope has been sent. |
| Delivered |
At least one recipient has been notified to sign the envelope. |
| Signed |
At least one recipient has signed the envelope. |
| Completed |
All recipients have signed the envelope. |
Declined |
A recipient indicated that they do not wish to sign the envelope. |
Voided |
The envelope was cancelled by the sender. |
Deleted |
The envelope was removed from the system. |
Template |
The EnvelopeID refers to a Template, not an Envelope. |
Processing |
The envelope is still being processed. This status is used with envelopes that are sent asynchronously and are placed in a queue pending processing. |
The Status value also has a timestamp value associated with it – for example, for a Created Status value there is an associated date-time value that indicates when the Status changed to Created, and the date-time associated with the Sent status tells you when an Envelope was sent.
Along with the Envelope level information, there are collections (or arrays) that provide status information on Recipients and CustomFields. A RecipientStatus object will let you see when the recipient received and signed the envelope, any extra authentication information that was used, and the status of the tabs assigned to the recipient.
Using the CustomFields status you can retrieve the value of any CustomFields that were specified when the envelope was sent. A CustomField is a collection of name-value pairs that are set by the sender and not visible to the recipients and they can be used to add information to an envelope that is useful to your application.
Of course, there are more status fields than the ones we’ve covered here – you can see the full list in the API documentation in the “EnvelopeStatus” section.
Now, let’s cover the rest of the RequestStatus family. There are actually four methods that differ based on the number of envelopes we are asking the status of and how much information we want to get back.
| Method |
Number of Envelopes |
Extended Information |
| RequestStatus |
Single |
No |
| RequestStatusEx |
Single |
Yes |
| RequestStatuses |
Multiple |
No |
| RequestStatusesEx |
Multiple |
Yes |
The Ex Methods
The Ex suffix on an API method indicates that there will be additional elements returned in the status and that these elements might change. The current version of the API documentation indicates which additional elements are currently being returned. There might be additional elements added in subsequent releases, so you should be sure that your code can accept the surprise appearance of new status properties. The Ex method’s input parameters are identical to the standard version – so the RequestStatusEx method takes a single EnvelopeID, just like the RequestStatus method.
The Es Methods
The ‘Es’ methods indicate that the method operates on multiple envelopes at a time. Because of this, they take different input parameters than the single envelope versions and they return a different object. Although they still use the same EnvelopeStatus object described above, it’s just placed in an array in a wrapper object.
The input parameter to these methods is an EnvelopeStatusFilter. This object is used to specify search parameters to identify the set of envelopes that are reported on. You can specify the Sender’s Username and Email, a span of Dates for an envelope event (for example, all envelopes where the Signed date is between the start and end dates), the current status of the envelope, or even a list of specific EnvelopeIDs. The AccountID is a required parameter and is used to indicate which account is the target of the search. So your code should prepare an EnvelopeStatusFilter representing the search you want to perform, pass that in to the method, and in return you get a FilteredEnvelopeStatuses object.
The FilteredEnvelopeStatuses object has a property called ResultSetSize that tells you how many envelopes matched your criteria. It also contains the EnvelopeStatusFilter used to make the request and an array of up to 200 EnvelopeStatus objects.
The methods are limited to returning up to 200 status objects per call, so if you have a large resultset you will have to make multiple calls. You can do this by passing in the number that you want to start at each time as the StartAtIndex of the EnvelopeStatusFilter. If your initial response indicated that there were 300 envelopes that matched your criteria, you would have received the first 200 status objects in the response, and then you would call the method again, this time setting the StartAtIndex property of the EnvelopeStatusFilter to 200, and you would receive the last 100 status objects in the response.
Here is an example of a request to retrieve all envelopes that are in a Complete status and were sent in the last 24 hours.
//.NET
int StatusesReceived = 0;
bool moreStatusesAvailable = true;
FilteredEnvelopeStatuses statuses ;
EnvelopeStatusFilter filter = new EnvelopeStatusFilter();
filter.AccountId = "Your AccountID Here";
filter.Statuses = new EnvelopeStatusCode[1];
filter.Statuses[0] = EnvelopeStatusCode.Completed;
filter.BeginDateTime = new EnvelopeStatusFilterBeginDateTime();
filter.BeginDateTime.statusQualifier = "Sent";
filter.BeginDateTime.Value = DateTime.Now.AddDays(-1);
while (moreStatusesAvailable==true)
{
// apiService is an already configured api proxy
statuses = apiService.RequestStatuses(filter);
// do something with statuses here
StatusesReceived += statuses.EnvelopeStatuses.Length;
if (statuses.ResultSetSize == StatusesReceived)
{
moreStatusesAvailable = false;
}
else
{
filter.StartAtIndex = StatusesReceived.ToString();
}
}
//PHP
$StatusesReceived = 0;
$moreStatusesAvailable = true;
$oneDay = 60 * 60 * 24;
$BeginDateVal = date("c",time() - $oneDay);
$filter = new EnvelopeStatusFilter();
$filter->AccountId = "Your AccountID Here";
$filter->Statuses[0] = "Completed";
$filter->BeginDateTime->statusQualifier = "Sent";
$filter->BeginDateTime->_ = $BeginDateVal;
$RequestStatusesParam = new RequestStatuses();
$RequestStatusesParam ->EnvelopeStatusFilter = $filter;
while($moreStatusesAvailable === true){
$result = $api->RequestStatuses($RequestStatusesParam);
$statuses = $result->RequestStatusesResult;
// do something with statuses
// this check is because php won't create an empty status array if there are no results,
if($statuses->ResultSetSize > 0){
$StatusesReceived += count($statuses->EnvelopeStatuses->EnvelopeStatus);
}
if ($statuses->ResultSetSize === $StatusesReceived)
{
$moreStatusesAvailable = false;
}
else
{
$filter->StartAtIndex = $StatusesReceived;
}
}
Both examples assume that you are doing something with the status results, like updating a local database, or preparing a list of documents to retrieve, etc.
So that’s the RequestStatus family. Be sure to check the API docs for full details on the methods and parameters, especially for the Ex methods. And as always, if you have any questions, please use the DocuSign DevCenter forums for assistance.
We’re excited to announce that Citadel Insurance Services in Florida uses the DocuSign electronic signature management service to complete and sign insurance documents online. Citadel, a leading personal insurance agency providing auto, home and business coverage, trusts the DocuSign electronic signature platform to quickly, securely and completely transact insurance documents online from anywhere, anytime.
In this electronic signature code walkthrough, we’ll cover Anchor Tabs. If you want a general overview of 
Recent Comments