eSignature REST API

The DocuSign eSignature REST API lets you eSign documents, request signatures, and automate your forms and data. To ensure data privacy the DocuSign REST API is served over HTTPS and documents stored in DocuSign are encrypted using AES-256. Learn more about security or check real-time system status.

API Endpoints

All REST API endpoints have the following base:

https://{server}.docusign.net/restapi/v2

DocuSign hosts multiple geo-dispersed ISO 27001-certified and SSAE 16-audited data centers. For example, account holders in North America might have the following base URL:

https://na2.docusign.net/restapi/v2/accounts/{accountId}

Whereas European users might access the following base URL:

https://eu.docusign.net/restapi/v2/accounts/{accountId}

To access DocuSign workflows and resources you append URIs to your base URL. For example to send a signature request append the /envelopes URI to your base URL:

https://na2.docusign.net/restapi/v2/accounts/12345/envelopes

To retrieve your specific base URL you need to authenticate with the DocuSign platform.

Authentication

The REST API supports several authentication methods. Your application should use one of the OAuth2 authentication methods:

The REST API supports Legacy Header authentication which is easier to use while you’re learning the API, but it is not recommended for production applications.

OAuth Authentication

Once you have an OAuth2 access token, you use the authentication service’s oauth/userinfo endpoint to obtain the base URL. The request to the /oauth/userinfo endpoint looks like this. You supply the access token in the Authorization header.

GET /oauth/userinfo
Authorization: Bearer eyJ0eX...MrhIddzBAQ

A typical response looks like this:

{
  "sub": "50d89ab1-dad5-d00d-b410-92ee3110b970",
  "accounts": [
    {
      "account_id": "fe0b61a3-3b9b-cafe-b7be-4592af32aa9b",
      "is_default": true,
      "account_name": "World Wide Co",
      "base_uri": "https://demo.docusign.net"
    }
  ],
  "name": "Susan Smart",
  "given_name": "Susan",
  "family_name": "Smart",
  "email": "susan.smart@example.com"
}

Choose the account you want to use. Then concatenate that entry’s base_uri and account_id fields to create the base URL you will use to make REST API requests.

{base_uri} + "/restapi/v2/accounts/" + {account_id}

Legacy Header Authentication

To retrieve your base URL using legacy header authentication, add your username, password, and integrator key in JSON format to the X-DocuSign-Authentication http header:

curl -H 'X-DocuSign-Authentication:{"Username": "bob@example.com","Password": "xxx","IntegratorKey": "your_key"}' \
https://www.docusign.net/restapi/v2/login_information

A successful response will contain your account’s baseUrl which is needed to request signatures and eSign documents:

{
  "loginAccounts": [
    {
      "name": "John Dough",
      "accountId": "12345",
      "baseUrl": "https://na2.docusign.net/restapi/v2/accounts/12345",
      "isDefault": "true",
      "userName": "John Dough",
      "userId": "02e6fc42-0c2e-4e8e-ade1-8ed6f140daee",
      "email": "john@example.com",
      "siteDescription": ""
    }
  ]
}

Testing

You can test the DocuSign API using a developer sandbox account. Sandbox accounts operate in the demo environment, which is identical to the live production system except documents sent through demo are not legally binding.

All URLs in the demo environment have the following base:

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

To create and send a test envelope send an http POST request to:

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

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

Read more about the Envelopes: create method or see the full REST API Reference.