Using the DocuSign eSignature API Postman Collection

Follow this guide to install and configure the DocuSign eSignature API Postman collection, which enables you to execute requests against the DocuSign eSignature REST API quickly and easily inside Postman. The DocuSign eSignature API Postman collection includes examples for common workflows (authenticating to retrieve your accountID and baseUrl, sending an envelope via email, templates, and embedded signing).

Step 1: Create your environment

To set up the DocuSign eSignature API Postman collection on your system, you need a DocuSign developer demo account and Postman installed. If you’ve previously set up an account, log in. Otherwise, create an account for free at the DocuSign Developer Center.

Once you're in your demo account, go to Admin, then choose API and Keys from the left nav. From here, you'll copy values into the environment setup. You'll need the following values before you click the button below to set up your Postman environment:

Integration key: Any app you create with DocuSign is called an integration. All your integrations are identified in your DocuSign demo account by their integration key, which is a GUID issued to your integration when you select Add App / Integration Key on the API & Keys page. If you don't have any integrations in your demo 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 Authentication Code Grant authentication, your integration needs a secret key as well. Select Add Secret Key on the API & 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. Version 2.1 is preferred; version 2 will be deprecated in the future.

Set up your environment

Step 2: Import into Postman

Be sure to complete step 1 before clicking the button below. This imports the DocuSign Postman collection and your environment variables into your installation of 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.

The eSignature API Postman collection's Authentication folder contains 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 accountID and baseURL. Note that you need to obtain consent through the web interface on 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 callback URL (set up when you generated the integration key) to obtain consent. This URL opens a DocuSign authentication screen; once you enter your DocuSign username and password, your browser will redirect to your callback URL with a long string returned for the code parameter embedded in the URL. Paste the value of the code parameter into the corresponding value location under Body in the 01 Authorization Code Grant Access Token request and execute it to generate an access token and a refresh token. Finally, use the 02 Get login information information for a specified user request to retrieve your AccountID and baseURL; these will then be added to your environment variables, ready for you to issue other API requests as you like.

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 callback URL (set up when you generated the integration key) to obtain consent. This URL opens a DocuSign authentication screen; once you enter your DocuSign username and password, your browser will redirect to your callback URL with a long string returned for the code parameter embedded in the URL.

Now, open a web browser and navigate to https://jwt.io to generate an RSA-256 compatible signature for the JWT. In order to create a compatible signature, you need to include your integration key and a user ID you wish to impersonate; for testing purposes, this can be your own (copy this from Account Information on the API & Keys page). Enter your generated JWT from jwt.io into the 01 JWT Access Token request. This request will store your access token in a Postman variable for future requests. Use the 02 Get login information information for a specified user request to retrieve the AccountID and baseURL. Note that the response for a JWT request will not include a refresh token, and that the access token generated by a JWT request will expire within one hour. Instead of using the 03 Refresh Access Token request (as utilized in Authorization Code Grant), simply run the 01 JWT Access Token request again.

Notice that just about every DocuSign API call here contains an bearer {{token}} authorization header that includes your access token. The access token is good for 8 hours, so the refresh token should be utilized beyond that window up to 30 days. Many (but not all) other calls use an AccountID, which can be retreived by running the strong>02 Get login information information for a specified user request.

Step 4: Running the examples

This collection is automatically generated from our available Swagger methods and is divided by available methods in the 2.1 API version. Select v2.1, then accounts, then {account id} to see the plethora of API requests available to you. Folder names wrapped in braces contain requests that require the {X} variable filled in on that given call within said {X} folder. Here are some of the folders and their requests that you may find interesting when getting started:

{account Id} -> envelopes

The envelopes folder contains methods to create envelopes, get status changes for multiple envelopes and even a separate put call for further details from a specific envelope. Going a step further, if you have an envelope ID on hand, click on the {envelopeID} folder and try your hand at any number of lookups or modifications for envelope data including comments, documents, and recipients.

{account Id} -> views

The views folder contains several methods for generating and retrieving view URLs that can be used for embedded signing, editing, and sending of envelopes. You can also retrieve prior views and preview the recipient shared view and a second that creates and sends an envelope from the created template.

{account Id} -> groups

The groups folder shows how to administer groups by creating, updating, and deleting user groups. The embedded {group id} folder allows you to correlate your brand id information on existing groups or to add and delete brands against your groups.

Step 5: 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 BaseUrl.