Code Walkthrough: Create And Send Electronic Signature Envelope

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.