Signature Request Walkthrough

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?

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

Files
Setup a template on hellosign.com and reuse it with custom data when sending signature requests.

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

Form Fields


Using Files

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.

Loading...
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, found in the response object, 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

If you need to send signature requests with the same documents often and need to have them filled in specific places, then using templates 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" 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.

Loading...
This will send a signature request to George. George 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, found in the response object, 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

warning

Due to a bug, the form_fields_per_document parameter only supports two-dimensional arrays right now. We're testing a fix right now. You can read more here: Using Form Fields per Document.

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.

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 the 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 on the API reference page.

Loading...

Retrieving Signature Status

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 HelloSign Events to get a better understanding of how webhooks work with your account and apps.

Polling

Important

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

curlphpjavapythonrubynodejsdotnet
Copy
Copied
curl 'https://api.hellosign.com/v3/signature_request/961f25267c4ee995619f1e28f0fcb28d2b68b84d' \
    -u 'SIGN_IN_AND_CREATE_API_KEY_FIRST:'
Copy
Copied
$client = new HelloSign\Client('SIGN_IN_AND_CREATE_API_KEY_FIRST');
$signature_request = $client->getSignatureRequest('961f25267c4ee995619f1e28f0fcb28d2b68b84d');
Copy
Copied
HelloSignClient client = new HelloSignClient("SIGN_IN_AND_CREATE_API_KEY_FIRST");
String signatureRequestId = "961f25267c4ee995619f1e28f0fcb28d2b68b84d";
SignatureRequest request = client.getSignatureRequest(signatureRequestId);
Copy
Copied
client = HSClient(api_key='SIGN_IN_AND_CREATE_API_KEY_FIRST')
client.get_signature_request('961f25267c4ee995619f1e28f0fcb28d2b68b84d')
Copy
Copied
client.get_signature_request :signature_request_id => '961f25267c4ee995619f1e28f0fcb28d2b68b84d'
Copy
Copied
const hellosign = require('hellosign-sdk')({ key: 'SIGN_IN_AND_CREATE_API_KEY_FIRST' });

hellosign.signatureRequest.get(signatureRequestId).then((res) => {
  // handle response
}).catch((err) => {
  // handle error
});
Copy
Copied
var client = new Client("SIGN_IN_AND_CREATE_API_KEY_FIRST");
var request = client.GetSignatureRequest("961f25267c4ee995619f1e28f0fcb28d2b68b84d");

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.

curlphpjavapythonrubynodejsdotnet
Copy
Copied
curl 'https://api.hellosign.com/v3/signature_request/files/961f25267c4ee995619f1e28f0fcb28d2b68b84d?file_type=zip' \
    -u 'SIGN_IN_AND_CREATE_API_KEY_FIRST:' \
    -o mySignedPDF.zip
Copy
Copied
$client = new HelloSign\Client('SIGN_IN_AND_CREATE_API_KEY_FIRST');
$client->getFiles('961f25267c4ee995619f1e28f0fcb28d2b68b84d', $dest_file_path, HelloSign\SignatureRequest::FILE_TYPE_ZIP);
Copy
Copied
HelloSignClient client = new HelloSignClient("SIGN_IN_AND_CREATE_API_KEY_FIRST");
String signatureRequestId = "961f25267c4ee995619f1e28f0fcb28d2b68b84d";
File zippedFiles = client.getFiles(signatureRequestId, SignatureRequest.SIGREQ_FORMAT_ZIP);
Copy
Copied
client = HSClient(api_key='SIGN_IN_AND_CREATE_API_KEY_FIRST')
client.get_signature_request_file(
    signature_request_id='961f25267c4ee995619f1e28f0fcb28d2b68b84d',
    filename='mySignedPDF.zip',
    file_type='zip'
)
Copy
Copied
file_bin = client.signature_request_files :signature_request_id => '961f25267c4ee995619f1e28f0fcb28d2b68b84d', :file_type => 'zip'
open("mySignedPDF.zip", "wb") do |file|
    file.write(file_bin)
end
Copy
Copied
const fs = require('fs');
const hellosign = require('hellosign-sdk')({ key: 'SIGN_IN_AND_CREATE_API_KEY_FIRST' });

hellosign.signatureRequest.download(signatureRequestId, { file_type: 'zip' }, (err, res) => {
  const file = fs.createWriteStream('files.zip');

  res.pipe(file);

  file.on('finish', () => {
    file.close();
  });
});
Copy
Copied
var client = new Client("SIGN_IN_AND_CREATE_API_KEY_FIRST");
client.DownloadSignatureRequestFiles(
    "961f25267c4ee995619f1e28f0fcb28d2b68b84d",
    "mySignedPDF.zip",
    SignatureRequest.FileType.ZIP
);