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

API Quick Start

Follow these steps to start sending and signing 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 enterprise level features enabled. 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

See a Live Example

See a sample loan app that illustrates various API workflows and features - Loanco sample app

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.

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.

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.

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

When you are ready to launch your app you will need to promote your integrator key to a live production account, learn how to quickly do that and the steps you should take once your key is live.

Requirements

To access DocuSign's production API endpoints and start sending legally-binding signature requests through your app you need:

You need Administrator privileges to the live DocuSign account you are promoting the Integrator Key to. If you are integrating on behalf of a client you either need admin access to their live account, or the client needs admin access to your developer sandbox account, or you can connect over a web conference and have them login in real time to promote the key to their live account.

20+ Test Transactions

To promote an Integrator Key from a developer sandbox to a live production account you need at least 20 API test transactions run in the DocuSign Demo environment. DocuSign analyzes those transactions to ensure they are in compliance with API Rules and Limits before allowing the key to be enabled in production.

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. However calls to the /login_information endpoint are not counted. 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

When promoting your key to a live DocuSign account make sure you have at least 20 consecutive API transactions that are error free and do not violate API rules. Otherwise you will not be able to promote the key. As mentioned you also need Admin access to the account.

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:

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

For rule #1, every API request your app makes is counted towards the hourly limit.

For rule #2, the following REST and SOAP calls are included:

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

For example, the second API request below would be a violation of API rules since it makes a GET request on the same envelope endpoint in less than 15 minutes:

[12:00:00] GET  /accounts/12345/envelopes/AAA 
[12:10:00] GET  /accounts/12345/envelopes/AAA  (*api rule violation)

The same applies to sub resources - such as tabs, recipients, documents - within a given envelope. In the example below the second API request is once again in violation of API rules:

[12:00:00] GET  /accounts/12345/envelopes/BBB/recipients/1/tabs 
[12:10:00] GET  /accounts/12345/envelopes/BBB/recipients/1/tabs  (*api rule violation)

Note the 15 minute limit only applies to GET requests (and the corresponding SOAP calls) and that your integration can query other envelopes during the 15 minute window. You can create and send envelopes as quickly as you would like (and per your plan limits). Read more about API resource limits.

DocuSign recommends using Webhooks to help avoid excessive API requests.

Go Live!

To promote an Integrator Key from your developer sandbox to a live DocuSign account you need to complete a quick review process. The review process takes just minutes to complete, though the actual approval and promotion of your key to the live production environment may take up to 24 hours.

Step 1: Review Transactions

First login to your developer sandbox and from the profile menu select Go To Admin -> API and Keys. The following screen shows a list of your Integrator Keys:

review DocuSign API transactions

From your list of integrator keys choose the key you would like to promote and select ACTIONS -> Review Transactions. The following dialog is displayed:

API transactions review dialog

Input the date your 20+ API transactions were run in the demo environment and click REVIEW to start the automated review process. Reviews may take up to 20 minutes to complete.

Review Passed

Upon successful review the key's status will change to Review Passed. You can confirm the status by selecting ACTIONS -> Review Results:

API Transactions pass

Review Failed

If the system can not find at least 20 error-free, consecutive API transactions that do not violate API Rules and Limits the key's status will change to Review Failed. To see the most recent review results select ACTIONS -> Review Results:

api transactions review failed

If your review fails ensure you have run at least 20 consecutive API transactions that are error free and do not violate API Rules and Limits. If you have created multiple integrator keys verify you have selected the same key you've run your test transactions under. Once you have an eligible set of transactions select ACTIONS -> Resubmit for Review to start a new review.

Step 2: Select Live Account

Once your transaction review has passed the next step is to select a live DocuSign account to promote the key to. Select the key you would like to enable and click ACTIONS -> Go Live. After accepting the developer terms and conditions the following dialog is displayed (note- you may need to enable pop-ups through your browser):

live production user login

Make sure to use your live DocuSign account credentials - ie not your developer sandbox credentials - to login since they are separate systems.

Important: You need Administrator privileges to the live account to promote a given key. If you do not have any valid account memberships an error will be returned. Also note that certain account types - such as 30-day Free Trials and Freemium accounts - are not eligible for key promotion and will be grayed out in the list accounts.

Step 3: Submit for Final Approval

Once authenticated a list of your live DocuSign accounts will be displayed, select the account you wish to promote the key to:

select live account membership

If you are integrating on behalf of a client and do not have Admin access to their live DocuSign account you will need to provide the client Admin access to your developer sandbox or you have them login in real-time to the live account through an online meeting while promoting the key.

After selecting a live account the key's status will change to Pending Approval. You do not need to take any action at this point and your key should be promoted in 4-24 hours of reaching this status.

API integrator key pending approval

Integrator Key Promotion Complete

Once complete you will receive an email notification and the key's status will change to Live indicating the key is live in production!  

api integrator key live system

The key will also start displaying in the live DocuSign account it was linked to once it has been enabled. Please follow the Post Go Live steps below once your key is live.

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 demo

https://account-d.docusign.com

to production

https://account.docusign.com

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

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

to production

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

Important: Your integration must use the baseUrl that is returned in the login response for subsequent API requests in the live production system. The baseUrl value will vary depending on user and which data center their account resides in. If using one of the OAuth authorization flows this property is called base_uri instead of baseUrl.

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 go-live@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...