Using the DocuSign API Postman Collections

Follow this guide to install and configure the DocuSign API Postman collections, which enable you to execute requests against the DocuSign REST APIs quickly and easily inside Postman. The DocuSign API Postman collections include examples for common workflows such as authenticating to retrieve your account ID and base URI, sending an envelope via email, creating reusable templates, and signing documents directly through your app or website, also known as embedded signing.

Prerequisites

To set up the DocuSign API Postman collections on your system, you need:

• A DocuSign developer account. You can create an account for free at the DocuSign Developer Center.

• Postman installed

• A Postman account. The Postman UI includes an option to create an account.

Step 1: Create your environment

Open the Apps and Keys page in your developer account settings. From here, you'll copy values into the Postman environment setup. The button below opens a dialog box prompting you to configure your Postman environment; to do so, you'll need the following values:

• Integration key: Any app you create with DocuSign is called an integration. All your integrations are identified in your DocuSign developer account by their integration key, which is a GUID issued to your integration when you select Add App and Integration Key on the Apps and Keys page within your developer account’s Settings area. If you don't have any integrations in your developer account yet, select that button and give your integration a name. Use the Integration Key value, which is automatically generated when you click OK.
• Corresponding secret key: For Authorization Code Grant authentication, your integration needs a secret key as well. Select Add Secret Key on the Apps and Keys page and copy the value; you can only do this when you create the key, as it won't be visible thereafter.
• Environment: Choose Demo.
• API version: The Postman collection supports the eSignature REST API versions 2 and 2.1. Select v2.1, which is preferred; version 2 will be deprecated in the future.

Step 2: Import into Postman

Step 3: Pick your desired OAuth grant type

Every request to any DocuSign API requires that you authenticate with DocuSign by presenting an access token. So, before you execute any API request in Postman, you'll need to obtain such a token. DocuSign uses the OAuth authentication model; visit our Authentication Guide to see how it works and determine which type to use for your integration.

Each Postman collection's Authentication folder contains requests for two OAuth 2.0 workflows: Authorization Code Grant and JSON Web Token Grant. We also provide a user info request for finding and storing your account ID and base URI. Note that you need to obtain consent through the web interface the first time you request access via the API.

For Authorization Code Grant:

Begin by opening a web browser and navigating to the following URL:

https://account-d.docusign.com/oauth/auth?response_type=code&scope=signature&client_id={iKey}&redirect_uri={callback}

Replace {iKey} with your integration key and {callback} with your redirect URI (set up when you generated the integration key) to obtain consent.

Note: The URL above includes the signature scope required for the eSignature REST API. If you are working with a different Postman collection, visit the Developer Center page for Click API authentication, Admin API authentication, or Rooms API authentication to find out which additional scopes you should specify in the URL.

This URL opens a DocuSign authentication screen; once you enter your DocuSign developer account email address and password and give consent for the requested scopes, your browser will redirect to your redirect URI with a long string returned for the code parameter embedded in the URL. Paste the value of the code parameter into the corresponding value under Body in the 01 Authorize Code Grant Access Token request in Postman. 

Obtain an authorization header by executing the following method call in a JavaScript console, with the integration and secret key values for your integration:

btoa('{iKey}:{secret key}')

Paste the value returned by the btoa call into the Authorization value under Headers in the 01 Authorize Code Grant Access Token request in Postman. The word Basic followed by a space must precede the pasted value. Execute the  01 Authorize Code Grant Access Token request to generate an access token and a refresh token.

Note: If you receive an expired_client_token error in the response, too much time has elapsed since you obtained the code from the https://account-d.docusign.com/oauth/auth URL. Resubmit that request, paste the new value into the code parameter in the 01 Authorize Code Grant Access Token request body, and resubmit the request.

Finally, paste the access token into the Authorization value under Headers in the 04 Get User Info request. The word Bearer followed by a space must precede the pasted value. Execute the request to retrieve your account ID and base URI; these will then be added to your environment variables, ready for you to issue other API requests as you like. For more information, see How to get an access token with Authorization Code Grant on the DocuSign Developer Center.

For JSON Web Token Grant:

Begin by opening a web browser and navigating to the following URL:

https://account-d.docusign.com/oauth/auth?response_type=code&scope=signature%20impersonation&client_id={{iKey}&redirect_uri={callback}

Replace {iKey} with your integration key and {callback} with your redirect URI (set up when you generated the integration key) to obtain consent.

Note: The URL above includes the signature scope required for the eSignature REST API plus the impersonation scope required for JWT Grant. If you are working with a different Postman collection, visit the Developer Center page for Click API authentication, DocuSign Admin API authentication, or Rooms API authentication to find out which additional scopes you should specify in the URL.

This URL opens a DocuSign authentication screen; once you enter your DocuSign developer account email address and password and give consent for the requested scopes, your browser will redirect to your redirect URI with a long string returned for the code parameter embedded in the URL. The code value is not needed for JWT authentication.

Now, open a web browser and navigate to https://jwt.io to generate an RSA-256 compatible signature for the JWT. See Step 2 in How to get an access token with JWT Grant authentication for details. Enter your generated JWT from jwt.io into the assertion value under Body in the 02 JWT Access Token request in Postman.

Obtain an authorization header by executing the following method call in a JavaScript console, with the integration and secret key values for your integration:

btoa('{iKey}:{secret key}')

Paste the value returned by the btoa call into the Authorization value under Headers in the 02 JWT Access Token request in Postman. The word Basic followed by a space must precede the pasted value.

Execute the 02 JWT Access Token request. This request will store your access token in a Postman variable for future requests. Use the 04 Get User Info request to retrieve the account ID and base URI. For more information, see How to get an access token with JWT Grant authentication on the DocuSign Developer Center.

Using access tokens and account IDs

Just about every DocuSign API call contains a Bearer {{accessToken}} authorization header that includes your access token. An Authorization Code Grant access token is good for eight hours, so the refresh token should be utilized beyond that window up to 30 days. A JWT access token expires within one hour, and refresh tokens are not available with JWT. Instead of using the 03 Refresh Access Token request (as utilized in Authorization Code Grant), simply run the 02 JWT Access Token request again. Many (but not all) calls use an account ID, which can be retrieved by running the 04 Get User Info request.

Requests in the Examples folder

Please add and define the following variables if you're planning to run the Postman requests under the Examples folder:

• user_email = email@domain.com

• user_name = Foo Bar

Step 4: Test production credentials

After you enable an integration key in production, you can test it using your production integration key and secret. Simply change the hostenv environment variable to account.docusign.com and re-authenticate using the Authentication examples to get your new base URI.