Welcome to the DocuSign eSignature API

DocuSign is the most secure and globally trusted platform for adding legally binding signatures, forms and document workflows to your app or service.

The DocuSign eSignature API lets you:

  • Send electronic signature requests
  • eSign documents through your app
  • Automate forms and form-field data
  • Track documents in real-time
  • Enforce multi-factor authentication
  • More...

How to use the eSignature API:

  1. Create your developer sandbox and generate an Integrator Key
  2. Integrate and test the DocuSign API within your app or website
  3. Purchase an API Plan and enable your Integrator Key

Common Terms

Some common terms you will see mentioned throughout this site:

Document

A digital file that contains content to be reviewed and/or signed or initialed by one or more recipients. Documents are always encrypted while stored in the system and can be supplied through client devices, cloud storage systems, or additional document sources. DocuSign accepts almost all document types - for example .pdf, .docx, .rtf, .png - and you can store multiple documents in a single envelope.

Envelope

An envelope is a container or "package" that is used to send documents to recipients and manage transactions. Envelopes have statuses (i.e. sent, delivered, completed, voided) and typically contain documents, recipients, and tabs. They also contain information about the sender and timestamps that indicate the progress of the delivery procedure. When an envelope is completed the DocuSign platform automatically generates a Certificate of Completion which details the full audit history of the transaction.

Recipient

Someone who receives an envelope and, depending on the settings, can sign the documents or add information where indicated by tabs. Recipients do not need a DocuSign account to sign or participate in transactions, and there are seven (7) different recipient types available in the platform. When you embed document signing into your UI your recipients are known as embedded recipients; users who sign through the DocuSign website are known as remote recipients.

Tab

A DocuSign Tab - also called a Field or Tag - are used in several ways. First they are used to indicate to a recipient where a signature or initials are required.

 

Second, tabs can be used to show data or information to recipients, such as dates, company names, titles, etc.

  

Third, tabs may be used as editable information fields where signers can add data to a document.

Template

A pre-set "cookie-cutter" envelope with specific documents, set recipient roles, tabs, and other business logic. Templates are great for any DocuSign workflow you do repeatedly- like sending the same document to different recipients for example. Templates can be simple one signer, one document workflows or they can be more complex transactions with multiple recipients, documents, tabs, and more. Additionally, Composite Templates allow you to easily combine multiple templates into a single envelope.

Sandbox

Sandbox accounts - also called demo or developer accounts - let you test our APIs for free. They are also the only place where you can create an Integrator Key, which is needed to go live. Sandbox accounts operate in the DocuSign demo environment, which is identical to production except that documents sent through demo are not legally binding and have test stamps on them. Sandbox accounts do not expire and have enterprise level features enabled so you can test everything out before going live.

Integrator Key

An Integrator Key - also called a client_id - is a unique identifier that serves two purposes. First it is used to identify your app. Second, it can be used as your client_id during OAuth authorization flows. Integrator keys are created through your sandbox admin menu and they are needed to authenticate your API calls. When you are ready to go live with your integration you will select one of your sandbox integrator keys to enable in your live production account.

User Application

A user application is a client that authenticates every end user with DocuSign. These applications are typically web services, mobile applications, or desktop programs that authenticate individual users on the DocuSign platform. Once authenticated, users give consent for the application to display, send, or sign envelopes from their account. For user applications the OAuth2 auth flows are recommended.

Service Integration

A service integration is a service that integrates directly with a DocuSign account. This kind of integration is typically reserved for backend services that authenticate on the DocuSign platform, without the involvement of an end user. For example, a backend application could be integrated into a line of business application to automatically send new member sign-ups. For service integrations the custom X-DocuSign-Authentication header is recommended.

Features

DocuSign's industry leading features and functionality can be integrated into any website, app, or embedded system that can make http requests.

Templates: Create standard envelopes with pre-defined requirements

Templates help streamline the sending process when you frequently send the same or similar documents. For instance, you have a document that you need approved by your manager and their boss once a week. Or you have a standard sign-up form on your website for new users. In both cases Templates can save you time, eliminate errors, and improve efficiency.

Embedding: Initiate workflows directly within your app or website

With Embedding you can seamlessly integrate DocuSign functionality into your app or website, allowing users to send and sign documents instantly instead of using email. With Embedding your users won’t even know they’ve left your website or app, and they won't have to wait for any emails to arrive to initiate workflows.

Recipients: Set specific roles and parameters with pre-defined recipient types

There are seven different types of Recipients you may add to your envelopes. They are: Agents, Carbon Copies, Certified Deliveries, Editors, In Person Signers, Intermediaries, and Signers. Every tab that you add to your documents (such as sign here tabs, initial, etc.) is specific to a given recipient.

Tabs (aka Tags or Fields): Define the actions to be taken by recipients

The DocuSign platform supports many different tab types and features. You can add signature, initial and information tabs to help your signers know precisely what actions you want them to take, where in the document you want them to sign, initial or add information, and in what order. You can also do things like pre-populate tabs with data, use calculated or conditional fields, and much more.

Send On Behalf Of (SOBO): Allow a user to Send API requests on behalf of another user

With SOBO you have the ability to send API requests on behalf of other users in the same account. For instance if you have an account with two users (let’s say Bob and Sally) with the right permissions enabled Bob could send a signature request on behalf of Sally. To the recipient who receives the signature request it would look like Sally sent it, even though was actually Bob who made the API call.

Additional features

There are many more features available such as Reminders & Expirations, Custom Branding, Bulk Sending, Data Validation, Document Visibility, PDF Form Field Conversion, Document Retention, and Advanced Corrections.

One method for discovering new features is by reviewing the various pages available in the admin console of your sandbox. You can also search the API Docs or the general product features pages.

See a Live Example

Visit a sample mortgage website which illustrates the embedded signing workflow.

Quick Start for the DocuSign eSignature API

Follow these steps to start sending signature requests and eSigning documents in minutes...

  1. Create a free developer sandbox
  2. Generate an integrator key
  3. Edit integrator key settings
  4. Send a signature request via email
  5. eSign a document through your app

1. Create Your Developer Sandbox

Developer sandboxes are free, they don't expire, and they have access to enterprise level features. Documents sent in the demo environment are not legally binding and have testing watermarks on them.

Create Free Dev Sandbox

2. Generate your Integrator Key

An Integrator Key identifies your app and is also used as your client_id during OAuth token requests. When you are ready to go live with your integration you will select one of your Integrator Keys from your sandbox to enable in your live production account, see the go live section for more info.

To generate an integrator key login to your sandbox, click the profile icon in the top right, and select Go To Admin.

Preferences

On the lower left side of the Admin Console select API and Keys then click the Add Integrator Key button:

client_id authentication key

Enter a description and click ADD to create a new Integrator Key. This same value is used as your client_id during the OAuth authorization flow.

3. Edit Your Integrator Key

If you are building a service integration you can skip this step. If you are building a user application the OAuth Authorization Code Grant and Implicit Grant authorization methods are recommended, which require a Redirect URI to be added. If using the Authorization Code Grant you must also create a secret key.

oauth client id and redirect URI

If you're building a mobile or client application then select This is a mobile app. Hit SAVE and you're ready to start testing the APIs!

4. Send an electronic signature request via email

Next use the API Explorer to call the Envelopes: create API. To make the request you need an accountId, which you can copy from your sandbox profile menu. An authentication header is also needed, which the API Explorer will handle for you.

To create an envelope send an http POST request to:

https://demo.docusign.net/restApi/v2/accounts/{accountId}/envelopes

With the following envelope definition as the request body:

{
    "status": "sent",
    "emailSubject": "Request a signature via email example",
    "documents": [{
        "documentId": "1",
        "name": "contract.pdf",
        "documentBase64": "base64 encoded bytes..."
    }],
    "recipients": {
        "signers": [{
            "name": "[YOUR NAME]",
            "email": "[YOUR EMAIL ADDRESS]",
            "recipientId": "1",
            "tabs": {
                "signHereTabs": [{
                    "xPosition": "25",
                    "yPosition": "50",
                    "documentId": "1",
                    "pageNumber": "1"
                }]
            }
        }]
    }
}

SEND SIGNATURE REQUEST

5. eSign a document through your app

Now let's generate a secure signing link that you can use to sign a document through your UI. This workflow is also called embedded signing, or the recipient view of an envelope.

[1] Get your Account URL

First you need to retrieve your Account URL, which is needed to create and send envelopes.

This example uses the custom X-DocuSign-Authentication header, which is typically used by service integrations, to authenticate each API request. User applications should use the Authorization Grant or Implicit Grant auth flows. In that case you may replace the X-DocuSign-Authentication header with an Authorization: bearer token header. See auth overview for more info.

Service Integrations can use the Authentication: login API to retrieve the account's baseUrl, as is shown in the code below. User applications should use the User Info endpoint to retrieve the account URL. Note that if using the User Info endpoint the account URL is named base_uri (instead of baseUrl).

It is ok to persist your account URL for testing purposes however make sure your integration does not skip this step when you go live since your production account endpoint will be different.

[2] Create Envelope with an Embedded Recipient

The next step is to create an envelope identical to the envelope you created through the API Explorer except for one key difference. This time you will also need to set the clientUserId property on your recipient to designate them as an embedded signer.

Whatever value you set for the clientUserId you must remember for the next and final step, where we generate the recipient view (signing URL) of the envelope. Note that we set the envelope's status to sent since you cannot generate the recipient view of a draft envelope.

The above code creates an envelope with one embedded recipient, one document, and one signHere tab arbitrarily located at 100 pixels right and 150 pixels down from the top left corner of the document. Since we set the status property to sent the envelope is active and ready to be signed, the next step is to create the recipient view of the envelope.

[3] Create Recipient View (Embedded Signing)

The last step is to generate a recipient signing URL (aka recipient view) of the envelope and load through a redirect or webview. Based on your integration type framing might be ok, see optimizing embedding for more info. The key here is that you can only generate a signing URL for a recipient who has their clientUserId property set. The envelope must also be in sent status.

We also must provide two values to generate the signing view- a returnUrl and an authenticationMethod, which both take strings. The returnUrl is where the signer will be redirected to once they are done signing. The authenticationMethod is an enumerated value used to help identify how the recipient authenticated through your integration. Additionally, the authenticationMethod goes into the envelope's Certificate of Completion (CoC) - a PDF that is automatically generated for every envelope - once the signing is complete.

The result of this API is a custom signing URL that your app can then redirect to or load in an webview to let your recipients eSign documents. The signing URL takes the form of:

{
    "uri": "https://demo.docusign.net/Signing/startinsession.aspx?t=fd6b9e60-e6f6-4260-a9fc-1f4d2e1973d1&pei=d1cf4bea-1b78-47ea-b372-746678e3679f"
}

Once signing is complete and the redirect occurs the returnUrl will have a query parameter appended to it which indicates the action the recipient took. For instance, if the recipient signed the document the query parameter would look like:

https://www.docusign.com/developer-center?event=signing_complete

Your app can then parse this parameter to determine what action the recipient took and handle accordingly.

Download Sample Code

You can download the (minimal) sample code for this tutorial here:

Source Code

SDKs

DocuSign provides the following open source SDKs that can be used to easily enable eSignature and DTM functionality in your apps and websites.

eSignature REST API Libraries

eSignature SOAP API Libraries

Webhooks

The DocuSign platforms supports Webhooks, which let you POST messages to a custom URL when things happen. For example, you can configure a webhook to send a notification when a document is signed.

The use of webhooks is encouraged since they help limit the number of API requests your integration makes, to which there are API Rules and Limits in place.

DocuSign Connect

The DocuSign Connect module lets you configure webhooks for envelope events and recipient actions for some or all users in your account. It can also be used to transport the completed documents back to your app or website and to retrieve any form field data entered by your recipients.

DocuSign Connect can be accessed through the admin console and is enabled in all developer sandboxes for testing.

webhook post callback

Note that DocuSign Connect is not available on all production account plans, please see our pricing pages for more info. You can also download the DocuSign Connect Service Guide.

Event Notifications

You can configure webhooks on a per envelope basis by using the eventNotification object, which is available at the root level of the envelope definition. Event notifications are available on all plans that include API access.

For example, to configure a webhook that triggers when an envelope is completed the following event notification could be used:

{
   "eventNotification": {
        "url": "http://yourappname/callback",
        "includeCertificateOfCompletion": "false",
        "includeDocuments": "true",
        "includeDocumentFields": "true",
        "requireAcknowledgment": "true",
        "envelopeEvents": [{
           "envelopeEventStatusCode": "completed",
        }]
   }
}

To learn more about webhooks through event notifications see the event notification API recipe or search our API Docs.

Go Live with Your DocuSign Integration

To start sending and signing legally binding signature requests through your app you will need to promote one of your sandbox Integrator Keys to a live production account. This is done through our quick but critical API Certification process.

Requirements

To access production API endpoints you need:

You must be an Administrator of the production account you are promoting the Integrator Key to. If you are integrating on behalf of a client and you are not an Administrator in their production account then the client will need to complete the go live form.

20+ Test Transactions

To promote an Integrator Key from a sandbox account to a live production account you first need to run 20 or more test transactions under that key. DocuSign then analyzes those transactions to ensure they are in compliance with API Rules and Limits before enabling the key in the production environment. Note that if you have created multiple Integrator Keys you will need to select one (or create a new key) to promote to your live production account.

These 20 test transactions do not need to all be create and send envelope requests but rather can be requests to generate signing URLs, requests to download document(s), and so on. For instance, all five of the following API requests are considered transactions:

POST /accounts/12345/envelopes
POST /accounts/12345/envelopes/AAA/views/recipient
GET  /accounts/12345/envelopes/AAA/documents/1
PUT  /accounts/12345/envelopes/BBB
GET  /accounts/12345/envelopes/BBB/recipients

API Rules and Limits

To maintain reliability and stability within our demo and production environments DocuSign has the following API rules and rate limits in place:

  • You may not exceed 1,000 API requests per account per hour.
  • You may not exceed 1 GET request per unique envelope per 15 minutes.

The following REST and SOAP calls qualify as status or document requests:

  • REST API: GET /accounts/{accountId}/envelopes/...
  • SOAP API: RequestStatus, RequestStatusEx, RequestStatuses, RequestStatusesEx,RequestPDF and RequestDocumentPDFs

For example, the following set of requests are in violation of API rules since more than 1 GET request is made on envelope AAA within 15 minutes:

[12:00:00] POST /accounts/12345/envelopes
[12:01:00] GET  /accounts/12345/envelopes/AAA 
[12:02:00] POST /accounts/12345/envelopes
[12:03:00] GET  /accounts/12345/envelopes/BBB
[12:04:00] GET  /accounts/12345/envelopes/AAA *

The following transactions also violate API rules due to the repeated GET requests to the first document and second recipient:

[12:00:00] POST /accounts/12345/envelopes
[12:01:00] GET  /accounts/12345/envelopes/AAA/documents/1
[12:02:00] GET  /accounts/12345/envelopes/AAA/recipients/2
[12:03:00] POST /accounts/12345/envelopes
[12:04:00] GET  /accounts/12345/envelopes/AAA/documents/1 *
[12:05:00] GET  /accounts/12345/envelopes/AAA/recipients/2 *

However the following set of requests comply with API rules and limits and would not be flagged by the platform:

[12:00:00] POST /accounts/12345/envelopes
[12:01:00] GET  /accounts/12345/envelopes/AAA
[12:16:00] GET  /accounts/12345/envelopes/AAA
[12:17:00] GET  /accounts/12345/envelopes/AAA/documents/1 
[12:32:00] GET  /accounts/12345/envelopes/AAA/documents/1 
[12:40:00] PUT  /accounts/12345/envelopes/AAA/recipients/1
[12:41:00] PUT  /accounts/12345/envelopes/AAA/recipients/1 

DocuSign recommends using Webhooks to help avoid excessive API requests.

Go Live!

Complete the following form to promote one of your Integrator Keys to a live production account:

Start API Certification Process

Post Go Live

Once you have successfully gone live and your Integrator Key has access to the production environment the following steps are recommended:

  • Point your integration to the production environment endpoints.
  • Create/Manage re-direct URIs for production (if using OAuth).
  • Migrate users, templates, and other settings from demo to production.

Point to Production API Endpoints

The first step to take once your Integrator Key is live is to point your integration to production environment endpoints. The exact URLs will differ based on the authentication and API protocol (REST or SOAP) that you are using.

REST API Integrations

If you are using the REST API and have built a user application that uses OAuth2 update your authentication endpoint from

https://account-d.docusign.com

to

https://account.docusign.com

Service Integrations that use the custom X-DocuSign-Authentication header must update their login endpoint from

https://demo.docusign.net/restapi/v2/login_information

to

https://www.docusign.net/restapi/v2/login_information
SOAP API Integrations

If your integration uses SOAP simply update your API service endpoints from demo to www like

https://www.docusign.net/api/3.0/dsapi.asmx

If using the Account Management or Credential services make sure to update those endpoints as well.

Create/Manage Production Re-Direct URIs and Client Secrets

If your integration uses the Authorization Code Grant or Implicit Grant auth flows you will need to edit your key's Redirect URIs through the API and Keys page of your production admin console. If using Authorization Code Grant you also need to create client secret(s). This is the same process we followed in step 3 of the Quickstart except now you want to make these changes to the Integrator Key in your live production account.

Migrate Users, Templates, and Settings to Production

Next step is to add users to your production account either through the admin console or through the API. The same is true for any templates you want to move to production. You should also double check you have all the same account settings and options enabled in your production account that have turned on your sandbox. Note that sandbox accounts have Enterprise level features enabled so make sure you've selected the right API Plan.

Lastly, if you are a Partner you should take advantage of the Partner Solutions Showcase.

Got Questions?

If you have questions about the go live process or are running into issues feel free to email us at apicertifications@docusign.com.

Solutions Showcase

What is the Partner Solutions Showcase?

  • The Partner Solutions Showcase is a collection of applications found across several different industries and categories that incorporate DocuSign eSignature functionality into their solutions
  • As a partner, your Partner Solutions Showcase listing is a great way to drive traffic to your website and raise your company’s brand awareness amongst DocuSign’s customers and partners

- To learn more about becoming a partner, sign up here!

To submit your listing for the Partner Solutions Showcase:

In order to help make these activities easier for you, as a Certified Partner, you have access to our Partner Success Content Pack.

View the Solutions Showcase...