Requests and Responses

This topic describes how the DocuSign API handles requests and responses.

  • All requests are made in HTTPS.
  • All requests must be authenticated.
  • All requests are made through a base URL.

On this page

Quick links

Authentication and Base URLs

To make API requests you first need to authenticate. After you authenticate, you can get a base URL that to use in all subsequent requests.

Note that it is not uncommon for an authenticated user to belong to more than one account. Depending on your case, the user’s default account may be best, or your integration may allow the user or administrator to choose the account.

Authentication

Your first interaction with the DocuSign API is to authenticate. The server you use depends on the authentication method.

Authentication Method Production Server Demo Server
OAuth2 account.docusign.com account-d.docusign.com
Legacy Header www.docusign.net demo.docusign.net

If you use OAuth2 authentication, you’ll receive an authentication token to include in an Authorization header in every request. If you use Legacy Header authentication, you’ll use the X-DocuSign-Authentication header in every request. See Request Headers.

The OAuth2 authentication methods include:

Base URL

How you get the base URL depends on the authentication method you use. In either case, the base URL looks like this:

https://{server}/restapi/v2/{accountId}/

The server value varies depending on which data center an account resides. North American accounts might use the server na1.docusign.net. On the other hand European users might use this URL: eu.docusign.net.

There are a few API methods that do not include an accountId such as Accounts: create RequestLogs resource For those methods, remove the accountId from the base URL. The HTTP Request section of the API documentation shows you whether you need an account ID.

Never hardcode the base URL.

Base URL for OAuth2 Authentication

If you use OAuth2 authentication, use the authentication server’s /oauth/userinfo endpoint. The response looks like this:

{
  "sub": "50d89ab1-dad5-4a0a-b410-92ee3110b970",
  "accounts": [
    {
      "account_id": "fe0b61a3-3b9b-46d4-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"
}

Concatenate the base_uri and account_id fields like this to create the base URL you will use to make REST API requests:

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

If there is more than one account, choose the one that applies to your integration.

Base URL for Legacy Header Authentication

Legacy header authentication is easier to use while learning the API but is not recommended for production applications. See Authentication Overview to learn more about your authentication options.

If you use legacy header authentication use the REST API’s login_information endpoint. The response looks like this:

{
  "loginAccounts": [
    {
      "name": "Dev Eloper",
      "accountId": "1703061",
      "baseUrl": "https://demo.docusign.net/restapi/v2/accounts/1703061",
      "isDefault": "true",
      "userName": "Dev Eloper",
      "userId": "1470ff66-f92e-4e8e-ab81-8c46f140da37",
      "email": "developer@example.com",
      "siteDescription": ""
    }
  ]
}

The base URL is given in the baseURL field.

If there is more than one account, choose the one that applies to your integration.

Requests

All requests to the DocuSign API must be sent to the base URL you obtained after authentication. Always use HTTPS to send API requests.

Request Headers

Every API request must have an authentication header. The header you use depends on the authentication method.

Authentication Method Required Header
OAuth2 Authorization: Bearer <OAuth2 token>
Legacy Header 'X-DocuSign-Authentication: { "Username":"developer@example.com", "Password":"S3cre+p455w0Rd", "IntegratorKey":"230546a7-9c55-40ad-8fbf-af205d5494ad" }'

The default request body format is JSON. If the request body is in XML, you must supply a Content-Type header.

Format Request header
JSON Content-Type: application/json
XML Content-Type: application/xml

Request Parameters

A request can take path parameters or query parameters. Path parameters are required. Query parameters are usually optional.

The Parameters section of the API documentation shows you which parameters are path parameters and which are query parameters.

Request Body

Request bodies are usually used in POST requests to send information to the platform. The request body can be formatted as JSON or XML. If you don’t specify a format in a Content-Type header, the default is JSON.

If the request body does not match the Content-Type header, you will get a 400 or 415 response status code.

Responses

Responses are usually JSON- or XML-formatted objects. In some cases, such as when requesting a document. the response is data.

Maintaining Forward Compatibility

To avoid sudden application errors when the API is updated, your application must implement the following best practices:

  • When processing API responses, ignore any unexpected parameters or objects.
  • When deserializing API responses, set your library to ignore any unexpected properties or objects.
  • When processing any enumerated values, ignore any unexpected values as “unknown”.

Response Status

Successful API responses are in the 200 range. The body of the response has the result.

Status Description
200 Successful.
201 Created. Example: An envelope has been successfully created.
400 Bad Request. Example: The request is missing information or not legal XML or JSON.
401 Unauthorized. Example: Your integrator key is incorrect.
415 Unsupported media type. Example: Your request may be in XML, but you did not specify Content-Type: application/xml in the request header.

Error results have a response body that describes the error:

{
  "errorCode": "PARTNER_AUTHENTICATION_FAILED",
  "message": "The specified Integrator Key was not found or is disabled. An Integrator key was not specified."
}

See Status and Error Codes for a full list of response codes, error results, signer status codes, and recipient status codes.

Response Headers

In addition to the standard response headers, API responses include the following headers.

Header Description
X-RateLimit-Limit The maximum number of API requests you can make.
X-RateLimit-Remaining The number of API requests left before you reach the limit.
X-RateLimit-Reset The time, in the Unix Epoch, when the rate limit will be reset.
Content-Type The format of the response. Usually one of application/json, application/xml, or application/pdf.
Content-Disposition Present only if the body is an attachment. Specifies the attachment’s file name.

Response Body

API responses use the following conventions:

  • All response fields are in camelCase: userName, envelopeId.
  • All values that represent constants or enumerations, except for errors, are given in lowercase: status: 'created'.
  • Error constants are in uppercase.
  • Fields with uri in their name are relative to the base URL.
  • Fields with url in their name are fully qualified URLs.
  • All times are in UTC. See Date and Time Formats.

By default, responses are formatted as JSON. Otherwise, results are rendered according to the Content-Type header in the request. For example, if you request a document from an envelope, the response body contains the data of a PDF file, and the content type is application/pdf.

Date and Time Formats

Dates and times in responses are in UTC in ISO 8601 format: 2016-10-20T21:58:02.6600000Z.

When providing dates and times in requests, you can use ISO 8601 or one of the following formats. These are also in the UTC time zone.

  • yyyy-MM-dd | HH:mm
  • MMMM d, yyyy | HH:mm
  • MMM-dd-yyyy | HH:mm
  • dd-MM-yyyy | HH:mm

Timing Requests

You can add a X-DocuSign-TimeTrack header to your requests to track how long the request took. The response will also have a X-DocuSign-TimeTrack with two semicolon-separated values of the start and end times of the request:

REST0_Start,2016-10-20T21:58:00.7388927Z;REST0_End,2016-10-20T21:58:03.0514225Z

If you provide a value in the request, it will appear before the time values.

MyApp 2.0 (gdef6cd);REST0_Start,2016-10-20T21:58:00.7388927Z;REST0_End,2016-10-20T21:58:03.0514225Z

Multipart Form Requests

There are generally two ways to upload documents for these methods:

  • base64 encoding the document and inserting the encoded bytes in the appropriate field. In the Envelopes: create method this is documentBase64 field.
  • Using multipart form requests.

Multipart uploads remove the need to encode documents in base64 format. Use a separator that will not occur in your document.

This is example multipart request. Note the use of Content-Type and Content-Disposition headers for this request.

POST https://{server}/restapi/v2/accounts/{accountId}/envelopes

Authorization: Bearer OvwkFQIqMsi5vTGq+tTAAAAAxKM=
Accept: application/json
Content-Type: multipart/form-data; boundary=01ead4a5-7a67-4703-ad02-589886e00923

--01ead4a5-7a67-4703-ad02-589886e00923
Content-Type: application/json
Content-Disposition: form-data
{
  "status":"sent",
  "emailBlurb":"Test Email Body",
  "emailSubject": "Test Email Subject - EnvelopeDefFull",
  "documents": [{
      "name": "test1.pdf",
      "documentId":"1",
      "order":"1"
  }],
  "recipients": {
    "signers" : [{
      "email": "joe-signer@example.com ",
      "name": "Joe Signer",
      "recipientId":"1",
    }]
  }
}
--01ead4a5-7a67-4703-ad02-589886e00923
Content-Type: application/pdf
Content-Disposition: file; filename="test1.pdf";documentid=1

[PDF binary document content not shown]

--01ead4a5-7a67-4703-ad02-589886e00923--

base64 Content Encoding

base64 content type encoding is supported for documents and images by setting the Content-Transfer-Encoding header to base64.

For PUT and POST requests, this setting indicates that the document or image bytes are encoded as base64, and the platform should decode the stream.

For GET requests, this setting indicates that the document or image bytes requested are to be encoded as base64 by DocuSign before sending them in the response. This header is set in the response if the conversion was performed.