Unlike the song where the singer waits for the postman to deliver, we’re not waiting. We’ve jumped on the bandwagon and moved forward with Postman to deliver immediate value. Postman is a great way to test calls to an API and to specify arguments, see JSON structures, and more. It’s also a great way to understand how to use an API without writing any code. Here is everything you need to know to use Postman with the DocuSign eSignature REST API.
Installing and Launching Postman
To use Postman, you must first install the app on your computer. It is available for Chrome, Mac, or Windows. To get the app, simply click here, select your platform, and follow the instructions. After installation, launch the Postman app by clicking its icon. As an example, if you installed Postman in Chrome, you’ll see the app listed when you navigate to chrome://apps/, as shown in Figure 1.
Figure 1: Postman App Installed in Chrome.
After Postman is running for the first time, you are prompted to login or signup with Postman. You can do that, but it is not required. You can simply click the Skip this link, which launches Postman with a default, blank slate shown in Figure 2.
Figure 2: Postman Running for the First Time.
Before you can use Postman with the DocuSign 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 prerequisites, follow these steps:
- Ensure you have a DocuSign demo/sandbox (developer) account and integrator key. If you don’t have one, visit the DocuSign Developer Center to create one for free.
- Navigate to the DocuSign API in Postman page on GitHub.
- Click the ENTER DOCUSIGN CREDENTIALS link, which brings up the dialog box shown in Figure 3, and prompts you to enter your Integrator Key, Email, and Password.Figure 3: Entering Your Demo Environment Credentials into Postman.
- Enter the required information and click the CREATE ENIVIRONMENT link.
- Click the Run in Postman link. This imports the DocuSign API into Postman and also creates a Postman environment with the name of DocuSign-demo.
Using DocuSign in Postman
After you follow the preceding steps and configure DocuSign in Postman, you are ready to start using it. In the Postman app, click the Collections tab and your app should look like the configuration shown in Figure 4.
Figure 4: Postman After DocuSign API Import and Demo Environment Configuration.
If you have configured Postman correctly, on the left pane, you’ll see a hierarchy of recipes (denoted with a preceding number on the left) and endpoints within the DocuSign REST API. You’ll also see at the top of the screen, the newly created environment named DocuSign-demo already selected.
To show how to use DocuSign API for Postman, we’ll walk you through using the four recipes at the top of the list:
- 00 Authentication
- 01 Send for Signature
- 02 Send Request via Template
- 03 Embedded Signing
The recipes are preconfigured with common DocuSign tasks and supply default arguments that you can customize in a group of endpoints.
00 Authentication Recipe
To begin, click 00 Authentication, which expands the folder into individual tasks. Click the only task available, Gets login information for a specified user. Click the Send button to authenticate using the credentials you entered during configuration. If there are no errors, you’ll see the screen shown in Figure 5.
Figure 5: Postman Showing Successful Authentication.
Note: If you receive any errors, you must correct them before continuing. You can change any of the configuration information by clicking the “eye” icon next to the environment dropdown, or by deleting the environment and re-running the configuration steps shown earlier in this blog post.
01 Send for Signature Recipe
After you ensure you successfully authenticated with the 00 Authentication recipe, expand the 01 Send for Signature recipe folder. Click the only task available, Create and Send Envelope. Click the Send button to create a new envelope, create a sample blank document, associate the document with the envelope, and send it via email to the address associated with your DocuSign account. If there are no errors (status 201 Created), you’ll see the screen shown in Figure 6.
Figure 6: Postman Showing Successful Creation and Sending of Envelope.
02 Send Request via Template
The next set of recipes is contained within a folder named 02 Send Request via Template. This folder contains two recipes:
- Create a Template w/Blank PDF
- Create Envelope from Template ID
Start by navigating to the Create a Template w/Blank PDF recipe. Click the Send button to use your stored credentials for the demo environment, create a template from a blank PDF, and place a “Sign Here” tag on the blank PDF. If this operation is successful, you’ll receive a 201 Created message and the API call will return a templateId, which is shown in Figure 7. This templateId is used in the next call.
Figure 7: Postman Showing Successful Creation of a Template with a Blank PDF.
After the successful creation of the templateId, navigate to the Create Envelope from Template ID recipe. Click the Send button to create a new envelope using the templateId. If this operation is successful, you’ll receive a 201 Created message and the API call will return an envelopeId, which is shown in Figure 8.
Figure 8: Postman Showing Successful Creation of an Envelope from a Template.
03 Embedded Signing
The folder called 03 Embedded Signing contains the next two recipes:
- Create Envelope with clientUserId for Recipient
- Returns a URL to the recipient view UI
Start by navigating to the Create Envelope with clientUserId for Recipient recipe. Click the Send button to use your stored credentials for the demo environment to create an envelope for a specific clientUserId to be used as the recipient. For this sample, the clientUserId will be your client ID for the demo environment. If this operation is successful, you’ll receive a 201 Created message and the API call will return an envelopeId, which is shown in Figure 9. This envelopeId is used in the next call.
Figure 9: Postman Showing Successful Creation of an Envelope for a Specific Recipient.
After the successful creation of the envelopeId, navigate to the Returns a URL to the recipient view UI recipe. Click the Send button to retrieve a URL to embed the signing experience into an application without redirecting back to the DocuSign web site. If this operation is successful, you’ll receive a 201 Created message and the API call will return a URL to use to embed the signing process, as shown in Figure 10.
Figure 10: Postman Showing URL for Embedded Signing.
Now that you’ve been through the basics of using Postman to execute API calls without writing any code, you’re ready to begin coding to integrate DocuSign into your apps. There are two main ways of doing this. You can use one of our SDKs, or you can write code directly into your app. The recommended method is to use one of our SDKs.
If you are not going to use an SDK, for any successful API call, Postman can generate code for you in your desired language. Clicking the Code link brings up the screen shown in Figure 11 (with C# code), which enables you to select virtually any language to generate the code.
Figure 11: Generating Code in any Language.
Now you know how to use the DocuSign API for Postman to execute calls with predefined recipes for commonly-used DocuSign actions. You can use these concepts in Postman to experiment with the other API endpoints listed in the left pane. We’d love to get your feedback on the DocuSign API for Postman app by sending an email to [email protected]; let us know if you find it useful (or not). Happy coding!