Exploring the HelloSign API Using Postman

"Exploring the HelloSign API Using Postman" header image

Hi folks! Did you know that the HelloSign API has a public Postman Collection? Postman allows you to quickly explore and test the HelloSign API using a collection of calls that we put together for you. By using the test_mode parameter and a free HelloSign account, you can test the full capabilities of the HelloSign API without ever entering a credit card. In this article, we’ll show you how to set up the HelloSign API Postman collection and then step through a series of calls together.

You’ll need Postman in order to follow along. You can use either the Postman web client or the Postman desktop agent (supports Mac, Linux, and Windows).  The images in this article are from the Postman desktop agent for Mac.

Import the Postman Collection

If you’re using the Postman web client, then you can skip this step and jump right to building in the HelloSign Public Workspace.

For folks using the desktop agent, you can import the HelloSign API collection into your Postman instance by using this button:

Alternatively, you can import the collection by clicking the “Run in Postman” button in the collection documentation page. Similar to the HelloSign API, the Postman collection is organized into a series of Objects and Methods. Each object has various methods that can be used to interact with that object through the API.

Note that each respective endpoint in the HelloSign API collection has documentation (click the dropdown arrow) that includes links to that endpoint’s API reference documentation.

Image showing the location in Postman to find more information about the HelloSign API

Set the Collection Variables

Postman supports user-defined variables with different scopes. The HelloSign API collection makes use of collection variables. Once you enter your authorization information into the collection variables, you’ll be authorized to call each endpoint in the collection (according to the permissions on your HelloSign account).

  • When logged into HelloSign, grab your API Key, and optionally your Client ID, from your API page (located under Integrations —> API).  
Image showing where to find your API key in the HelloSign app.

  • In Postman, select “Edit” on the HelloSign API collection and go to the “Variables” tab. Replace the api_key and client_id with your information from HelloSign. Leave test_mode set to 1.
Image showing the "Variables" tab in Postman

Note: API calls sent in test mode are not legally binding and don’t count towards your plan.

With your HelloSign credentials entered as collection variables, you’re ready to start making API calls!

Use Postman to Call the HelloSign API

Let’s use Postman to call Send Signature Request, manually complete the signature, inspect the request status with Get Signature Request,  and call Get Files to download the signed file.

In Postman, go to Signature Requests → Send Signature Requests and select the “Body” tab. Include the following parameters in your call:

  • test_mode - Resolves to 1 based on collection variable.
  • file[0] - Press “Select Files” and choose a file to send for signature.
  • title - Add a title to your Signature Request. I used “Postman Collection Demo Request”.
  • signers[0][name] - Add signers name.
  • signers[0][email_address] - Add signer’s email address. For testing, I email myself using an alias (i.e. email+alias@hellosign.com)
  • client_id - Resolves to client id in collection variable. Optional for this call.

Press “Send”. You should get a signature_request object in response. Copy the signature_request_id to use later.

Image showing the "signature_request" object in Postman, with the "signature_request_id" item highlighted.

Go to the inbox of the email you just provided. You should receive a signature request from HelloSign. Click the link in the email and fully complete the signing flow before proceeding to the next step.

Image showing the API success message from HelloSign

Let’s check the state of the signature request. In Postman, go to Signature Requests → Get Signature Request, enter your signature_request_id, and press “Send”. At any time, your app can poll this endpoint to check flags on a specific signature request for is_complete, is_declined, or has_error. Alternatively, your app could receive the notification asynchronously using Callbacks.

Image showing the "signature_request" response object in Postman, with the "is_complete", "is_declined" and "has_error" flags highlighted

Go to Signature Requests → Get Files. Replace the placeholder signature request id with the one you just copied and press “Send”. My completed URL looks like this: https://api.hellosign.com/v3/signature_request/files/5c38c3243536f1eb027b228921cb57888601d036?get_url=true. A successful response will include a file_url with a link to the signed file. You can visit the link to download it.

Image showing the successfully signed document in HelloSign's web interface

Exploring the HelloSign API Using Postman

Thanks for following along! You can use the HelloSign API Postman collection on HelloSign’s Public Workspace, or import it here:

We’re big fans of Postman and use this collection internally. When you’re ready to add the HelloSign API to your codebase, the Quick Start Guide is a great next step!

Ready to integrate signatures into your app or website?

Let us help you build a custom API plan that fits your unique business needs.

Get news, insights and posts directly in your inbox

Thank you! Your submission has been received!
Oops! Something went wrong while submitting the form
Oops! Something went wrong while submitting the form.