Overview

When planning your application integration with DocuSign, you should consider how you want to handle the signing process. DocuSign offers two methods of running a Signing Ceremony, known as Remote and Embedded Signing.

Remote signing is when DocuSign sends email invitations to the Recipients, and the Recipients click on a link in the email to go to the DocuSign site and sign the documents. DocuSign takes care of everything – sending emails to the Recipients, handling all of the possible actions that they can take during signing, providing access to the signed documents after the signing ceremony is complete. It’s very easy to use, and doesn’t require any setup so it’s a good choice if you need to get up and running quickly. Here’s how it might work in a sample application.

Let’s say that you have a web application that collects some information from your customer, and prepares an envelope with the documents that the customer needs to sign. You send the envelope, and then inform your customer that they will receive an email from DocuSign, and that they will need to click on the link in the email to start the signing process. Then, once the signing is complete, your application can be notified via a status callback from DocuSign, and you can then take additional steps as necessary.

For some applications this is the most desirable flow, but for others it isn’t. It splits the customer interaction into multiple processes – the customer interacts with your application, then they leave your application and interact with DocuSign, and then they (at some future point) interact with your application again. At any point the customer may abandon the transaction, or forget to complete it. Neither of these outcomes is desirable.

You can avoid these issues by using the Embedded Signing pattern. Embedded Signing allows you to host the signing process in your own application and manage the customer interactions directly. It allows you to put your own processes around the signing ceremony to accomplish complex workflows.

How Embedded Signing Works

Embedded Signing works by running a streamlined version of the DocuSign service inside of an iframe in your web application. Your application will make a request to DocuSign to start an Embedded Signing session for a particular Recipient, and DocuSign will provide you with a single use url (known as a RecipientToken) that can be used to start the session.

Your application will then set the iframe’s src attribute to this url, and the Embedded Signing session will start.
While the session is running, DocuSign will conduct the signing ceremony in the iframe. When the Recipient concludes the signing ceremony by signing the documents (or indicating that they do not wish to sign), DocuSign will redirect the iframe to an url, known as a ClientURL, designated by you. When your application detects that the ClientURL is requested, you can then continue with your application workflow.

The RecipientToken
Let’s look at the RecipientToken workflow in more detail.
First, you need to indicate which Recipients can use Embedded Signing when you send the Envelope. You do this by setting the CaptiveInfo object on the Recipient object. You can set the CaptiveInfo object on as many Recipients as you like, but you have to set it when you send the Envelope. The CaptiveInfo object has a single property named ClientUserId, and you must set this to some value that is unique on the Envelope. You can use something simple like “1” or “2”, or you can use some localID that is significant in your application – like a customerId. It just has to be unique on the envelope because this value will be used along with the Recipient’s Name and Email to request the RecipientToken. Remember that while the you can have multiple Recipients with the same Name and Email address (because the same person can act in multiple roles on a single envelope), they must all have different ClientUserIds.

Here’s an example of setting up a Recipient with the CaptiveInfo ClientUserId. In a real application this would have to be done on an Envelope of course – you can review the Create And Send Envelope walkthrough to see a complete Envelope setup.

//.NET
	Recipient recipient= new Recipient();
	recipient.Email = "test@docusign.com";
	recipient.UserName = "Test User";
	recipient.ID = "1";
	recipient.Type = RecipientTypeCode.Signer;
	recipient.RequireIDLookup = false;
	recipient.CaptiveInfo = new RecipientCaptiveInfo();
	recipient.CaptiveInfo.ClientUserId = "1";

//PHP
	$Recipient = new Recipient();
	$Recipient->Email = "test@docusign.com";
	$Recipient->UserName = "Test User";
	$Recipient->ID = "1";
	$Recipient->Type = "Signer";
	$Recipient->RequireIDLookup =false;
	$Recipient->CaptiveInfo->ClientUserId ="1";

Second, you have to get a RecipientToken for each Recipient that you want to have sign. When you get a Token, it is locked to the Recipient that you specify in the parameters. If you are having multiple Recipients sign, you will have request multiple RecipientTokens. Also note that the RecipientToken is a single use token. Once you use it, it is marked as used and if you try to reuse it, you will get an error. The RecipientToken also has a timeout (five minutes by default), so if you request a RecipientToken and try to use it ten minutes later, you will get an error.

The way to get a RecipientToken is the RequestRecipientToken API method. This method has a couple of parameters that we haven’t discussed yet, so let’s cover those and then we’ll show some code samples.

The Authentication Assertion
Part of Embedded Signing is allowing you to authenticate the Recipients who will be signing the documents. In exchange for DocuSign allowing you to do this, you have to supply DocuSign with a record referencing your authentication record, and the time, method, and domain of the authentication. The parameters are:

ClientURLs
ClientURLs are an array of urls that are used when the Signing Ceremony is completed. The Array is keyed by event codes, so you can specify different urls for different events. There are currently 10 different events, and this may increase in the future. The exhaustive list is always specified in the API Documentation, but here is the current list (August 2010):

Since there are different event codes, you can decide to use different pages on your site for each event, or you can use a single url with different parameters to indicate which event occurred. This latter method is usually employed just to reduce the amount of code that you maintain in your application.

ClientURLs and Security.
Although DocuSign is using these urls to signal your application, you should always confirm events by checking the status of the transaction whenever you receive one of these events. This is because a clever attacker could determine what your ClientURLs are and attempt to spoof your application by beginning a transaction and then manually requesting the SigningComplete ClientURL which would indicate that the signing is complete when it is not. Always confirm the transaction status when you get the Callback event.

The Code
Ok, let’s look at some sample code for this.

//.NET
	string EnvelopeId = "Your EnvelopeID Here";

	// All of these three values must match an existing Recipient on the specified Envelope
	string UserName = "Test User";
	string Email = "test@docusign.com";
	string ClientUserId = "1";

	RequestRecipientTokenAuthenticationAssertion assert = new RequestRecipientTokenAuthenticationAssertion();
	assert.AssertionID = "Your AssertionID Here";
	assert.AuthenticationInstant = DateTime.Now;
	assert.AuthenticationMethod = RequestRecipientTokenAuthenticationAssertionAuthenticationMethod.Password;
	assert.SecurityDomain = "YourApp.com";

	RequestRecipientTokenClientURLs clientURLs = new RequestRecipientTokenClientURLs();

	clientURLs.OnAccessCodeFailed = "https://YourApp.com/DocuSignCallback.html?envelopeId=YourEnvelopeId&event=OnAccessCodeFailed";
	clientURLs.OnCancel = "https://YourApp.com/DocuSignCallback.html?envelopeId=YourEnvelopeId&event=OnCancel";
	clientURLs.OnDecline = "https://YourApp.com/DocuSignCallback.html?envelopeId=YourEnvelopeId&event=OnDecline";
	clientURLs.OnException = "https://YourApp.com/DocuSignCallback.html?envelopeId=YourEnvelopeId&event=OnException";
	clientURLs.OnFaxPending = "https://YourApp.com/DocuSignCallback.html?envelopeId=YourEnvelopeId&event=OnFaxPending";
	clientURLs.OnIdCheckFailed = "https://YourApp.com/DocuSignCallback.html?envelopeId=YourEnvelopeId&event=OnIdCheckFailed";
	clientURLs.OnSessionTimeout = "https://YourApp.com/DocuSignCallback.html?envelopeId=YourEnvelopeId&event=OnSessionTimeout";
	clientURLs.OnSigningComplete = "https://YourApp.com/DocuSignCallback.html?envelopeId=YourEnvelopeId&event=OnSigningComplete";
	clientURLs.OnTTLExpired = "https://YourApp.com/DocuSignCallback.html?envelopeId=YourEnvelopeId&event=OnTTLExpired";
	clientURLs.OnViewingComplete = "https://YourApp.com/DocuSignCallback.html?envelopeId=YourEnvelopeId&event=OnViewingComplete";

	// assumes apiService = preconfigured api proxy
	string RecipientToken = apiService.RequestRecipientToken(EnvelopeId,ClientUserId,UserName,Email,assert,clientURLs);

	// now we would set the iframe src attribute location to RecipientToken.

// PHP
	$RequestRecipientTokenParams = new RequestRecipientToken();
	$RequestRecipientTokenParams->EnvelopeID = "Your EnvelopeID Here" ;

	// All of these three values must match an existing Recipient on the specified Envelope
	$RequestRecipientTokenParams->Username = "Test User";
	$RequestRecipientTokenParams->Email = "test@docusign.com";
	$RequestRecipientTokenParams->ClientUserID = "1";
	//
	$RequestRecipientTokenParams->AuthenticationAssertion->AssertionID = "Your AssertionID Here";
	$RequestRecipientTokenParams->AuthenticationAssertion->AuthenticationInstant = date("Y")."-".date("m")."-".date("d")."T00:00:00.00";
	$RequestRecipientTokenParams->AuthenticationAssertion->AuthenticationMethod = "Password";
	$RequestRecipientTokenParams->AuthenticationAssertion->SecurityDomain = "YourApp.com";

	$RequestRecipientTokenParams->ClientURLs->OnAccessCodeFailed =  "https://YourApp.com/DocuSignCallback.html?envelopeId=YourEnvelopeId&event=OnAccessCodeFailed";
	$RequestRecipientTokenParams->ClientURLs->OnCancel = "https://YourApp.com/DocuSignCallback.html?envelopeId=YourEnvelopeId&event=OnCancel";
	$RequestRecipientTokenParams->ClientURLs->OnDecline =  "https://YourApp.com/DocuSignCallback.html?envelopeId=YourEnvelopeId&event=OnDecline";
	$RequestRecipientTokenParams->ClientURLs->OnException = "https://YourApp.com/DocuSignCallback.html?envelopeId=YourEnvelopeId&event=OnException";
	$RequestRecipientTokenParams->ClientURLs->OnFaxPending =  "https://YourApp.com/DocuSignCallback.html?envelopeId=YourEnvelopeId&event=OnFaxPending";
	$RequestRecipientTokenParams->ClientURLs->OnIdCheckFailed =  "https://YourApp.com/DocuSignCallback.html?envelopeId=YourEnvelopeId&event=OnIdCheckFailed";
	$RequestRecipientTokenParams->ClientURLs->OnSessionTimeout ="https://YourApp.com/DocuSignCallback.html?envelopeId=YourEnvelopeId&event=OnSessionTimeout";
	$RequestRecipientTokenParams->ClientURLs->OnSigningComplete =  "https://YourApp.com/DocuSignCallback.html?envelopeId=YourEnvelopeId&event=OnSigningComplete";
	$RequestRecipientTokenParams->ClientURLs->OnTTLExpired = "https://YourApp.com/DocuSignCallback.html?envelopeId=YourEnvelopeId&event=OnTTLExpired";
	$RequestRecipientTokenParams->ClientURLs->OnViewingComplete = "https://YourApp.com/DocuSignCallback.html?envelopeId=YourEnvelopeId&event=OnViewingComplete";

	// assumes $api = preconfigured api proxy
	$RequestRecipientTokenResponse = $api->RequestRecipientToken($RequestRecipientTokenParams);

	$RecipientToken = $RequestRecipientTokenResponse->RequestRecipientTokenResult;

	// now we would set the iframe src attribute location to $RecipientToken.

As you can see, the code is pretty straightforward. One thing to remember is that you have to use absolute, rather than relative, Urls for the ClientURLs. This is because the redirect will be evaluated against the iframe’s current url, rather than the url of your hosting page. It’s best to come up with some function to dynamically build the ClientURLs – for example, by inspecting the current hostname – rather than hardcoding them.

Now that we have the RecipientToken, we just set our iframe’s src attribute to this and let the session run. When the session is complete, the appropriate ClientURL will be loaded in the iframe. You will probably want to break out of the frame at this point – One pattern that you will see in the LoanCo and InsuranceCo samples is the use of a simple html page as the ClientURL, and then that page redirects the top frame to the appropriate page (signingreturn.php or signingreturn.aspx as appropriate) when it loads:

Then when the actual signingreturn page loads you can inspect the event and envelopeId parameters and check the status of the transaction.

That concludes our walkthrough. I highly recommend that you read the relevant sections of the official API Documentation as well – it covers all the details of the process and is the authoritative guide. And remember to check the DocuSign DevCenter if you have any questions or need additional resources.

Additional Resources

• RequestStatus code walkthrough
• Retrieving Documents code walkthrough
• DocuSign DevCenter
• Electronic Signature API Documentation

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:

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.

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.

In this electronic signature code walkthrough, we’ll cover Anchor Tabs. If you want a general overview of DocuSign Tabs, you can click for more information.

An Anchor Tab is any DocuSign Tab defined by its relative location to a string in the document’s text. To illustrate this, let’s consider the scenario of a user signing up for a new service. The user will have to sign a service contract, and this contract may change depending on where the user lives. When the contract changes, the place where the user must sign will also change – it will shift down the page as more lines are added to the contract.

If we attempt to use a Fixed Tab in this scenario, we will have to calculate the Fixed Tab location for every possible variant of the contract, and store those in our application, and then use the correct location depending on where the user lives. Clearly we don’t want to do this additional work.

The solution to this problem – Anchor Tabs. Since an Anchor Tab works by matching a string present in the document’s text, we would just need to examine the document and see if there is a suitable bit of text. Many contracts have something like “Sign Here” printed on the document, so we could use that as the anchor text, and then DocuSign would place a Signature Tab on the document everywhere it finds the text “Sign Here”.

Now, if for some reason we insert a new paragraph in the middle of the contract, and the “Sign Here” text moves down the page, the Signature Tab will follow it.

That’s the simple scenario, just to illustrate the concept. Let’s look a little deeper to examine some real implementation strategies.

The Details

Anchor Tab placement happens when your envelope is sent to DocuSign. DocuSign will parse the envelope. If it sees an Anchor Tab defined, then it will perform a Text search on the specified document. It will get the X & Y coordinates of every instance of the anchor text, and create a new Fixed Location tab using those coordinates. It does this by finding the bounding box of the anchor text (basically the rectangle containing the text) and using the Lower Right corner of the bounding box as the Lower Left corner of the Tab.

You can fine tune the position of the placed Tab by setting the X and Y offset properties of the Anchor Tab. This will simply move the Tab in the X or Y from its calculated position. You can set the Units for the offset, so it can specified in Pixels, or Inches, or Centimeters, or Millimeters. Remember that the offset will be applied to every tab generated by the Anchor Tab – so if your anchor text is found in five places, you will get five Fixed Tabs, and they will all be shifted by the offset amount.

Selecting your Anchor Text can be challenging – sometimes it’s obvious, but other times it isn’t. Remember that you can use any text as an anchor, so as long as the text is in a fixed location relative to the signature block. You should also remember that the anchor text should only be present near the signature block – If you use a common word or phrase as the anchor, you will end up with a Tab at every place that the anchor text shows up in the document.

If you can’t find good anchor text in your document, you may be able to add it. One very common solution is to edit the contract, and place text strings in every location that needs a Tab. Once entered, you change the text to the document’s background color so they are effectively invisible but still parseable. You can utilize a naming convention that will help you assign the tabs correctly. For example, a signature tab for the first recipient might be indicated by placing ‘\s1\’ at the appropriate place, and the signature tab for the co-Signer could be indicated by ‘\s2\’. Initials could be indicated by ‘\i1\’ and ‘\i2\’, optional initials by ‘\oi1\’ and so on and so forth.

If you are having trouble getting the Tab placed correctly, you can always log in to the DocuSign console and create a new envelope with your document and use the Web Tagger to create Anchor Tabs and see them positioned in real time. This exercise will familiarize you with Anchor Tabs in general.

The Anchor Tab also supports a flag, called “IgnoreIfNotPresent”, that allows you to control what DocuSign will do if it doesn’t find the anchor text in the document. If this flag is set to False, then DocuSign will throw an exception if it doesn’t find the text. If it is true, then no exception will be thrown and the envelope will be sent. This allows you to specify Anchor Tabs that will be placed if the text is found, and ignored otherwise. This can be very handy if your documents are generated dynamically and may contain optional clauses that require initials if present.

The Code

So that we know all about Anchor Tabs, let’s place a couple of them. If you read the article on Create And Send Envelope , I’m using the same code here, so this will just be adding an anchor tab to the envelope that we constructed there. We will add a tab that looks for the text “X:”, and is offset 50 pixels right and 100 pixels down. We will also specify the flag that tells DocuSign to send the envelope even if it doesn’t find the Anchor Text.

 	// .NET
	Tab tab = new Tab();
	tab.DocumentID = "1";
	tab.RecipientID = "1";
	tab.Type = TabTypeCode.SignHere;
	tab.PageNumber = "1";
	tab.AnchorTabItem = new AnchorTab();
	tab.AnchorTabItem.AnchorTabString = "X:";
	tab.AnchorTabItem.Unit = UnitTypeCode.Pixels;
	tab.AnchorTabItem.UnitSpecified = true;
	tab.AnchorTabItem.XOffset = 50;
	tab.AnchorTabItem.YOffset = 100;
	tab.IgnoreIfNotPresent = true;

 	// PHP
	$tab = new Tab();
	$tab->Type = "SignHere";
	$tab->DocumentID = "1";
	$tab->RecipientID = "1";
	$tab->PageNumber =  "1";
	$tab->AnchorTabItem->AnchorTabString = "X:";
	$tab->AnchorTabItem->Unit = "Pixels";
	$tab->AnchorTabItem->XOffset = 50;
	$tab->AnchorTabItem->YOffset = 100;
	$tab->AnchorTabItem->IgnoreIfNotPresent = true;

So that’s it. Remember, Anchor Tabs are a Tab Location option, and they can be used with any type of Tab, not just Signature Tabs. As always, if you have any questions about these API methods, please use the DocuSign DevCenter forums for assistance.

Photo by Dorron

In this walkthrough, we will cover the different methods that you can use to retrieve documents with electronic signature from DocuSign. 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.

The Documents

Once you send a DocuSign envelope, and the Recipients e-sign it, the next step is usually to retrieve the signed documents. While you can leave them in the DocuSign account, many implementors want their systems to keep copies locally. Additionally, DocuSign provides a document called the Envelope Certificate that displays key data about the signing ceremony, and this document is often kept locally along with the signed documents to provide evidence of the transaction.

RequestPDF

The first method we’ll discuss is the RequestPDF method. This method takes an EnvelopeID as a parameter, and returns a structure that contains the EnvelopeID and a PDF file. The PDF File contains the entire contents of the envelope, so if you sent in an envelope with five different documents in it, the resulting PDF will contain all five documents in order.

Here’s an example of using the RequestPDF method:

//.NET
	APIServiceSoapClient apiService = new APIServiceSoapClient();
	apiService.ClientCredentials.UserName.UserName = "Your DocuSign UserName here";
	apiService.ClientCredentials.UserName.Password = "Your DocuSign Password here";

	string envelopeID = "Some EnvelopeID";
	EnvelopePDF envPDF = apiService.RequestPDF(envelopeID);

For the php code, we are assuming that we have the wsdl file cached locally in the indicated location.

//PHP
	$api_endpoint= "https://demo.docusign.net/api/3.0/api.asmx";
	$api_wsdl = "api/APIService.wsdl";
	$api_options =  array('location'=>$api_endpoint,'trace'=>true,'features' => SOAP_SINGLE_ELEMENT_ARRAYS);
	$api = new APIService($api_wsdl, $api_options);
	$api->setCredentials("Your DocuSign UserName here", "Your DocuSign Password here");

	$RequestPDFParam = new RequestPDF();
	$RequestPDFParam->EnvelopeID = $envelopeID;
	$result = $api->RequestPDF($RequestPDFParam);
	$envPDF = $result->RequestPDFResult;

Now that you have the EnvelopePDF object, you can access the raw bytes via the EnvelopePDF.PDFBytes accessor and write them out to a file ( or a database blob field, etc)

//.NET
	System.IO.File.WriteAllBytes(AppDomain.CurrentDomain.BaseDirectory + @"\envelope.pdf", envPDF.PDFBytes);

//PHP
	file_put_contents("./envelope.pdf", $envPDF->PDFBytes);

RequestDocumentPDFs

The RequestDocumentPDFs is used when you want to get all of the Envelope’s contents back as individual documents. This is very useful when you have a package of documents that are signed and then need to be routed to different departments after signing. For example, using the Auto Insurance example, you might have an Electronic Funds Transfer authorization form in the Envelope along with the Insurance Application, and post signing you need to send the EFT form to finance and the Application to whereever Insurance applications go to. This method also includes the Envelope Certificate, so if you want this you have to use this method rather than RequestPDF.

The returned data from this call is a DocumentPDFs object, which contains the EnvelopeID and an array of DocumentPDF objects – 1 for each original document, plus the Envelope Certificate.

Assuming that you already have your API proxy setup, here’s the code:

 //.NET
	string envelopeID = "Some EnvelopeID";
	DocumentPDFs docPDFs = apiService.RequestDocumentPDFs(envelopeID);

//PHP
	$RequestDocumentPDFsParam = new RequestDocumentPDFs();
	$RequestDocumentPDFsParam->EnvelopeID = $envelopeID;
	$result = $api->RequestDocumentPDFs($RequestDocumentPDFsParam);
	$docPDFs = $result->RequestDocumentPDFsResult;

With the DocumentPDFs object, you will need to iterate the array of DocumentPDF objects, and access the PDFBytes property on each DocumentPDF. You will also see some other properties there – like ‘Name’, which will contain the name of the file when it was sent in the envelope. For the Envelope Certificate, the Name will be ‘Summary’. Remember that the name will be whatever it was set to, so if you are saving it out to the filesystem you will need to add the ‘pdf’ extension to the Name.

//.NET
	foreach (DocumentPDF doc in docPDFs.DocumentPDF)
	{
		System.IO.File.WriteAllBytes(AppDomain.CurrentDomain.BaseDirectory + @"\" + doc.Name + ".pdf", doc.PDFBytes);
	}

 //PHP
	foreach($docPDFs->DocumentPDF as $doc){
		file_put_contents("./" . $doc->Name . ".pdf", $doc->PDFBytes);
	}

You will also see a couple of properties – currently DocumentID and DocumentType – that will not be populated. This is because the DocumentPDFs object is used as the return value both for the RequestDocumentPDFs method and the RequestDocumentPDFsEx method.

RequestDocumentPDFsEx

This method is a variant of the RequestDocumentPDFs method that returns additional elements in the response. The exact elements that can be returned will change over time, so if you are using this method you need to be sure that your code won’t break if it encounters an unexpected property here. Currently the DocumentID and DocumentType properties are being returned but there may be additional elements here in the future.
Also note that these additional elements return data that would have been supplied at the time the envelope was created. If you did not specifically add this data to the envelope, it will not be there when you call this method.

Account Options

You may also have your account configured to pass back additional information in the metadata elements of the PDF file. Please see the API documentation for more information about this ( see the Rules for Using RequestDocumentPDFs on page 79).

So that’s how to get your documents back out of DocuSign. If you have trouble using these API methods, please use the DocuSign DevCenter forums for assistance.

Doug Glagola, vice president at MeridianLink, explains how DocuSign extends MeridianLink’s platform, enabling the entire process to be conducted in the cloud:

With the success financial institutions are experiencing with their investment in online lending and account opening capabilities and the millions of loans and accounts now being originated online, it seemed only natural to also finalize and close the transaction online. With DocuSign, the entire process can be conducted seamlessly in the cloud—eliminating paper, hassles and wasted time. DocuSign is the final mile in completing the loan process.

MeridianLink’s platform, an online application, instantly generates pre-qualified loan decisions for all types of consumer loans and generates new accounts for all types of deposit accounts. Commercial loan origination and deposit accounts are also available. MeridianLink’s platform fully integrates loan origination and account opening, core processing and internal banking software in almost any configuration to produce a fully paperless lending and account opening program for any financial institution. Now with the integration of DocuSign electronic signature services within the MeridianLink platform, online transactions can be originated, approved, signed and funded without interruption. DocuSign finalizes the process by offering financial institutions and borrowers the convenience to electronically sign and complete the final mile of the process all within the MeridianLink workflow.

Just as the MeridianLink platform has transformed how loans and new deposit accounts are originated and processed, electronic signatures are further transforming these transactions so they are conducted entirely in the cloud. By moving loan and deposit account document signing into the cloud, financial institutions can leverage the time and cost efficiencies of cloud computing while gaining real-time insight into the signing process. And, through the integration of the DocuSign electronic signature platform, MeridianLink financial institution customers have complete real-time visibility into the entire process.

Dave Thorpe, market director at DocuSign, explains what integrating the DocuSign electronic signature solution into the MeridianLink platform means for banks and credit unions:

More than 450 banks and credit unions have currently deployed the MeridianLink platform. With the integration of the DocuSign electronic signature service, we anticipate an accelerated adoption of the MeridianLink automated loan and account opening solution. DocuSign is excited to align with MeridianLink and we look forward to collaborating with them to further extend the power of the DocuSign electronic signature platform and the MeridianLink’s platform in streamlining the loan and account opening process, reducing costs and ensuring the continued success of our joint customers.

In this walkthrough, we’ll cover the sending of an electronic signature Envelope using the CreateAndSendEnvelope method. This is the most common method of sending a DocuSign Envelope as it does not require too much preparatory work. It requires a PDF document that you wish to get signed, some knowledge of where the signatures should go, and the name and email address of the person who should sign it. A common business scenario for this is getting an application signed – in fact, there are two sample projects in the SDK that use this scenario: LoanCo and InsuranceCo. Both of these sample apps show an end user filling out an application which is then sent to DocuSign and prepared for signature.

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.

If you have looked over the API Documentation, you might have seen the CreateAndSendEnvelope method call, and the parameters that you can pass in. There are a lot. We are going to ignore most of them, as they deal with advanced functionality, and just concentrate on the basics: Recipients, Documents, and Tabs.

The Envelope Object

First, let’s create the objects for our method call. In the PHP Code, using the proxy classes from the SDK, it looks like this:

$CreateAndSendEnvelopeParam = new CreateAndSendEnvelope();

Here’s the .NET version:

Envelope envelope = new Envelope();

Notice that the PHP class is one level higher in the hierarchy so we will end up using

$CreateAndSendEnvelopeParam->Envelope->property

whereas in .NET we will use

envelope.property

Other than that, the code samples will look very similar.

Now let’s populate these objects.

Recipients

A Recipient is someone who will participate in the Envelope Signing in some way – they may sign the documents, they may help prepare the documents, or they may be sent a copy of the documents. The most common type of Recipient is a signer.
Here’s a basic signer constructed in .NET:

	Recipient recipient = new Recipient();
	recipient.ID = "1";
	recipient.Email = "someemail@somewhere.com";
	recipient.UserName = "Some Person";
	recipient.Type = RecipientTypeCode.Signer;
	recipient.RequireIDLookup = false;

And in PHP:

	$Recipient = new Recipient();
	$Recipient->ID = "1";
	$Recipient->Email = "someemail@somewhere.com";
	$Recipient->UserName = "Some Person";
	$Recipient->Type = "Signer";
	$Recipient->RequireIDLookup = false;

Since there can be multiple recipients on an Envelope, the DocuSign API expects an array of Recipients, so we’ll put them in one:

	//.NET
	envelope.Recipients = new Recipient[1];
	envelope.Recipients[0] = recipient;

	//PHP
	$CreateAndSendEnvelopeParam->Envelope->Recipients->Recipient[] = $Recipient;

(Note the PHP hierarchy has an extra level in it – instead of using Recipients[] as you might expect, it uses Recipients->Recipient[]. This is due to the code that generated the PHP proxy objects (wsdl2php ver 0.2). If you happen to use some other code to generate your proxy objects you might see a slightly different class hierarchy. All of these code samples are using the proxy objects included in the php sample code in the SDK.)

Documents

We need a document. For this case, let’s assume that we have a PDF document available to our code, so we can read it in as a byte array;

	//.NET
	envelope.Documents = new Document[1];
	Document doc = new Document();
	doc.ID = "1";
	doc.Name = "Our Document";
	doc.PDFBytes = System.IO.File.ReadAllBytes(Server.MapPath("resources/Loan.pdf"));
	envelope.Documents[0] = doc;

	//PHP
	$CreateAndSendEnvelopeParam->Envelope->Documents->Document[0]->ID = "1";
	$CreateAndSendEnvelopeParam->Envelope->Documents->Document[0]->Name = "Document";
	$CreateAndSendEnvelopeParam->Envelope->Documents->Document[0]->PDFBytes = file_get_contents("resources/Loan.pdf");

Tabs

Now that we have a Recipient, and a Document, we need some way to express that the Recipient is supposed to sign the Document in a certain place. We do this using a Signature Tab. The tab will reference a Recipient and a Document, and provide the location of the signature.

	//.NET
	Tab tab = new Tab();
	tab.DocumentID = "1";
	tab.RecipientID = "1";
	tab.Type = TabTypeCode.SignHere;
	tab.PageNumber = "1";
	tab.XPosition = "100";
	tab.YPosition = "100";
	envelope.Tabs = new Tab[1];
	envelope.Tabs[0] = tab;

	//PHP
	$tab = new Tab();
	$tab->Type = "SignHere";
	$tab->DocumentID = "1";
	$tab->RecipientID = "1";
	$tab->PageNumber =  "1";
	$tab->XPosition = "100";
	$tab->YPosition = "100";
	$CreateAndSendEnvelopeParam->Envelope->Tabs->Tab[] = $tab;

Note that while we are using a single signature tab for this example, there are several different types of tabs available for use. As well as indicating signature locations, they can be used to indicate locations of a Recipient’s Initials, Form Field locations where Recipients can enter data, System Information, etc. You can also set Tab locations by specifying a bit of text that appears in your document, and having DocuSign place a tab at every location that text appears in your document. This technology is called “Anchor Tabs”, and will be discussed in more detail in another article.

Ready to Send?

Not quite. We have to set a couple of pieces of information on the Envelope object itself. We are going to give our Envelope a subject, so when the Recipient sees it in their inbox they will know what it is for, and we are going to provide an bit of text that will be included in the email that is sent to the Recipient – this will allow us to personalize it a bit. And finally, we will set the AccountID that the Envelope will be sent from. Since DocuSign allows users to be in multiple accounts, the AccountID is necessary to indicate which account the Envelope should be sent from.

	//.NET
	envelope.AccountId = "Your AccountID Here";
	envelope.Subject = "Sample Application";
	envelope.EmailBlurb = "You can add a personal message here.";

	//PHP
	$CreateAndSendEnvelopeParam->Envelope->AccountId = "Your AccountID Here";
	$CreateAndSendEnvelopeParam->Envelope->Subject = "Sample Application";
	$CreateAndSendEnvelopeParam->Envelope->EmailBlurb = "You can add a personal message here.";

At this point we are ready to send the envelope. When we send an envelope we get a status object (of type EnvelopeStatus) in return.
We will use our API Proxy to call the CreateAndSendEnvelope Method:

	//.NET
	APIServiceSoapClient apiService = new APIServiceSoapClient();
	apiService.ClientCredentials.UserName.UserName = "Your DocuSign UserName here";
	apiService.ClientCredentials.UserName.Password = "Your DocuSign Password here";
	EnvelopeStatus envStatus = apiService.CreateAndSendEnvelope(envelope);
	string envelopeId = envStatus.EnvelopeID;

For the php code, we are assuming that we have the wsdl file cached locally in the indicated location.

	//PHP
	$api_endpoint= "https://demo.docusign.net/api/3.0/api.asmx";
	$api_wsdl = "api/APIService.wsdl";
	$api_options =  array('location'=>$api_endpoint,'trace'=>true,'features' => SOAP_SINGLE_ELEMENT_ARRAYS);
	$api = new APIService($api_wsdl, $api_options);
	$api->setCredentials("Your DocuSign UserName here", "Your DocuSign Password here");

	$result = $api->CreateAndSendEnvelope($CreateAndSendEnvelopeParam);
	$envStatus = $result->CreateAndSendEnvelopeResult;
	$envelopeID = $envStatus->EnvelopeID;

The response from the CreateAndSendEnvelope method is an EnvelopeStatus object, which contains detailed status about the process of the envelope signing. In this example, we are grabbing the EnvelopeID property from this object so that we can store it somewhere in our own system. The EnvelopeID is the unique Identifier for this envelope in DocuSign, and there are several other API methods that will use it as a parameter – methods for requesting status, retrieving documents, voiding the envelope, etc.

At this point the envelope has been sent, and the Recipient should have gotten an email from DocuSign. This email will contain a link that will take the Recipient to the DocuSign site, and guide them through the process of signing the Document.

To get DocuSign tools and a free developer account please visit DocuSign DevCenter. To see what other developers have created on DocuSign’s electronic signature platform, take a look at DocuSign’s github e-siganture code repository.

My job? To show you the automation and extension features built into the Spring ‘10 release!

We’ve:

• extended the workflow for new types of recipients in the transaction
• added a way for recipients to collaborate on documents via markup
• added a way for you to build conditional logic for SecureFields™
• created a new way for you to launch a DocuSign envelope
• included many more features

Today I’d like to drill into the new way to launch DocuSign envelopes – the feature we call PowerForms 2.0. PowerForms have existed in DocuSign for a long time and were originally designed to enable sending a PDF form that could be filled in, eSigned, and tracked with DocuSign. With the Spring ’10 release, DocuSign PowerForms 2.0 extends this feature to allow direct launch without the PDF form in the middle of the process and before you know it, we’ve got a whole new protocol!

Previously, if you wanted to create a DocuSign envelope in response to a click on your website you had to write some server side code. While this wasn’t a big issue for a lot of people who already had some back-end systems, those with a Google Site or a pure HTML site had to extend their infrastructure. Now with PowerForms 2.0 to launch a DocuSign transaction all you need to do is create a PowerForm and copy the link to it.

You can send that link via e-mail or add it to your website. In addition to the link, you can add data or recipient information from your site to the URL and that information is inserted into the appropriate fields in the envelope. The data can be passed in the URL or in a form post.

As a proof of concept, we created a small form on a Google site that takes a few form fields and posts the data and the recipient information to a PowerForm. As a result, without any code (JavaScript or back-end code like C#, Java or PHP), a new envelope is created and we have an integrated solution.

Here is the form (you will need to map it to your own PowerForm link of course).

Which looks like:

Google Sites Screenshot

For more on the PowerForm data syntax see the PowerForms User Guide

Want to inject DocuSign’s electronic signature capabilities into your existing technology? Take a look at the DocuSign eSignature Developer Center and register here for a DocuSign Developer account for free access to the leading eSignature API and SDK!

The summer’s heating up for DocuSign’s developers, working with our API to inject eSignature capabilities into other technologies. We’ve seen some amazing integrations recently, highlighted in our Featured eSign Applications. These electronic signature applications were all built using our Free eSign Development Account – you can register to get free access to the DocuSign API and SDK! Take a look at the DocuSign DevCenter – did you know that one of our talented DocuSign DevCenter developers has created and released eSignControl, a new mobile app for DocuSign? Available as an iPhone app and iPad app, eSignControl enables users to track and report results as well as send and sign documents.

With eSignControl, available for iPhone and iPad, you can:

• See current status and history
• Review contracts
• Correct envelopes

• Send from Google Docs, DocuSign templates (using your local address book) and your local drafts folder
• Drag / drop tags onto documents with Mobile Tagger

• Create groups of users to track
• Filter envelopes based on envelope or data fields
• Generate performance reports with totals
• Email reports

Want to learn more about DocuSign’s API and eSign developer community? Join Mike Borozdin for our weekly Developer Webinars on Thursdays – click to register!

At DocuSign, we think electronic signature and paperless processes add convenience and eliminate the need to fax, copy and file paper. From our customers, we’ve heard accounts of their clients appreciating the convenience DocuSign’s eSignature services provides. From Mike Borozdin, manager of professional services here at DocuSign, we have a story of how going paperless has changed his life:

In less than a month it’s going to be a year since I stopped storing paper. Last spring before my move from Madrona to Capitol Hill I did a bit of spring-cleaning. As I was cleaning out my closets and the attic I realized how much old and useless stuff I had. Some of my old tech toys ended up with my friends. Most of my old clothes ended up at Good Will. And then I started cleaning out my files. For a guy who has been on the bleeding edge of tech for a bit I had a surprising amount of old statements and receipts. Consolidated it was three full boxes.

During my childhood my parents told me not to lose paper. I remember carefully storing and filing my bank statements “just in case something happened.” My car was hit in the late nineties and sure enough I had a full folder of papers for a car that was totaled a decade ago. I was torn: I had an emotional attachment to my old dusty paper, yet I was too lazy to move these boxes with me. I decided that I am going to go paperless.

I decided to scan some of the most important documents from my past and have them backed up online. I promised to myself that going forward I would not store any more paper. It seemed like in the age of Internet it should be pretty easy. After all Chase already offered paperless statements and Fidelity did too. My Comcast bill could be viewed and paid online and so was AT&T’s. Those were the first steps and they took care of a lot of my paper.

This seemed like a piece of cake and I lasted without accumulating any more paper for about a month. Then I had a dentist appointment. My dentist is great when it comes to my teeth, but his assistant still writes the bills by hand and stuffs them in little blue envelopes that cost 40 cents to deliver less than a mile. My accountant insisted on sending me things via mail and the worst was healthcare. Between the Polyclinic on Broadway and Regence I must have 5 letters for every visit to the doctor.

I had to counteract this somehow. I employed two services: for anything where people wanted me to sign anything I used DocuSign and for all the paper that people wanted to send me still I created an Earth Class Mail account.

It took a little getting used to. Not for me, but for all the people that all of a sudden were shocked that I resisted their attempts to send me pages of stuff in the mail. My accountant was probably the most shocked. I kept telling her that I really don’t want my tax return sent to me. I kept reminding to send me things in a PDF file via some secure delivery service such as our own DocuSign, but she kept on trying to give me paper. Thankfully EarthClassMail would scan it in and then, if there were signatures required, I would DocuSign it and send it back to her via e-mail.

So after 5-6 months of constantly attempting to fend off the influx of paper at my door I finally ended up getting most of my important mail electronically. My life has altered a bit. I stopped going to my mailbox to see if there is anything new. The only new things were junk mail from Pizza Hut and Office Max. I tried taking that stuff out and putting it into the recycling bin but then I got lazy about that too. I stopped going to the mailbox altogether. On the eleventh month I went to clean my mailbox one more time and to my surprise it was completely clean with just a yellow note from my local post office. It read: “Your address has been marked as vacant.” According to the old paper world I might no longer exist.

Mike can track all of his necessary documents through various online services and uses DocuSign for his electronic signature needs. Congratulations to Mike for being paperless personally AND professionally!

Interested in taking a look at the DocuSign API and downloading the DocuSign SDK to integrate DocuSign into your existing technology? Take a look at the DocuSign dev center, which Mike manages, to get your FREE development account today!

Our first e-Signature developer workshop was such a success, so we’re offering another ESIGN developer workshop! Join Mike Borozdin, Manager of Professional Services, in a free electronic signature developer workshop.

Are you evaluating the DocuSign API to integrate electronic signature with you existing processes or technologies? Have you’ve heard about the DocuSign API but aren’t sure how to get started?

This free webinar will help you get started! In one hour, you’ll learn how to get set up a DocuSign .NET Sample and connect it to your DocuSign developer account. You’ll also get a brief overview of DocuSign interfaces and object model.

So when is this all happening? Wednesday, February 17th, from 1:00 – 2:00 pm PST.

Please register for the e-Signature developer workshop, get your free DocuSign Developer account and download the DocuSign SDK prior to the workshop.