Please Mr. Postman
The Marvelletes have been waiting for the postman, but here at the DocuSign API team, we have no time to wait. The DocuSign public Postman collections were recently named among the top 10 Postman API Workspaces as picked by Postman staff.
What’s new?
- Support for version 2.1 of the DocuSign eSignature API
- Support for modern, secure OAuth 2.0 authentication
- Full list of 366 different requests covering every endpoint of the eSignature REST API
Watch a YouTube video showcasing how to use the DocuSign Postman collections.
How to use the DocuSign eSignature Postman collection
To use the collections, you must first install the Postman app on your computer. It is available for Linux, macOS, or Windows. Once it's installed, you can launch the application directly if you want to try it out, but to use it with the DocuSign collections, you need to personalize it with your own information.
Setting up your personalized Postman configuration
Before you can use Postman with the DocuSign eSignature REST API, you need to configure it. Configuration is a one-time process that imports the DocuSign API and creates an environment with your API credentials so you can easily execute calls. To configure Postman for the DocuSign collections, follow these steps:
- Make sure you have a DocuSign developer account and integration key. If you don’t have one, you can create one for free.
- Create a new integration key and secret key in the DocuSign Apps and Keys page inside the DocuSign Settings application (Take a note of the secret key, as you can only see it once when you create it). You will also have to add at least one URL in the redirectUri list for this integration key. We recommend you use something like “http://localhost” (I’ll explain later how you use this).
- Navigate to the DocuSign eSignature API Postman Collection page.
- Select SET UP YOUR ENVIRONMENT. The dialog box shown in figure 1 appears and prompts you to enter your integration key and corresponding secret key which you created in step 2 above.
- You can leave the Environment (Demo, which is the developer environment and what we will discuss in this blog post) and API version default settings.
Figure 1: Configuring the initial environment to be used with the DocuSign eSignature Postman collection
Configuring Postman continued:
- Select CREATE ENVIRONMENT.
- Select Run in Postman
- On Windows, a small popup window will appear (figure 2). Select Postman for Windows to run the Postman client application.
- Optional on Windows: Another security popup (see figure 3) may require you to select Open Postman before the application launches.
Figure 2: Launching the Postman application from the website
Figure 3: Additional security popup on Windows before launching the application
Using Postman to make DocuSign eSignature API calls
After you follow the preceding steps and configure DocuSign in Postman, you are ready to start using it. In the Postman app, click Collections. Your app should look like figure 4.
Figure 4: Postman after DocuSign eSignature REST API import
Running the authentication code
Before you proceed, make sure to select DocuSign-account-d (since you selected demo when setting the environment, it will be a different name for production) from the environment dropdown at the top-right corner of the Postman window (next to the "eye" icon) to ensure the environment information you created earlier is applied to the variables inside the calls.
These steps show you how to use Authorization Code Grant to obtain an access token to make your API calls from postman. You may also use JWT (JSON Web Tokens) if you prefer.
To start the authentication process, you have to manually construct a URL that looks like this:
https://account-d.docusign.com/oauth/auth?response_type=code&scope=signature&client_id={iKey}&redirect_uri={callback}
Remember to replace {iKey} with the integration key you created earlier and replace {callback} with the redirectUri you have configured for it. After you enter this URL in the browser, you should expect to see the DocuSign login screen for the developer environment, where you can enter your credentials to your account. If this is your first time using this new application, you should also see the consent dialog shown in figure 5. Select ACCEPT to allow your app to make API calls to DocuSign using this newly created integration key.
Figure 5: You must grant consent to your integration in order to make API calls to DocuSign
If it's configured correctly, you should now be redirected back to your redirectUri with an additional URL parameter called code. That parameter contains a long code that can be used to obtain an access token to make API calls. Open the Postman collection and expand the DocuSign eSignature REST API folder on the left. Then expand the Authentication folder and select 01 Authorize Code Grant Access Token.
Copy/paste this code into your Postman application. You would have to copy/paste the code that you obtained from the URL parameter into the Body key/value pair (replacing the {{codeFromUrl}} value). Note that the code is valid for two minutes only. If you don’t send this information to DocuSign quickly enough, you will have to obtain a new code again. Hit the Send button at the top of Postman to make the call to DocuSign. If successful, you should get back an access_token and refresh_token. These will be automatically stored in the Postman environment for you.
Figure 6: Sending the 01 Authorize Code Grant Access Token request
The next call you have to make is 04 Get User Info. This is the last call in the Authentication folder and can be made as soon as you obtain the access token. That call is used to populate additional environment variables such as your accountId, userId and baseUrl required to make any eSignature API call. Selecting the Environment Quick look (the "eye" icon to the right of the environment drop-down) in Postman will enable you to view all your environment variables and confirm you have what is needed to start making DocuSign eSignature API calls.
Figure 7: The Postman environment includes four new parameters after completing the authentication calls to DocuSign
Making your first DocuSign eSignature API call with Postman
The DocuSign eSignature API Collection that you imported includes the full set of API calls, including every possible parameter. I'm not going to cover them all in this blog post; instead, I'll show you how to make a simple API call to create a new envelope. To do so, you'll have to provide some data.
Scroll down and expand the Envelopes category/folder, where you can find different API calls related to envelopes. Select the POST Creates an envelope. When you open it and select the Body tab in Postman, it should look like this:
Figure 8 - full featured POST creates an envelope call without customizations.
Remove the entire body and replace it with a simple JSON body to create an envelope with a single recipient and short single document. That JSON looks like this (replace email:domain.com with your email address):
{
"emailSubject": "Please sign this document set",
"documents": [
{
"documentBase64": "dGVzdCBkb2M=",
"name": "Lorem Ipsum",
"fileExtension": "txt",
"documentId": "1"
}
],
"recipients": {
"signers": [
{
"email": "email@domain.com",
"name": "Your Name",
"recipientId": "1",
"routingOrder": "1",
}
]
},
"status": "sent"
}
Before you run this, though, you do need to make one more change. Go to the Headers tab in Postman and uncheck the Content-Type header. The default Content-Type is required for this call.
Figure 9: successful API call to create and send an envelope.
If the call was successful, expect to get back an envelopeId. which is a GUID value. You should also get an email from DocuSign to the email address you used, asking you to sign the document.
That’s it. You made your first DocuSign eSignature API call! There’s a lot more to do and explore with the new DocuSign eSignature Postman Collection. Have Fun!
