Welcome to the DocuSign API

DocuSign is the most secure and globally trusted platform for adding legally binding signatures, forms and document workflows to your app or service. With the DocuSign API you get the flexibility and control to scale from simple eSignature integrations to complex enterprise applications.

Using the DocuSign APIs you can:

  • Request legally binding signatures on virtually any type of document
  • Embed the signing or sending workflow into your UI
  • Track documents in real-time
  • Retrieve form-field data
  • Enforce multi-factor recipient authentication
  • Much more...

How to use the API:

  1. Create your developer sandbox and generate an Integrator Key
  2. Integrate and test the DocuSign API within your app or website
  3. Complete the quick API Certification, purchase an API Plan, and go live

Common Terms

Before we get started let's review some of the common terms that you will see mentioned throughout this site:

Envelope

This represents a container used to send documents to recipients. The envelope carries information about the sender and timestamps to indicate the progress of the delivery procedure. It can contain collections of Documents, Tabs and Recipients and is analogous to a physical envelope.

Document

A document that is to be delivered, representing the content to be reviewed and/or signed by one or more recipients. Documents have names and are always encrypted while stored in the system.

Tab or Tag

This represents a DocuSign Tab (also known as a Tag or Stick-eTab® ) on a document. It is used in several ways: First, it is 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.

Recipient

Someone who receives the envelope and, depending on the settings, can sign (or initial) the documents or can add information where indicated by tabs. There are currently 7 different recipient types in the DocuSign platform, see the Features section for more information.

Template

A pre-set envelope with specific documents, set recipient roles, recipient routing order, recipient authentication, signing tabs and information fields. Templates can also contain set signing instructions for the document and signature attachment requests. Templates can be set to allow the sender to make some changes before sending the envelope.

Integrator Key

An Integrator Key is a unique identifier for each DocuSign integration. It is used (and required) for all API calls to any DocuSign service. An Integrator Key is required for all integrations, and if you want to move to Production (make calls to www.docusign.net) you also must get Certified with DocuSign. See the Quick Start section for creating your Integrator Key and the Go Live section for information on Certification.

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.

Stick-eTabs® (Tabs): Define the actions to be taken by recipients

When you are tagging your documents before sending them out you have numerous tab types at your disposal that you can add for your recipients. You can add signature, initial and other 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, have calculated fields and dates, have conditional fields, and 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

The steps below show you how to create your developer sandbox and Integrator Key so you can start making API calls in the DocuSign Demo environment. Documents sent through Demo are not legally binding and have stamps on them indicating they are tests.

1: Create Your Developer Sandbox

Developer sandboxes are completely free, they never expire, and we give you access to enterprise level features.

Create Free Dev Sandbox

2. Generate your integrator key

An Integrator Key (or API Key) is a GUID that is used to identify your integration and is needed to authenticate your API calls. To generate your key click the Login to Sandbox button to the right or navigate to https://demo.docusign.net and login, then click the profile icon in the top right of the console.

From the drop down menu select Go To Admin.

Preferences

Once in the Admin Console select API and Keys on the lower left side of the screen then click the Add Integrator Key button.

Get Demo Integrator Key

Enter a description for your key click Add and a GUID will be generated, which is your Integrator Key.

3. Try Examples

Request a Signature

This quickstart shows you how to request a signature on a document. The recipient receives an email that lets them initiate the signing process through the DocuSign Website. Advantages are that recipients do not need to install any software and they can sign using any web browser on any device.

Login

The first API call every integration must make is the Login call. The Login call is used to authenticate against the API and retrieve your baseUrl – which is needed to make signature requests and other API calls.

To make the Login call we must provide three values: a DocuSign username, password, and integrator key. Use the same credentials you used when you created your developer sandbox.

Note that you only need to make the Login() call for users who wish to create and send signature requests – signers do not need a DocuSign account and signing is always free.

Create & Send Envelope

To send a signature request we must create an Envelope. Envelopes are packages that contain Documents, Recipients, Tabs, and more. For simplicity we will create an envelope with just one document, one recipient (signer), and one SignHere tab.

In this example we use Absolute positioning to place the tab on the document. You can also specify tab locations using the Anchor Tagging feature or through PDF form fields.

The above code places a signature tab 100 pixels right and 150 pixels down from the top left corner of the first page of your document, which means it might cover document text based on the file you test with. We encourage you to alter the tab settings and observe the results.

Note that if you do not specify any tabs in your request it becomes a Free Form signing experience, which means the recipient decides where to sign the document.

Another aspect to note is the status property which can take one of two values: sent or created. A value of sent immediately sends the signature request, a value of created saves the request as a draft in your account.

Download

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

Source Code

Embedded Signing

This quickstart shows you how to embed document signing directly into your website or app. This is done by opening a custom signing URL in an iFrame for web or Webview for mobile. Advantages with Embedded Signing are that your users do not need to context-switch out of your UI and wait for an email to arrive to sign documents.

Login

The first API call every integration must make is the Login call. The Login call is used to authenticate against the API and retrieve your baseUrl – which is needed to make signature requests and other API calls.

To make the Login call we must provide three values: a DocuSign username, password, and integrator key. Use the same credentials you used when you created your developer sandbox.

Note that you only need to make the Login() call for users who wish to create and send signature requests – signers do not need a DocuSign account and signing is always free.

Create Envelope with Embedded Recipient

To send a signature request we must create an Envelope. Envelopes are packages that contain Documents, Recipients, Tabs, and more. In this example we will create an envelope with just one document, one recipient (signer), and one SignHere tab.

The clientUserId Property

To designate a recipient as an Embedded recipient we must set their clientUserId property, which takes a string. Setting this property tells the DocuSign system that this particular recipient will sign in an Embedded workflow, instead of an email-based workflow.

Note that whatever value we use we must remember this value for the last step, where we request the signing URL for the embedded recipient. Just like the request a signature quickstart we will use absolute positioning to place the tab on the document, and we also set the envelope's status to sent.

The above code creates an envelope with one embedded recipient (since we set the clientUserId property), one document, and one signHere tab 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, now we just need to create the recipient view of the envelope.

Request Recipient View (aka 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 Step 2.

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 an API Certification process before being enabled in the production environment. During API Certification we check your integration for security vulnerabilities and ensure it adheres to platform rules and limits. API Certification is included with all API Plans at no additional cost, and the process usually takes 1-2 days.

Certification Requirements

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 refer to the API Reference Guide and also check out the event notification API recipe.

Ready to put your app or website into Production?

Go Live

Go Live with Your DocuSign Integration

To have your Integrator Key enabled in the production environment you must complete the API Certification process. During this quick but critical process we review your integration for potential security risks and ensure it adheres to API rules and limits. The process usually takes 1-2 days.

The following section provides information including certification requirements, introduces our available API Plans (Certification is included at no additional cost), and explains how to get listed in the DocuSign Solutions Showcase.

Quick links:

API Certification

Please review the following requirements guide prior to starting the API Certification process:

Certification Requirements

API Rules and Limits

To maintain reliability and stability within our demo (demo.docusign.net) and production (www.docusign.net) environments DocuSign has API rules and rate limits in place. All DocuSign integrations must be in compliance with the following platform rules:

  • 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.

To see which REST and SOAP calls qualify as status or document requests refer to the Certification Requirements. For additional questions regarding the API Certification process please reach out to your DocuSign Account Manager or e-mail apicertifications@docusign.com.

Does Certification Cost Anything?

API Certification is included with all available API Plans at no additional cost.

How Do I Start the Process?

To begin the process you'll need an Integrator Key from your developer sandbox, an API Plan or Enterprise edition of DocuSign, and 20+ test transactions completed in the demo environment, among other requirements. If you have created multiple Integrator Keys you must select one to certify with. Please refer to the Certification Requirements above for a complete list of requirements and a sample certification checklist.

Start API Certification Process

Post Certification Steps

Note that the Integrator Key you certified will not be visible through your production account. Among other considerations, DocuSign recommends the following post certification steps:

  • Point your integration to the production environment endpoints.
  • 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.

For detailed information on each of these steps please refer to the following guide:

Post API Certification Guide

If you have built a Partner Integration, please note that you must call GetLoginInformation to locate the desired accountID and baseURL. This call is available in both the REST & SOAP API.

For Customer Integrations that are not using multiple DocuSign AccountIDs, the baseURL can be fetched and then persisted. For Partner Integrations, it is an important part of the partnership to be listed in DocuSign's Partner Solutions Showcase.

Solution 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 Solution Showcase...