Code Walkthrough _ The RequestStatus Methods

This walkthrough covers the RequestStatus family of methods. These methods are used to get the status of existing Envelopes at DocuSign 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 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	All recipients have opened the envelope and accepted the consumer disclosure.
Signed	All recipients have signed the envelope. This is typically a transient state on the way to completion.
Completed	All recipients have signed the envelope and processing is complete.
Declined	A recipient indicated that they do not wish to sign the envelope.
Voided	The sender cancelled the envelope.
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.
TimedOut	The envelope was sent but did not complete in the correct number of days.

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.