Skip to navigation
Tools

Using the Docusign API Postman collections

View as Markdown

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 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:

Step 1: Create your environment

The Set Up Your Environment button below opens a dialog box prompting you to configure your Postman environment using the values in Apps and Keys page.

Any app you create with Docusign is called an integration.

  1. Open Apps and Keys page of your Docusign account.

  2. Integration Key(IK): All your integrations are identified in your Docusign developer account by their integration key, which is a GUID issued to your integration. To add an app and get an integration key,

    1. Select Add App and Integration Key.
    2. Enter a name for the app and select Create App.
    3. In the integration page, under the General Info, copy the Integration Key value, which is automatically generated when you select Create App.

  3. Corresponding secret key: For Authorization Code Grant, your integration needs a secret key as well. To add a secret key,

    1. Under the Authentication section, Select + Add Secret Key.
    2. Copy and save your secret key now because it won’t be shown again. If lost, you must generate a new one.
    3. Select Save.

    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.

    Now, to create your Postman environment, select Setup Your Environment button below.

  1. Enter the Integration key value.
  2. Enter the Corresponding secret key value.
  3. Select Environment as Demo.
  4. Select API version as v2.1.
  5. Select Close.

The Postman collection supports the eSignature REST API versions v2 and v2.1.

Select v2.1, which is preferred. v2 will be deprecated in the future.

Step 2: Import into Postman

Before you select one of the options below, be sure to log in to Postman from the Postman UI in your browser.

Select a button below to import the Docusign Postman collection for that API and your environment variables into your installation of Postman.

To import a Postman collection,

  1. Select Run in Postman.
  2. Select Fork Collection.
  3. Enter a Fork label.
  4. Select a Workspace.
  5. Select Fork collection.

Note: Your environment variables are added while importing the Postman collection. If you want to import more than one collection, refresh the page between imports to avoid caching issues.

API NamePostman Collections URL
eSignature REST API
Web Forms API
Maestro API
Agreement Manager API
Workspaces API (Beta)
Rooms API
Click API
Docusign Admin API
Monitor API
Notary API

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. To execute any API request in Postman, you need to such a token for you.

Docusign uses the OAuth authentication model; visit our Authenticate guide to see how it works and determine which type to use for your integration.

Each Postman collection’s 🔐 Quick Auth Setup → Then Run APIs folder contains requests for three OAuth 2.0 workflows, one Refresh Access Token, and one user info flow.

  • 01 - JWT / Service Integration, see JSON Web Token (JWT) Grant.

  • 02 - Authorization Code Grant (Confidential Client), see Authorization Code Grant.

  • 03 - Authorization Code Grant with PKCE (Public Client) , seeProof Key for Code Exchange (PKCE).

  • 04 - Refresh Access Token. Used to refresh the generated access token after its expiry.

  • 05 - User Info. This request is 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.

Authentication Type

To set up a JSON Web Token (JWT) grant, copy the following parameter values from Apps and Keys page and paste in the corresponding variables of your Postman Environment.

Before saving the variables in Postman, select Pin to collection for the Docusign-account-d environment.

postman environment
Field Name in Apps and Keys PageVariable Name in Postman CollectionDescription
General Info > Integration KeyintegrationKeyAn integration key identifies your integration and links to its configuration values. Refer Create an integration key..
Additional Settings > Redirect URIsredirectUriThe redirect URI is the URI (URL) to which Docusign will redirect the browser after authentication. Refer Set a redirect URI..
Service Integration > RSA Keypairs (ID)privateKeyRefer RSA key pair.
Apps and Keys > My Account Information > User IDuserIdFind your User ID in the Apps and Keys page.

  1. Go to 🔐 Quick Auth Setup -> Then Run APIs > 01 - JWT / Service Integration > then 01-1 - Construct Consent URL (JWT) and send a request to generate authorization URL.

  2. Paste the authorizeUrl into your web browser’s address bar, and open the page.

  3. Select Allow Access. (Sign in to your Docusign Developer’s account if required). Once you give your consent to the requested scopes, the browser will redirect to your redirect URI.

  4. Execute the 01-2 - JWT Token (exchange) request to generate an access token.

  5. Execute the 05 Get User Info request to retrieve your account ID and base URI; These values will be added to your environmental variables, so they’re ready for subsequent requests.

    If you get an internal error, select the Authorization of 05 Get User Info in Postman Authorization tab as Bearer Token and paste the access token obtained in Step 4.

To set up an authorization code grant , copy the following parameter values from Apps and Keys page and paste in the corresponding variables of your Postman Environment.

Before saving the variables in Postman, select Pin to collection for the Docusign-account-d environment.

postman environment
Field Name in Apps and Keys PageVariable Name in Postman CollectionDescription
General Info > Integration KeyintegrationKeyAn integration key identifies your integration and links to its configuration values. Refer Create an integration key..
Authentication > Secret KeyclientSecretThe secret key identifies your integration app through a unique key. Refer secret key.
Additional Settings > Redirect URIsredirectUriThe redirect URI is the URI (URL) to which Docusign will redirect the browser after authentication. Refer Set a redirect URI.

  1. Go to 🔐 Quick Auth Setup -> Then Run APIs > 02 – Authorization Code Grant (Confidential Client) > then 02-1 – Construct Authorization URL and send a request to generate authorization URL.

  2. Paste the authorizeUrl into your web browser’s address bar, and open the page.

  3. Select Allow Access. (Sign in to your Docusign Developer’s account if required). Once you give your consent to the requested scopes, the browser will redirect to your redirect URI with a long string returned for the code parameter embedded in the URL.

  4. Copy this code value ( Note: The code value is valid only for one minute. If the code is expired, refresh the URL displayed in Step 2 and obtain a new code).

  5. Go to 🔐 Quick Auth Setup -> Then Run APIs > 02 – Authorization Code Grant (Confidential Client) > 02-2 – Exchange Authorization Code for Tokens request. Paste the value of the code parameter into the code value under Body of the request. Alternatively, you can save the code in the Postman variable authCodeNoPkce.

  6. Execute the 02-2 – Exchange Authorization Code for Tokens request to generate an access token and a refresh token. The access token is saved in the Postman variable to be used for subsequent API calls.

    1. 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.
    2. Repeat the steps from Step 2 to generate a new code and obtain the access token.

  7. Execute the 05 Get User Info request to retrieve your account ID and base URI; These values will be added to your environmental variables, so they’re ready for subsequent requests.

    If you get an internal error, select the Authorization of 05 Get User Info in Postman Authorization tab as Bearer Token and paste the access token obtained in Step 4.

To set up an public authorization code grant, copy the following parameter values from Apps and Keys page and paste in the corresponding variables of your Postman Environment.

Before saving the variables in Postman, select Pin to collection for the Docusign-account-d environment.

postman environment
Field Name in Apps and Keys PageVariable Name in Postman CollectionDescription
General Info > Integration KeyintegrationKeyAn integration key identifies your integration and links to its configuration values. Refer Create an integration key..
Additional Settings > Redirect URIsredirectUriThe redirect URI is the URI (URL) to which Docusign will redirect the browser after authentication. Refer Set a redirect URI.
Authentication > User ApplicationNot applicableRefer set the authentication method.
1. Select No for Is your application able to securely store a client secret?

2**.** Select Single-Page Web Application for App Type.
3. Select Authorization Code Grant with Proof Key for Code Exchange (PKCE) for Authentication Method for your App.
Additional Settings > Origin URLs and Allowed HTTP MethodsoriginUrlRefer CORS configuration parameters
1. Add the list of Origin URL by selecting + Add Origin URL in Apps and Keys page.
2. Add these urls in Postman variable originUrl as common separated values.
3. Select Allow CORS for OAuth calls checkbox.
4. Select all checkboxes of Allowed HTTP methods such as GET, POST, PUT, DELETE, and HEAD.
5. Select Save.

  1. Go to 🔐 Quick Auth Setup -> Then Run APIs > 03 - Authorization Code Grant with PKCE (Public Client) > then 03-1 - Construct Authorization URL with PKCE and send a request to generate authorization url.

  2. Paste the authorizeUrl into your web browser’s address bar, and open the page.

  3. Select Allow Access. (Sign in to your Docusign Developer’s account if required). Once you give your consent to the requested scopes, the browser will redirect to your redirect URI with a long string returned for the code parameter embedded in the URL.

  4. Copy this code value ( Note: The code value is valid only for one minute. If the code is expired, refresh the URL displayed in Step 2 and obtain a new code).

  5. Go to 🔐 Quick Auth Setup -> Then Run APIs > 03 - Authorization Code Grant with PKCE (Public Client) > 03-2 - Exchange Authorization Code for Tokens (PKCE) request. Paste the value of the code parameter into the code value under Body of the request. Alternatively, you can save the code in the Postman variable authCodePkce.

  6. Execute the 03-2 - Exchange Authorization Code for Tokens (PKCE) request to generate an access token and a refresh token.

    1. 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.
    2. Repeat the steps from Step 2 to generate a new code and obtain the access token.

  7. Execute the 05 Get User Info request to retrieve your account ID and base URI; These values will be added to your environmental variables, so they’re ready for subsequent requests.

    If you get an internal error, select the Authorization of 05 Get User Info in Postman Authorization tab as Bearer Token and paste the access token obtained in Step 4.

Using access tokens and account IDs

Nearly every Docusign API call requires an authorization header containing your access token:

Authorization: Bearer {{accessToken}}

Access Token Lifespans & Renewal

  • Authorization Code Grant:

    • Access Token Duration: 8 hours.
    • Renewal: Use a refresh token to generate a new access token via the 04 Refresh Access Token request. Refresh tokens remain valid for up to 30 days.

  • JSON Web Token (JWT) Grant:

    • Access Token Duration: 1 hour.
    • Renewal: Refresh tokens are not supported. To renew, re-run the 02-2 - Exchange Authorization Code for Tokens request (or generate a new JWT assertion).

User & Account Identification

  • Account ID Requirement: Many API endpoints require a specific accountId.
  • Retrieval: Obtain your account ID by executing the 05 Get User Info request or see in your Apps and Keys page at Apps and Keys > My Account Information > User ID.

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:

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.