Sending Signature Requests | HelloSign API Documentation
Sending Signature Requests

There are several ways to send a signature request using the HelloSign API. The method you may want to use will depend on your use case. Take a look at the different options we offer to decide which scenario fits your needs.

Scenarios

How do you plan on creating your signature requests?

Using files
Using Templates
Using form fields
Using files
You provide the files to create the request and we add a signature page for the signers to sign.

This is the simplest way to create a signature request, attach the file(s) along with signer details and you're all set. A signature page will be appended at the end of your documents with a signature field for each signer involved.

Example

This will send a signature request to Jack and Jill. Both will receive an email with a link to sign the request. The link will take them to a page where they can review the document before adding their signatures onto the signature page.

The signature_request_id field allows you to keep track of the request status as shown in the signature request status section. You can find more details about the Signature Request object on the API reference page.

Using templates
Setup a template ahead of time on hellosign.com and reuse them with custom data it when sending signature requests.

If you need to send signature requests with the same documents often and need to have them filled in specific places, then using templates (formerly known as a reusable form) make perfect sense. This way, you save yourself the trouble of uploading the document files everytime and get to decide where the signers should fill in information.

Templates allow you to specify form fields (text, check boxes, signatures, etc...) that the signers should fill. But it also offers the possibilty to define "custom fields" (see picture) that will be filled when the request gets sent via the API and will be shown to the signers.

Visit our template walkthrough if you're not familiar with templates and how to use them with the API.

Example

This will send a signature request to Jack and Jill. Both will receive an email with a link to sign the request. The link will take them to a page where they can review the document and fill out the required fields.

The signature_request_id field allows you to keep track of the request status as shown in the signature request status section. You can find more details about the Signature Request object on the API reference page.

Using files and form fields
You provide the files and tell us exactly where form fields go on them. No signature page is added in this case.

If you need to send documents with changing content but the same form fields, we have a better alternative than using templates. Rather than creating a large number of templates to cover all the variations, you can create one single template and retrieve the coordinates of the associated form fields. With that information, you can provide the list of form fields and their coordinates when sending the signature request via the API.

NOTE Text Tags are a much easier way to handle this scenario as they allow you to place tags in the document that will be converted to components when the request is sent.

Example

First, let's retrieve the coordinates for the form fields we need from a chosen template.

This following request will create a signature request for two signers. On the first document (NDA), there will be a signature field and a date field for each signer. No form fields will be present on the second document.

For more information about form fields and their attributes, see "form_fields" in Templates.

Finding out when documents have been signed

There are 2 ways get the status of a document. The preferred method is to provide a callback url which we'll post events to. The option to poll the API is also available but it's impractical in most situations since signers may take a while to view and sign your documents.

Webhooks (preferred)

Read our documentation about events to get a better understanding of how webhooks work with your account and apps.

Polling
Warning

If you poll, any frequency you choose has disadvantages, either having to make thousands of requests per signature request over a day or two or making fewer requests and having more time pass between the signature request completion and your system finding out about it. Webhooks solve both of these problems.

Checking the status of a Signature Request
Retrieving documents

At any given time during the signature request process, you can retrieve the associated document in its current state via the API. You can either download a single PDF document or separate pages in a zip file. Either option will contain all the signatures and information that signers have added so far.