Formatting API requests

When making a request to the eSignature API, you must include the following set of data:

• The base_uri for your account, which is used to build the full path of the API call. To find your base URI, you can call the UserInfo endpoint or look in your Apps and Keys page.

  • For integrations in the developer environment, the base URI is https://demo.docusign.net/
  • For integrations in production, the base URI is in the form https://{server}.docusign.net/

• Your API account ID, which is also used to build the full path of the API call. You can find your API account ID on the Apps and Keys page.

• An access token, which is obtained via Authentication and attached as a request header for the call.

To build the base path of your call, include your base_uri and API account ID in the following format (using /restapi/v2.1/accounts/ as an example endpoint):

{base_uri} + "/restapi/v2.1/accounts/" + {api_account_id}

Always use HTTPS to send eSignature API requests in both the developer and production environments.

Request headers

Every API request must have an authentication header.

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

Request parameters

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

The Parameters section of the API Reference for each method 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.

Timing requests

You can add an X-DocuSign-TimeTrack header to your request to track how long it took to complete. If you use this header, the API response header will include an X-DocuSign-TimeTrack property with two semicolon-separated values showing the start and end times of the request, such as:

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

If you provide a value for X-DocuSign-TimeTrack in the request, it will appear before the time values in the response header.

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

Multipart form requests (binary transfer)

Some API methods, such as Envelopes:create, require you to provide source content for your documents. You can provide source content by:

• Base64-encoding the document and inserting the encoded bytes in the appropriate field. In the Envelopes:create method, this is the documentBase64 field.
• Using multipart form requests, also known as binary transfer.

Binary transfer is 33% more efficient than base64 encoding and is recommended for all documents that are larger than 15 MB. To perform binary transfer, you must:

• Wrap each part of the document (which is formatted as bytes) in two hyphens and a value identifying the boundary separator (which should be unique in your document).
• Define a Content-Disposition: form data header for each part of the document.

See How to attach documents via binary transfer for a full example.

Base64 encoding

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

Best practices for uploading documents

When uploading documents to your envelope, use the following guidelines for the best efficiency. For documents:

• Smaller than 25 MB, include them as a base64 encoded string in the envelope definition.
• Larger than 25 MB but smaller than 32 MB, use binary transfer.
• Larger than 32MB, use chunked uploads.

Ensure that your documents are 52 MB or smaller. Documents that are 50 MB larger can cause delays for envelope operations.