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.
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.
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:
Before you select one of the options below, be sure to log in to Postman from the Postman UI.
Select a button below to import the DocuSign Postman collection for that API and your environment variables into your installation of Postman.
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.
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.
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.
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.
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
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.