REST API Recipe: Request a Signature via Email


This recipe sends a signer a request by email to sign a document. The signer will be contacted by email from DocuSign to start the signing ceremony. The signer does not need an account from DocuSign before or after signing.

The signing ceremony will automatically use the signer’s local language preference as set by their browser. DocuSign automatically supports 43 languages for signing.

The signer can use her mobile phone, a tablet, or a workstation browser to sign. No app download is required. For phones and tablets, graphical signature capture is automatically enabled. (Try it on your mobile!)

Getting ready

You’ll need a DocuSign account email and password. The signing request will be sent by the account holder. You’ll also need an integration key. See Generate Your Integrator Key

How to do it

Step 1: use the login_information API end point to obtain the base URL for use in subsequent API calls, and the user’s account id. In this recipe, we’re using the first account in the response body. For a production application, it is important to enable the user to choose the account that should be used — it is not uncommon for a person’s email/password to be associated with more than one account.

Depending on your application and use case, it may be appropriate for the user to choose the account as a configuration parameter for your application, or each time your application is used.



Step 2: Send the signing request via the Envelopes::create end point. The request has several parts. The configuration object is a JSON object that instructs DocuSign to create an envelope with a single signer, and place one signature tab on the envelope's single document, located 100 pixels to the right and 100 pixels down from the top left of the document.

Create the request body, sent as a multi-part mime request. The request includes the envelope’s configuration object first, then the file.

Then send the request to the DocuSign platform. The call should return a 201 HTTP code with the newly created envelope id in the response body. Your signing request has been sent! Check your email to see the incoming signing request.


Source files

The recipe source files are available on Github: Java, C#, Objective-C, Python, PHP, and Node-JS

How it works

Authentication of the signer is always a key consideration for any signing request. In this recipe, simple email authentication is used. Many other types of authentication are available from DocuSign. Not all DocuSign account types provide all authentication options.

Since you have an account on DocuSign, your signing experience may be slightly different from an “account-less signer.” To see what an “account-less” signer will experience, use a throwaway email address from Mailinator or similar. If the signer accepts the offer for a free DocuSign account at the end of the signing ceremony, then subsequent signing requests, from the same sender, will remember some of the signer’s responses from the prior signing ceremony to provide a better user experience.