README
Electronic Signature API Examples | HelloSign
Sending a Signature Request
There are two ways to send a Signature Request using the HelloSign API.
Signature Page Template (formerly Reusable Form)
API Method
signature_request/send
signature_request/send_with_reusable_form
Prior Setup
None. Just attach your files with the API request and we’ll append a signature page with a place for each person to sign.
Create a Template (formerly known as a Reusable Form) on the HelloSign site at https://www.hellosign.com/home/createTemplate.
Fields available
1 Signature field per signer.
As many text, signature, initials, checkmark and date fields as required.
Placement
Fields are placed on a separate page appended to your documents. 
Fields are placed inline over the document (wherever you put them). 
Dynamic Custom Fields
N / A
When setting up your Template, you can place Custom Fields on the document. Each field must be named.
When sending the Signature Request using the API, you can fill in each Custom Field with a value. These values will be shown to the signer(s) in the location that you placed that Custom Field. The signer(s) will not be able to edit them.
See the Creating a Template section for more details.
Signature Page
Let’s try it out:
curl -u 'me@hellosign.com:password' 'https://api.hellosign.com/v3/signature_request/send' \
-F 'title=NDA with Acme Co.' \
-F 'subject=The NDA we talked about' \
-F 'message=Please sign this NDA and then we can discuss more. Let me know if you have any questions.' \
-F 'signers[0][email_address]=jack@example.com' \
-F 'signers[0][name]=Jack' \
-F 'signers[1][email_address]=jill@example.com' \
-F 'signers[1][name]=Jill' \
-F 'file[0]=@NDA.pdf' \
-F 'file[1]=@AppendixA.pdf'
Response:
{
"signature_request": {
"signature_request_id": "ed5c515a791db8459a682418367d97d8f7f2c1e4",
"title": "NDA with Acme Co.",
"subject": "NDA with Acme Co.",
"message": "Please sign this NDA and then we can discuss more. Let me know if you have any questions.",
"is_complete": false,
"has_error": false,
"custom_fields": [
],
"response_data": [
],
"signing_url": "https:\/\/www.hellosign.com\/editor\/sign?guid=ed5c515a791db8459a682418367d97d8f7f2c1e4",
"details_url": "https:\/\/www.hellosign.com\/home\/manage?locate=ed5c515a791db8459a682418367d97d8f7f2c1e4",
"requester_email_address": "me@hellosign.com",
"signatures": [
{
"signer_email_address": "jack@example.com",
"signer_name": "Jack",
"order": null,
"status_code": "awaiting_signature",
"signed_at": null,
"last_viewed_at": null,
"last_reminded_at": null
},
{
"signer_email_address": "jill@example.com",
"signer_name": "Jill",
"order": null,
"status_code": "awaiting_signature",
"signed_at": null,
"last_viewed_at": null,
"last_reminded_at": null
}
],
"cc_email_addresses": [
]
}
}
This will generate and send a Signature Request to both jack@example.com and jill@example.com.
Template
Before sending a Template (formerly known as a Reusable Form) via the API you’ll first need to create the Template on the HelloSign site.
Creating a Template through hellosign.com
- Go to .
- Upload a document.
- Specify roles for each signer for example ‘Client’ and ‘Me’.
- Click “Prepare Documents”
- Add fields to be filled out by each role by dragging from the ‘Assign Tasks’ section.
- Add fields for any text or checkmark annotations you’ll want to make at the time of sending. These are referred to by the API as Custom Fields. For example, if you wanted to add a uniquely identifying contract number to the top of each contract, you could add a text field named “contract number” and specify a different contract number to be filled in every time you send the document.
- Save and click Create Template
Finding the reusable_form_id from hellosign.com
We’ll need to tell the API which Template to send and for that we need it’s reusable_form_id. Find the Template on the Documents page and click to select it. The ID is listed in the slide out info panel.
NOTE: The ID will only show up once you have made at least one API request. The easiest call to make is probably a GET /account.
Finding the reusable_form_id with the API
To find the reusable_form_id via the API call reusable_form/list and find the object with the title and roles you supplied.
curl -u 'me@hellosign.com:password' 'https://api.hellosign.com/v3/reusable_form/list'
#For formatted JSON output try: curl -u 'me@hellosign.com:password' 'https://api.hellosign.com/v3/reusable_form/list' | python -mjson.tool"
{
"list_info": {
"num_pages": 1,
"num_results": 1,
"page": 1,
"page_size": 20
},
"reusable_forms": [
{
"accounts": [
{
"account_id": "c82e1992b64ba763e6716a05a0860f47e67ea6ee",
"email_address": "me@hellosign.com"
}
],
"cc_roles": [],
"documents": [
{
"index": 0,
"name": "mutual_nda.pdf"
"form_fields": [
{
"name": "VendorName",
"type": "text",
"x": 160,
"y": 141,
"width": 80,
"height": 30,
"required": true
},
{
"name": "VendorTitle",
"type": "text",
"x": 160,
"y": 181,
"width": 80,
"height": 30,
"required": true
},
{
"name": "ManagerName",
"type": "text",
"x": 160,
"y": 221,
"width": 80,
"height": 30,
"required": true
},
{
"name": "ManagerTitle",
"type": "text",
"x": 160,
"y": 251,
"width": 80,
"height": 30,
"required": true
},
{
"name": "DateSigned",
"type": "date_signed",
"x": 523,
"y": 28,
"width": 105,
"height": 16,
"required": true
}
],
"custom_fields": [
{
"name": "contract number",
"type": "text"
}
],
}
],
"message": "",
"reusable_form_id": "5eb54aaaa71ce8dcaec5d06e93a2754af1712606",
"signer_roles": [
{
"name": "Client",
"order": null
},
{
"name": "Me",
"order": null
}
],
"title": "Demo Form"
}
]
}
Sending a Signature Request with a Template
curl -u 'me@hellosign.com:password' 'https://api.hellosign.com/v3/signature_request/send_with_reusable_form' \
-F 'title=NDA with Acme Co.' \
-F 'subject=The NDA we talked about' \
-F 'message=Please sign this NDA and then we can discuss more. Let me know if you have any questions.' \
-F 'signers[Me][email_address]=jack@example.com' \
-F 'signers[Me][name]=Jack' \
-F 'signers[Client][email_address]=jill@example.com' \
-F 'signers[Client][name]=Jill' \
-F 'custom_fields[contract number]=DD21' \
-F 'reusable_form_id=5eb54aaaa71ce8dcaec5d06e93a2754af1712606'
Response:
{
"signature_request": {
"cc_email_addresses": [],
"custom_fields": [
{
"name": "contract number",
"value": "DD21",
"type": "text"
}
],
"details_url": "https://www.hellosign.com/home/manage?locate=961f25267c4ee995619f1e28f0fcb28d2b68b84d",
"has_error": false,
"is_complete": false,
"message": "Please sign this NDA and then we can discuss more. Let me know if you have any questions.",
"requester_email_address": "me@hellosign.com",
"response_data": [],
"signature_request_id": "961f25267c4ee995619f1e28f0fcb28d2b68b84d",
"signatures": [
{
"last_reminded_at": null,
"last_viewed_at": null,
"order": null,
"signed_at": null,
"signer_email_address": "jack@example.com",
"signer_name": "Jack",
"status_code": "awaiting_signature"
},
{
"last_reminded_at": null,
"last_viewed_at": null,
"order": null,
"signed_at": null,
"signer_email_address": "jill@example.com",
"signer_name": "Jill",
"status_code": "awaiting_signature"
}
],
"signing_url": "https://www.hellosign.com/editor/sign?guid=961f25267c4ee995619f1e28f0fcb28d2b68b84d",
"subject": "The NDA we talked about",
"title": "NDA with Acme Co."
}
}
jack@example.com and jill@example.com will receive an email shortly. When they click on the link in the email they will be brought straight to the Document to sign.
Retrieving the signed document
Once they have signed the document you can download the final PDF using the API.
Downloading the signed PDF
curl -o mySignedPDF.pdf "https://api.hellosign.com/v3/signature_request/final_copy/961f25267c4ee995619f1e28f0fcb28d2b68b84d" -u "me@hellosign.com:password"
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 because of the amount of time things like signature requests can take to complete.
Webhooks (preferred)
Setting your callback url
curl -u 'me@hellosign.com:password' 'https://api.hellosign.com/v3/account' \
-F 'callback_url=http://example.com/my_HelloSign_webhook_endpoint'
Response:
{
"account": {
"account_id": "c82e1992b64ba763e6716a05a0860f47e67ea6ee",
"callback_url": "http://example.com/hellosign_callback_script.php",
"email_address": "me@hellofax.com",
"role_code": null
}
}
Handling callbacks
When events (signature request sent, signature request viewed, signature request signed, etc) are triggered we’ll send a POST request to your callback url. The ‘json’ param will be populated with a JSON string containing an Event object as well as any relevant model objects structured like this:
{
"event": {
"event_time": "1348177752",
"event_type": "signature_request_sent"
},
"signature_request": {
"cc_email_addresses": [],
"custom_fields": [],
"details_url": "https://www.hellosign.com/home/manage?locate=1f8c510a38edbdf97eed524fba1c9a900feb56a4",
"has_error": false,
"is_complete": false,
"message": "Please sign this NDA and then we can discuss more. Let me know if you have any questions.",
"requester_email_address": "me@hellosign.com",
"response_data": [],
"signature_request_id": "1f8c510a38edbdf97eed524fba1c9a900feb56a4",
"signatures": [
{
"last_reminded_at": null,
"last_viewed_at": null,
"order": null,
"signed_at": null,
"signer_email_address": "jack@example.com",
"signer_name": "Jack",
"status_code": "awaiting_signature"
}
],
"signing_url": "https://www.hellosign.com/editor/sign?guid=1f8c510a38edbdf97eed524fba1c9a900feb56a4",
"subject": "NDA with Acme Co.",
"title": "NDA with Acme Co."
}
}
NOTE: Your endpoint will need to return a 200 HTTP code and a response body containing the following text: Hello API Event Received. Otherwise, the callback will be considered a failure and will be retried later.
Polling
Warning
Signature Requests can take days to complete, especially with multiple signers. 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
curl -u "me@hellofax.com:password" "https://api.hellosign.com/v3/signature_request/961f25267c4ee995619f1e28f0fcb28d2b68b84d"
Response:
{
"signature_request": {
"cc_email_addresses": [],
"custom_fields": [],
"details_url": "https://www.hellosign.com/home/manage?locate=961f25267c4ee995619f1e28f0fcb28d2b68b84d",
"has_error": false,
"is_complete": true,
"message": "Please sign this NDA and then we can discuss more. Let me know if you have any questions.",
"requester_email_address": "me@hellosign.com",
"response_data": [],
"signature_request_id": "961f25267c4ee995619f1e28f0fcb28d2b68b84d",
"signatures": [
{
"last_reminded_at": null,
"last_viewed_at": null,
"order": null,
"signed_at": 1348092474,
"signer_email_address": "jack@example.com",
"signer_name": "Jack",
"status_code": "signed"
},
{
"last_reminded_at": null,
"last_viewed_at": null,
"order": null,
"signed_at": 1348092432,
"signer_email_address": "jill@example.com",
"signer_name": "Jill",
"status_code": "signed"
}
],
"signing_url": null,
"subject": "The NDA we talked about",
"title": "The NDA we talked about"
}
}