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

Here's some of the common terms that 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.

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 applications to automatically send new member sign-ups. For these types of applications, you should use the legacy authentication header.

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, you should use the Authorization Code and Implicit grant types.

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.

DocuSign CONNECT: Send real-time data updates to external applications

DocuSign Connect is a separate module that can be used to send real-time updates to external applications. Configured through your account preferences, you can setup a URL that receives http POSTs from the DocuSign system and logic at that endpoint to parse what events just occurred (i.e. document signed, declined, etc.) instead of constantly polling the API for status updates. You can also use DocuSign Connect to retrieved the completed documents themselves.

Additional features

The above features are popular ones but are by no means the only features available. For instance, did you know you can use custom branding during sending, signing, or other workflows? There's also things like Template Matching, Bulk Sending, Data Validation, Reminders & Expirations, Document Visibility, PDF Form Field Conversion, Document Retention, Advanced Corrections, and much more. One good way of discovering additional features is to read the API Reference Guides, you can also review our general product features page.

See a Live Example

Visit a sample mortgage website to explore embedded signing examples.

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. Request a signature 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

Use the Envelopes: create method to create an envelope with at least one document and one recipient, plus any optional information such as tabs. You will need your accountId to create the envelope, which you can copy from your sandbox profile menu when logged in.

To create an envelope send an http POST request to:

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

Use an envelope definition similar to the following for the request body:

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

The status property must be set to sent otherwise the envelope will be saved as a draft. For simplicity this example uses fixed tab positioning to place one signature tab, see tab locations and positioning for alternative placement methods.

SEND SIGNATURE REQUEST

5. eSign a document through your app

Follow these three steps to add document signing directly to your app. The source code is available at the end of the walkthrough.

[1] Retrieve your Account URL

First you need to retrieve your Account URL, which is needed to create envelopes and access other platform features.

This example uses the custom X-DocuSign-Authentication header, which is typically used by service integrations, to authenticate each API request. If you are instead building a user application where each of your end-users will authenticate with DocuSign the Authorization Grant or Implicit Grant auth flows are recommended. In this case you may replace the X-DocuSign-Authentication header with an Authorization: bearer token header.

Use the Authentication: login API to retrieve your baseUrl. This method takes three parameters: a DocuSign username, password, and integrator key. Use the same credentials you used when you created your developer sandbox.

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

[2] Create Envelope with 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 when you add the recipient you will also need to set their clientUserId property. Setting the clientUserId to a non-null value tells the DocuSign system this particular recipient will access the envelope through an embedded view, instead of an email-based workflow.

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. Make sure to set the envelope's status to sent once again.

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] Request Recipient View (Signing URL)

To open the recipient (or signer) view of an envelope we just need to create a signing URL and load it in an iFrame or Webview. The key here is that we must provide the same exact recipient information that we used in the previous step when we created the Envelope. For example, we must provide the same recipient email, name, recipientId, and clientUserId combo that we used in the previous step.

We also need to provide two other values to create the signing URL: a returnUrl and an authenticationMethod, which both take strings. The returnUrl is where the signer is redirected to once they are done signing. The authenticationMethod is an enumerated value used to help identify how the recipient verified their identity.

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. Here we just set the authenticationMethod to email to indicate basic authentication was used.

After running the above code all we simply need to do is load the signingUrl value in an iFrame if implementing a web solution or a Webview if implementing a mobile solution. DocuSign recommends not using an iFrame on mobile due to space requirements and other issues.

Note that the returnUrl that you provide will have a query parameter appended to it once the redirect occurs. This is used to determine what action the recipient took. For instance, if the recipient signed the document the URL would look like:

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

Or the recipient might have declined to sign the document, in which case the redirect URL would look like:

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

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

Source Code

Go Live with a Streamlined Certification Process

DocuSign takes security seriously, as a result we require all integrations go through our API Certification process for production API access. During API Certification we examine test transactions sent through your developer sandbox and ensure they adhere to platform rules and limits in place in production. API Certification is included with all API Plans at no additional cost, and the process usually takes 1-2 business days.

SDKs

DocuSign Supported

Community Supported

REST Libraries

Java
JavaScript

SOAP Libraries

Ruby
Objective-C
PHP
DocuSign CONNECT

Modules

DocuSign Connect (Webhooks)

The DocuSign Connect - aka webhooks - service enables the sending of real-time data updates to external applications. In other words, instead of polling the DocuSign platform for status and other real-time information, to which there are API rules and call limits in place, you can use DocuSign Connect to push events out to your app or website the instant they occur. DocuSign Connect can also be used to retrieve the completed documents themselves and the associated form field data.

Download the DocuSign Connect Service Guide

Event Notifications

In addition to DocuSign Connect, which is configured at the account level, you can configure one-off webhooks for individual envelopes using the eventNotification object. This optional envelope element can be configured to send secure messages to a specified URL when the envelope or recipient changes status. For more information on configuring event notifications for your envelopes please see our API Docs and also check out the event notification API recipe.

Go Live with Your DocuSign Integration

To start sending 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.

API Certification Requirements

The following API Certification requirements are in place for both customers and partners:

  • Developer sandbox
  • Integrator Key (client_id)
  • 20+ Test Transactions
  • DocuSign API Plan or User-Edition

You must be an Administrator of the production account you are trying to go live with. If you are integrating on behalf of a client or customer and you are not an Administrator in their production account then the client or customer will need to complete the go live form below.

20+ Test Transactions

When you submit to go live you will need to provide a time window during which you have sent at least 20 test transactions through your sandbox account using your Integrator Key. If you have created multiple Integrator Keys you will need to select one to run your tests with and promote to your live production account.

The 20 or more test transactions you send through the DocuSign demo environment are analyzed to ensure your app is in compliance with API Rules and Limits. These security and design requirements are in place in the demo and production environments to help maintain reliability and stability. Note that requests to the /login_information endpoint are not counted as transactions.

API Rules and Limits

To maintain reliability and stability within our demo (demo.docusign.net) and production (www.docusign.net) environments DocuSign has the following API rules and rate limits in place. The 20+ test transactions we examine during API Certification, as well as any transactions your app sends in the production environment, must comply with the following:

  • You may not exceed 1,000 API calls per account per hour.
  • You may not exceed 1 status request per unique envelope per 15 minutes.
  • You may not exceed 1 unique document request per unique envelope per 15 minutes.

For rules #2 and #3 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

The following document explains the API Certification process in more detail and includes a sample submission form: Requirements PDF

Go Live!

Complete the following form once you have run your 20+ test transactions and purchased a DocuSign API Plan or User-Edition:

Start API Certification Process

Post Go Live Steps

Once you have enabled an Integrator Key in your live production DocuSign account you should:

  • Point your integration to the production environment endpoints.
  • Create/Manage re-direct URIs for production (if using OAuth).
  • Ensure DocuSign Service IP addresses are allowed to access your network.
  • Ensure your system can receive emails from DocuSign's production email accounts.
  • Add users to your production DocuSign account.
  • Migrate your templates from demo to production.
  • Migrate any branding profiles you've created from demo to production.
  • If using Embedded Signing or DocuSign Connect implement security certificates.

See the Post API Certification Guide for more detailed information on each step.

For Partner Integrations, you should take advantage of the Partner Solutions Showcase.

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

In order to be listed in the Partner Solutions Showcase you must:

To submit your listing for the Partner Solutions Showcase:

There is a lot more you can do with DocuSign to market your product!

  • Build out a page on your corporate website telling prospective customers you integrate with DocuSign. DocuSign is a trusted brand, and being a certified partner is something to be proud of!
  • Do a press release announcing your joint integration with DocuSign.
  • Attend a DocuSign event, such as our yearly Momentum conference. Whether you attend as an attendee or as a sponsor, you will meet hundreds of like-minded, future thinking prospects who are looking for a solution just like yours!
  • Write a guest post for the DocuSign blog. Email IntegratedPartnerTeam@docusign.com for more information.
    - Check out what some existing partners have to say!

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

The Partner Success Content Pack contains approved DocuSign logos for use on your website, information about messaging DocuSign, options for marketing events with us, and ways to do a press release. If you have any questions related to partnerships with DocuSign please contact: IntegratedPartnerTeam@docusign.com

View the Solutions Showcase...