Signature Request

In this example we will cover requesting an electronic signature, which is done by sending an 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 document that you wish to get eSigned, some knowledge of where the signatures should go, and the name and email address of the person who should sign it. 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 SOAP API Reference you might have seen there are many parameters you can pass to the CreateAndSendEnvelope method. 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.

Since there can be multiple recipients on an Envelope, the Docusign API expects an array of Recipients, so we’ll put them in one, as shown in the second gist to the right.

(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.)

Recipient recipient = new Recipient();
recipient.ID = "1";
recipient.Email = "{USER_EMAIL}";
recipient.UserName = "{USER_FULLNAME}";
recipient.Type = RecipientTypeCode.Signer;
recipient.RequireIDLookup = false;

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

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.

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;

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.

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.

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;

Are you 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.

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. For the php code, we are assuming that we have the wsdl file cached locally in the indicated location.

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 eSigning the Document.

envelope.AccountId = "{ACCOUNT_ID}";
envelope.Subject = "Sample Application";
envelope.EmailBlurb = "You can add a personal message here.";

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

Download source code

You can download the source code for this example and all other code examples from GitHub:

Source code