API Documentation

Jump to

Account
SignatureRequest
ReusableForm
Team
UnclaimedDraft

Events
Errors and Warnings
Account Contains information about an account and its settings

Account

Response Object.
account_id The id of the Account.
email_address The email address associated with the Account.
callback_url The URL that HelloSign events will be POSTed to.
role_code The membership role for the team. O = Owner, M = Member.
URI Description
GET /accountReturns your Account settings. 

Description

Returns the properties and settings of your Account.

Request Parameters

None

Response

Returns an Account object

Example request / response

GET https://[username]:[password]@api.hellosign.com/v3/account

CURL:

Request: 
curl -u 'me@hellosign.com:password' 'https://api.hellosign.com/v3/account'

Response: 
{
    "account": {
        "account_id": "5008b25c7f67153e57d5a357b1687968068fb465",
        "email_address": "me@hellosign.com",
        "callback_url": null,
        "role_code": null
    }
}
POST /accountUpdates your Account's settings. 

Description

Updates the properties and settings of your Account.

Request Parameters

callback_urloptional
The URL that HelloSign should POST events to.

Response

Returns an Account object

Example request / response

POST https://[username]:[password]@api.hellosign.com/v3/account

callback_url=https://www.example.com/callback

CURL:

Request: 
curl -u 'me@hellosign.com:password' 'https://api.hellosign.com/v3/account' \
	-F 'callback_url=https://www.example.com/callback'

Response: 
{
    "account": {
        "account_id": "5008b25c7f67153e57d5a357b1687968068fb465",
        "email_address": "me@hellosign.com",
        "callback_url": "https://www.example.com/callback",
        "role_code": null
    }
}
POST /account/createSigns up for a new HelloSign Account. 

Description

Creates a new HelloSign Account that is associated with the specified email_address and password.

Request Parameters

email_address
The email address to create a new Account for.
password
The password for the new Account.

Response

Returns an Account object

Example request / response

POST https://[username]:[password]@api.hellosign.com/v3/account/create

email_address=newuser@hellosign.com
password=securePW

CURL:

Request: 
curl 'https://api.hellosign.com/v3/account/create' \
	-F 'email_address=newuser@hellosign.com' \
	-F 'password=securePW'

Response: 
{
	"account": {
		"account_id": "a2b31224f7e6fb5581d2f8cbd91cf65fa2f86aae",
		"email_address": "newuser@hellosign.com",
		"callback_url": null,
		"role_code": null
	}
}
SignatureRequest Contains information regarding documents that need to be signed

SignatureRequest

Response Object.
signature_request_id The id of the SignatureRequest.
requester_email_address The email address of the initiator of the SignatureRequest.
title The title the specified Account uses for the SignatureRequest.
subject The subject in the email that was initially sent to the signers.
message The custom message in the email that was initially sent to the signers.
is_complete Whether or not the SignatureRequest has been fully executed by all signers.
has_error Whether or not an error occured (either during the creation of the SignatureRequest or during one of the signings).
final_copy_uri The relative URI where the PDF copy of the finalized documents can be downloaded. Only present when is_complete = true.
signing_url The URL where a signer, after authenticating, can sign the documents.
details_url The URL where the requester and the signers can view the current status of the SignatureRequest.
cc_email_addresses A list of email addresses that were CCed on the SignatureRequest. They will receive a copy of the final PDF once all the signers have signed.
custom_fields An array of Custom Field objects containing the name and type of each custom field.
name The name of the Custom Field.
type The type of this Custom Field. Currently, 'text' is the only valid value.
response_data An array of form field objects containing the name, value, and type of each textbox or checkmark field filled in by the signers.
name The name of the form field.
value The value of the form field.
type The type of this form field. eg: text, signature, initial, checkmark.
signatures An array of signature obects, 1 for each signer.
signer_email_address The email address of the signer.
signer_name The name of the signer.
order If signer order is assigned this is the 0-based index for this signer.
status_code The current status of the signature. eg: awaiting_signature, signed, on_hold
signed_at Time that the document was signed or null.
last_viewed_at The time that the document was last viewed by this signer or null.
last_reminded_at The time the last reminder email was sent to the signer or null.
URI Description
GET /signature_request/[:signature_request_id]Gets a SignatureRequest that includes the current status for each signer 

Description

Returns the status of the SignatureRequest specified by the signature_request_id parameter.

Request Parameters

signature_request_id
The id of the SignatureRequest to retrieve.

Response

Returns a SignatureRequest object

Example request / response

GET https://[username]:[password]@api.hellosign.com/v3/signature_request/[:signature_request_id]

CURL:

Request: 
curl -u 'me@hellosign.com:password' 'https://api.hellosign.com/v3/signature_request/fa5c8a0b0f492d768749333ad6fcc214c111e967'

Response: 
{
	"signature_request": {
		"signature_request_id": "fa5c8a0b0f492d768749333ad6fcc214c111e967",
		"title": "Purchase Agreement",
		"subject": "Purchase Agreement",
		"message": "Please sign and return.",
		"is_complete": true,
		"has_error": false,
		"custom_fields": [
		],
		"response_data": [
			{
				"name": "Needs Express Shipping",
				"value": true,
				"type": "checkbox"
			},
			{
				"name": "Shipping Address",
				"value": "1212 Park Avenuee",
				"type": "text"
			},
			{
				"name": "DateSigned",
				"value": "09\/01\/2012",
				"type": "text"
			}
		],
		"signing_url": null,
		"details_url": "https:\/\/www.hellosign.com\/home\/manage?guid=fa5c8a0b0f492d768749333ad6fcc214c111e967",
		"requester_email_address": "me@hellosign.com",
		"signatures": [
			{
				"signer_email_address": "john@example.com",
				"signer_name": "John Doe",
				"order": null,
				"status_code": "signed",
				"signed_at": 1346521550,
				"last_viewed_at": 1346521483,
				"last_reminded_at": null
			}
		],
		"cc_email_addresses": [
		]
	}
}
GET /signature_request/listLists the SignatureRequests (both inbound and outbound) that you have access to. 

Description

Returns a list of SignatureRequests that you can access. This includes SignatureRequests you have sent as well as received, but not ones that you have been CCed on.

Request Parameters

pageoptional
Which page number of the ReusableForm List to return. Defaults to 1.

Response Parameters

list_info
A ListInfo object
num_pages
Total number of pages available
num_results
Total number of objects available
page
Number of the page being returned
page_size
Objects returned per page
signature_requests
An array of SignatureRequest objects.

Example request / response

GET https://[username]:[password]@api.hellosign.com/v3/signature_request/list

CURL:

Request: 
curl -u 'me@hellosign.com:password' 'https://api.hellosign.com/v3/signature_request/list?page=1'

Response: 
{
	"list_info": {
		"page": 1,
		"num_pages": 1,
		"num_results": 2,
		"page_size": 20
	},
	"signature_requests": [
		{
			"signature_request_id": "d10338cad145e1cb68afc828348c3fe3bd534bb1",
			"title": "FHA",
			"subject": "FHA",
			"message": "Let me know if you two have any questions.",
			"is_complete": false,
			"has_error": false,
			"custom_fields": [
			],
			"response_data": [
			],
			"signing_url": "https:\/\/www.hellosign.com\/editor\/sign?guid=d10338cad145e1cb68afc828348c3fe3bd534bb1",
			"details_url": "https:\/\/www.hellosign.com\/home\/manage?guid=d10338cad145e1cb68afc828348c3fe3bd534bb1",
			"requester_email_address": "me@hellosign.com",
			"signatures": [
				{
					"signer_email_address": "george-jetson@example.com",
					"signer_name": "George Jetson",
					"order": 0,
					"status_code": "awaiting_signature",
					"signed_at": null,
					"last_viewed_at": null,
					"last_reminded_at": null
				},
				{
					"signer_email_address": "jane-jetson@example.com",
					"signer_name": "Jane Jetson",
					"order": 1,
					"status_code": "awaiting_signature",
					"signed_at": null,
					"last_viewed_at": null,
					"last_reminded_at": null
				}
			],
			"cc_email_addresses": [
				"stan@example.com"
			]
		},
		{
			"signature_request_id": "fa5c8a0b0f492d768749333ad6fcc214c111e967",
			"title": "Purchase Agreement",
			"subject": "Purchase Agreement",
			"message": "Please sign and return.",
			"is_complete": true,
			"has_error": false,
			"custom_fields": [
			],
			"response_data": [
				{
					"name": "Needs Express Shipping",
					"value": true,
					"type": "checkbox"
				},
				{
					"name": "Shipping Address",
					"value": "1212 Park Avenuee",
					"type": "text"
				},
				{
					"name": "DateSigned",
					"value": "09\/01\/2012",
					"type": "date_signed"
				}
			],
			"signing_url": null,
			"details_url": "https:\/\/www.hellosign.com\/home\/manage?guid=fa5c8a0b0f492d768749333ad6fcc214c111e967",
			"requester_email_address": "me@hellosign.com",
			"signatures": [
				{
					"signer_email_address": "john@example.com",
					"signer_name": "John Doe",
					"order": null,
					"status_code": "signed",
					"signed_at": 1346521550,
					"last_viewed_at": 1346521483,
					"last_reminded_at": null
				}
			],
			"cc_email_addresses": [
			]
		}
	]
}
POST /signature_request/sendCreates and sends a new SignatureRequest with the submitted documents. 

Description

Creates and sends a new SignatureRequest with the submitted documents. If form_fields_per_document is not specified, a signature page will be affixed where all signers will be required to add their signature, signifying their agreement to all contained documents.

Request Parameters

file[]
The file(s) to send for signature.
titleoptional
The title you want to assign to the SignatureRequest.
subjectoptional
The subject in the email that will be sent to the signers.
messageoptional
The custom message in the email that will be sent to the signers.
signers[%i%][name]
The name of the signer. %i% is an integer that should be unique for each signer.
signers[%i%][email_address]
The email address of the signer. %i% is an integer that should be unique for each signer.
signers[%i%][order]optional
The order the signer is required to sign in. %i% is an integer that should be unique for each signer.
cc_email_addresses[]optional
The email addresses that should be CCed.
form_fields_per_documentoptional
The fields that should appear on the document, expressed as a serialized JSON data structure which is a list of lists of the form fields. One list is required for each file[]. In the case of a file with no fields, an empty list must be specified. Each field must identify which signer is supposed to fill out the field, which type of field it is, its location and size, and if it is required. The signer is identified by the offset (%i%) in the "signers" parameter. ReusableForm objects contain fields of the this type in "form_fields". 
[
				[
				{
					"name": "",
					"type": "text",
					"x": 112,
					"y": 328,
					"width": 100,
					"height": 16,
					"required": true,
					"signer": 2
				},
				{
					"name": "",
					"type": "signature",
					"x": 530,
					"y": 415,
					"width": 120,
					"height": 30,
					"required": true,
					"signer": 1
				}],
				[]
]

Response

Returns a SignatureRequest object

Example request / response

POST https://[username]:[password]@api.hellosign.com/v3/signature_request/send

title=NDA with Acme Co.
subject=The NDA we talked about
message=Please sign this NDA and then we can discuss more. Let me know if you have any questions.
signers[0][email_address]=jack@example.com
signers[0][name]=Jack
signers[0][order]=0
signers[1][email_address]=jill@example.com
signers[1][name]=Jill
signers[1][order]=1
cc_email_addresses[0]=lawyer@hellosign.com
cc_email_addresses[1]=lawyer@example.com
file[1]=@NDA.pdf
file[2]=@AppendixA.pdf

CURL:

Request: 
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[0][order]=0' \
	-F 'signers[1][email_address]=jill@example.com' \
	-F 'signers[1][name]=Jill' \
	-F 'signers[1][order]=1' \
	-F 'cc_email_addresses[0]=lawyer@hellosign.com' \
	-F 'cc_email_addresses[1]=lawyer@example.com' \
	-F 'file[1]=@NDA.pdf' \
	-F 'file[2]=@AppendixA.pdf'

Response: 
{
	"signature_request": {
		"signature_request_id": "a9f4825edef25f47e7b4c14ce8100d81d1693160",
		"title": "NDA with Acme Co.",
		"subject": "The NDA we talked about",
		"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=a9f4825edef25f47e7b4c14ce8100d81d1693160",
		"details_url": "https:\/\/www.hellosign.com\/home\/manage?guid=a9f4825edef25f47e7b4c14ce8100d81d1693160",
		"requester_email_address": "me@hellosign.com",
		"signatures": [
			{
				"signer_email_address": "jack@example.com",
				"signer_name": "Jack",
				"order": 0,
				"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": 1,
				"status_code": "awaiting_signature",
				"signed_at": null,
				"last_viewed_at": null,
				"last_reminded_at": null
			}
		],
		"cc_email_addresses": [
			"lawyer@hellosign.com",
			"lawyer@example.com"
		]
	}
}
POST /signature_request/send_with_reusable_formCreates and sends a new SignatureRequest based off of a ReusableForm. 

Description

Creates and sends a new SignatureRequest based off of the ReusableForm specified with the reusable_form_id parameter.

Request Parameters

reusable_form_id
The id of the ReusableForm to use when creating the SignatureRequest.
titleoptional
The title you want to assign to the SignatureRequest.
subjectoptional
The subject in the email that will be sent to the signers.
messageoptional
The custom message in the email that will be sent to the signers.
signers[%RoleName%][name]
The name of the signer filling the role of RoleName.
signers[%RoleName%][email_address]
The email address of the signer filling the role of RoleName.
ccs[%RoleName%][email_address]optional
The email address of the CC filling the role of RoleName. Required when a CC role exists for the ReusableForm.
custom_fields[%CustomFieldName%]optional
The value to fill in for custom field with the name of CustomFieldName. Required when a CustomField exists in the ReusableForm.

Response

Returns a SignatureRequest object

Example request / response

POST https://[username]:[password]@api.hellosign.com/v3/signature_request/send_with_reusable_form

reusable_form_id=c26b8a16784a872da37ea946b9ddec7c1e11dff6
subject=Purchase Order
message=Glad we could come to an agreement.
signers[Client][name]=George
signers[Client][email_address]=george@example.com
ccs[Accounting][email_address]=accounting@hellosign.com
custom_fields[Cost]=$20,000

CURL:

Request: 
curl -u 'me@hellosign.com:password' 'https://api.hellosign.com/v3/signature_request/send_with_reusable_form' \
	-F 'reusable_form_id=c26b8a16784a872da37ea946b9ddec7c1e11dff6' \
	-F 'subject=Purchase Order' \
	-F 'message=Glad we could come to an agreement.' \
	-F 'signers[Client][name]=George' \
	-F 'signers[Client][email_address]=george@example.com' \
	-F 'ccs[Accounting][email_address]=accounting@hellosign.com' \
	-F 'custom_fields[Cost]=$20,000'

Response: 
{
	"signature_request": {
		"signature_request_id": "17d163069282df5eb63857d31ff4a3bffa9e46c0",
		"title": "Purchase Order",
		"subject": "Purchase Order",
		"message": "Glad we could come to an agreement.",
		"is_complete": false,
		"has_error": false,
		"custom_fields": [
			{
				"name": "Cost",
				"value": "$20,000",
				"type": "text"
			}
		],
		"response_data": [
		],
		"signing_url": "https:\/\/www.hellosign.com\/editor\/sign?guid=17d163069282df5eb63857d31ff4a3bffa9e46c0",
		"details_url": "https:\/\/www.hellosign.com\/home\/manage?guid=17d163069282df5eb63857d31ff4a3bffa9e46c0",
		"requester_email_address": "me@hellosign.com",
		"signatures": [
			{
				"signer_email_address": "george@example.com",
				"signer_name": "George",
				"order": null,
				"status_code": "awaiting_signature",
				"signed_at": null,
				"last_viewed_at": null,
				"last_reminded_at": null
			}
		],
		"cc_email_addresses": [
			"accounting@hellosign.com"
		]
	}
}
POST /signature_request/remind/[:signature_request_id]Sends an email to the signer reminding them to sign the signature request. 

Description

Sends an email to the signer reminding them to sign the signature request. You cannot send a reminder within 12 hours of the last reminder that was sent. This includes manual AND automatic reminders.

Request Parameters

signature_request_id
The id of the SignatureRequest to send a reminder for.
email_address
The email address of the signer to send a reminder to.

Response

Returns a SignatureRequest object

Example request / response

POST https://[username]:[password]@api.hellosign.com/v3/signature_request/remind/[:signature_request_id]

email_address=john@example.com

CURL:

Request: 
curl -u 'me@hellosign.com:password' 'https://api.hellosign.com/v3/signature_request/remind/2f9781e1a8e2045224d808c153c2e1d3df6f8f2f' \
	-F 'email_address=john@example.com'

Response: 
{
	"signature_request": {
		"signature_request_id": "2f9781e1a8e2045224d808c153c2e1d3df6f8f2f",
		"title": "ok",
		"subject": "ok",
		"message": null,
		"is_complete": false,
		"has_error": false,
		"custom_fields": [
		],
		"response_data": [
		],
		"signing_url": "https:\/\/www.hellosign.com\/editor\/sign?guid=2f9781e1a8e2045224d808c153c2e1d3df6f8f2f",
		"details_url": "https:\/\/www.hellosign.com\/home\/manage?guid=2f9781e1a8e2045224d808c153c2e1d3df6f8f2f",
		"requester_email_address": "me@hellosign.com",
		"signatures": [
			{
				"signer_email_address": "john@example.com",
				"signer_name": "John Doe",
				"order": 0,
				"status_code": "awaiting_signature",
				"signed_at": null,
				"last_viewed_at": null,
				"last_reminded_at": 1346616433
			}
		],
		"cc_email_addresses": [
		]
	}
}
POST /signature_request/cancel/[:signature_request_id]Cancels a SignatureRequest. 

Description

Cancels a SignatureRequest. After canceling, no one will be able to sign or access the SignatureRequest or its documents. Only the requester can cancel and only before everyone has signed.

Request Parameters

signature_request_id
The id of the SignatureRequest to cancel.

Example request / response

POST https://[username]:[password]@api.hellosign.com/v3/signature_request/cancel/[:signature_request_id]

CURL:

Request: 
curl -u 'me@hellosign.com:password' -X POST 'https://api.hellosign.com/v3/signature_request/cancel/2f9781e1a8e2045224d808c153c2e1d3df6f8f2f'

Response: 
N/A (HTTP Status Code 200)
GET /signature_request/final_copy/[:signature_request_id]Download the PDF copy of the finalized documents. 

Description

Download the PDF copy of the finalized documents specified by the signature_request_id parameter.

Request Parameters

signature_request_id
The id of the SignatureRequest to retrieve.

Response

Returns a PDF

Example request / response

GET https://[username]:[password]@api.hellosign.com/v3/signature_request/final_copy/[:signature_request_id]

CURL:

Request: 
curl -u 'me@hellosign.com:password' 'https://api.hellosign.com/v3/signature_request/final_copy/f57db65d3f933b5316d398057a36176831451a35'  -o final-copy.pdf

Response: 
N/A (final-copy.pdf will be created)
ReusableForm Contains information about the templates you and your team have created

ReusableForm

Response Object.
reusable_form_id The id of the ReusableForm.
title The title of the ReusableForm. This will also be the default subject of the message sent to signers when using this ReusableForm to send a SignatureRequest. This can be overriden when sending the SignatureRequest.
message The default message that will be sent to signers when using this ReusableForm to send a SignatureRequest. This can be overriden when sending the SignatureRequest.
signer_roles An array of the designated signer roles that must be specified when sending a SignatureRequest using this ReusableForm.
name The name of the Role.
order If signer order is assigned this is the 0-based index for this role.
cc_roles An array of the designated CC roles that must be specified when sending a SignatureRequest using this ReusableForm.
name The name of the Role.
documents An array describing each document associated with this ReusableForm. Includes form field data for each document.
form_fields An array of Form Field objects containing the name and type of each named textbox and checkmark field.
name The name of the form field.
type The type of this form field. eg: text, signature, initial, checkmark.
x The x location of this form field.
y The y location of this form field.
width The width of this form field.
height The height of this form field.
required Boolean showing whether or not this field is required.
custom_fields An array of Custom Field objects containing the name and type of each custom field.
name The name of the Custom Field.
type The type of this Custom Field. Currently, 'text' is the only valid value.
accounts An array of the Accounts that can use this ReusableForm.
account_id The id of the Account.
email_address The email address associated with the Account.
URI Description
GET /reusable_form/[:reusable_form_id]Gets a ReusableForm which includes a list of Accounts that can access it. 

Description

Returns the ReusableForm specified by the id parameter.

Request Parameters

reusable_form_id
The id of the ReusableForm to retrieve.

Response

Returns a ReusableForm object

Example request / response

GET https://[username]:[password]@api.hellosign.com/v3/reusable_form/[:reusable_form_id]

CURL:

Request: 
curl -u 'me@hellosign.com:password' 'https://api.hellosign.com/v3/reusable_form/f57db65d3f933b5316d398057a36176831451a35'

Response: 
{
	"reusable_form": {
		"reusable_form_id": "f57db65d3f933b5316d398057a36176831451a35",
		"title": "Mutual NDA",
		"message": "Please sign this NDA as soon as possible.",
		"signer_roles": [
			{
				"name": "Outside Vendor",
				"order": 0
			},
			{
				"name": "Internal Manager",
				"order": 1
			}
		],
		"cc_roles": [
			{
				"name": "Corporate Attorney"
			}
		],
		"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": "Effective Date",
						"type": "text"
					}
				],
			}
		],
		"accounts": [
			{
				"account_id": "5008b25c7f67153e57d5a357b1687968068fb465",
				"email_address": "me@hellosign.com"
			}
		]
	}
}
GET /reusable_form/listLists your ReusableForms. 

Description

Returns a list the ReusableForms that are accessible by you.

Request Parameters

pageoptional
Which page number of the ReusableForm List to return. Defaults to 1.

Response Parameters

list_info
A ListInfo object
num_pages
Total number of pages available
num_results
Total number of objects available
page
Number of the page being returned
page_size
Objects returned per page
reusable_forms
An array of ReusableForm objects.

Example request / response

GET https://[username]:[password]@api.hellosign.com/v3/reusable_form/list

CURL:

Request: 
curl -u 'me@hellosign.com:password' 'https://api.hellosign.com/v3/reusable_form/list?page=1'

Response: 
{
	"list_info": {
		"page": 1,
		"num_pages": 1,
		"num_results": 2,
		"page_size": 20
	},
	"reusable_forms": [
		{
			"reusable_form_id": "c26b8a16784a872da37ea946b9ddec7c1e11dff6",
			"title": "Purchase order",
			"message": "",
			"signer_roles": [
				{
					"name": "Client"
				}
			],
			"cc_roles": [
				{
					"name": "Accounting"
				}
			],
			"documents": [
				{
					"index": 0,
					"name": "purchase_order.pdf"
					"form_fields": [
					],
					"custom_fields": [
						{
							"name": "Cost",
							"type": "text"
						}
					],
				}
			],				
			"accounts": [
				{
					"account_id": "5008b25c7f67153e57d5a357b1687968068fb465",
					"email_address": "me@hellosign.com"
				}
			]
		},
		{
			"reusable_form_id": "21f920ec2b7f4b6bb64d3ed79f26303843046536",
			"title": "Mutual NDA",
			"message": "Please sign this NDA as soon as possible.",
			"signer_roles": [
				{
					"name": "Outside Vendor",
					"order": 0
				},
				{
					"name": "Internal Manager",
					"order": 1
				}
			],
			"cc_roles": [
				{
					"name": "Corporate Attorney"
				}
			],
		"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": "Effective Date",
						"type": "text"
					}
				],
			}
		],				
		"accounts": [
				{
					"account_id": "5008b25c7f67153e57d5a357b1687968068fb465",
					"email_address": "me@hellosign.com"
				}
			]
		}
	]
}
POST /reusable_form/add_user/[:reusable_form_id]Gives the specified Account access to the specified ReusableForm. 

Description

Gives the specified Account access to the specified ReusableForm. The specified Account must be a part of your Team.

Request Parameters

reusable_form_id
The id of the ReusableForm to give the Account access to.
account_id OR email_address
The id or email address of the Account to give access to the ReusableForm. The account id prevails if both are provided.

Response

Returns a ReusableForm object

Example request / response

POST https://[username]:[password]@api.hellosign.com/v3/reusable_form/add_user/[:reusable_form_id]

email_address=george@hellofax.com

CURL:

Request: 
curl -u 'me@hellosign.com:password' 'https://api.hellosign.com/v3/reusable_form/add_user/21f920ec2b7f4b6bb64d3ed79f26303843046536' \
	-F 'email_address=george@hellosign.com'

Response: 
{
	"reusable_form": {
		"reusable_form_id": "21f920ec2b7f4b6bb64d3ed79f26303843046536",
		"title": "Mutual NDA",
		"message": "Please sign this NDA as soon as possible.",
		"signer_roles": [
			{
				"name": "Outside Vendor",
				"order": 0
			},
			{
				"name": "Internal Manager",
				"order": 1
			}
		],
		"cc_roles": [
			{
				"name": "Corporate Attorney"
			}
		],
		"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": "Effective Date",
						"type": "text"
					}
				],
			}
		],				
		"accounts": [
			{
				"account_id": "5008b25c7f67153e57d5a357b1687968068fb465",
				"email_address": "me@hellosign.com"
			},
			{
				"account_id": "",
				"email_address": "teammate@hellosign.com"
			}
		]
	}
}
POST /reusable_form/remove_user/[:reusable_form_id]Removes the specified Account's access to the specified ReusableForm. 

Description

Removes the specified Account's access to the specified ReusableForm.

Request Parameters

reusable_form_id
The id of the ReusableForm to remove the Account's access to.
account_id OR email_address
The id or email address of the Account to remove access to the ReusableForm. The account id prevails if both are provided.

Response

Returns a ReusableForm object

Example request / response

POST https://[username]:[password]@api.hellosign.com/v3/reusable_form/remove_user/[:reusable_form_id]

email_address=george@hellofax.com

CURL:

Request: 
curl -u 'me@hellosign.com:password' 'https://api.hellosign.com/v3/reusable_form/remove_user/21f920ec2b7f4b6bb64d3ed79f26303843046536' \
	-F 'email_address=george@hellosign.com'

Response: 
{
	"reusable_form": {
		"reusable_form_id": "21f920ec2b7f4b6bb64d3ed79f26303843046536",
		"title": "Mutual NDA",
		"message": "Please sign this NDA as soon as possible.",
		"signer_roles": [
			{
				"name": "Outside Vendor",
				"order": 0
			},
			{
				"name": "Internal Manager",
				"order": 1
			}
		],
		"cc_roles": [
			{
				"name": "Corporate Attorney"
			}
		],
		"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": "Effective Date",
						"type": "text"
					}
				],
			}
		],				
		"accounts": [
			{
				"account_id": "5008b25c7f67153e57d5a357b1687968068fb465",
				"email_address": "me@hellosign.com"
			}
		]
	}
}
Team Contains information about your team and its members

Team

Response Object.
name The name of your Team.
accounts A list of all Accounts belonging to your Team. Note that this response is a subset of the response parameters found in GET /account.
account_id The id of the Account.
email_address The email address associated with the Account.
role_code The membership role for the team. O = Owner, M = Member.
invited_accounts A list of all Accounts that have an outstanding invitation to join your Team. Note that this response is a subset of the response parameters found in GET /account.
account_id The id of the Account.
email_address The email address associated with the Account.
URI Description
GET /teamGets your Team and a list of its members 

Description

Returns information about your Team as well as a list of its members. If you do not belong to a Team, a 404 error with an error_name of "not_found" will be returned.

Request Parameters

None

Response

Returns a Team object

Example request / response

GET https://[username]:[password]@api.hellosign.com/v3/team

CURL:

Request: 
curl -u 'me@hellosign.com:password' 'https://api.hellosign.com/v3/team'

Response: 
{
	"team": {
		"name": "Team HelloSign",
		"accounts": [
			{
				"account_id": "5008b25c7f67153e57d5a357b1687968068fb465",
				"email_address": "me@hellosign.com",
				"role_code": "a"
			},
			{
				"account_id": "d3d3d7b98d80b67d07740df7cdfd1f49fa8e2b82",
				"email_address": "teammate@hellosign.com",
				"role_code": "m"
			}
		],
		"invited_accounts": [
		]
	}
}
POST /team/createCreates a new Team 

Description

Creates a new Team and makes you a member. You must not currently belong to a Team to invoke.

Request Parameters

name
The name of your Team

Response

Returns a Team object

Example request / response

POST https://[username]:[password]@api.hellosign.com/v3/team/create

name=Team America World Police

CURL:

Request: 
curl -u 'me@hellosign.com:password' 'https://api.hellosign.com/v3/team/create' \
	-F 'name=Team America World Police'

Response: 
{
	"team": {
		"name": "Team America World Police",
		"accounts": [
			{
				"account_id": "5008b25c7f67153e57d5a357b1687968068fb465",
				"email_address": "me@hellosign.com",
				"role_code": "a"
			}
		],
		"invited_accounts": [
		]
	}
}
POST /teamUpdates a Team's name 

Description

Updates the name of your Team. If you do not have a Team, a new Team is created.

Request Parameters

name
The name of your Team

Response

Returns a Team object

Example request / response

POST https://[username]:[password]@api.hellosign.com/v3/team

name=New Team Name

CURL:

Request: 
curl -u 'me@hellosign.com:password' 'https://api.hellosign.com/v3/team' \
	-F 'name=New Team Name'

Response: 
{
	"team": {
		"name": "New Team Name",
		"accounts": [
			{
				"account_id": "5008b25c7f67153e57d5a357b1687968068fb465",
				"email_address": "me@hellosign.com",
				"role_code": "a"
			}
		],
		"invited_accounts": [
		]
	}
}
POST /team/destroyDeletes your Team. 

Description

Deletes your Team. Can only be invoked when you have a Team with only one member (yourself).

Request Parameters

None

Example request / response

POST https://[username]:[password]@api.hellosign.com/v3/team/destroy

CURL:

Request: 
curl -u 'me@hellosign.com:password' -X POST 'https://api.hellosign.com/v3/team/destroy'

Response: 
N/A (HTTP Status Code 200)
POST /team/add_memberAdds or invites a user to your Team 

Description

Adds or invites a user (specified using the email_address parameter) to your Team. If the user does not currently have a HelloSign Account, a new one will be created for them. If the user currently has a paid subscription, they will not automatically join the Team but instead will be sent an invitation to join. If a user is already a part of another Team, a "team_invite_failed" error will be returned.

Request Parameters

account_id OR email_address
The id or email address of the Account of the user to invite to your Team. The account id prevails if both are provided.

Response

Returns a Team object

Example requests / responses

POST https://[username]:[password]@api.hellosign.com/v3/team/add_member

email_address=george@hellofax.com

CURL:

Request: 
curl -u 'me@hellosign.com:password' 'https://api.hellosign.com/v3/team/add_member' \
	-F 'email_address=george@hellosign.com'

Response: 
{
	"team": {
		"name": "New Team Name",
		"accounts": [
			{
				"account_id": "5008b25c7f67153e57d5a357b1687968068fb465",
				"email_address": "me@hellosign.com",
				"role_code": "a"
			},
			{
				"account_id": "8e239b5a50eac117fdd9a0e2359620aa57cb2463",
				"email_address": "george@hellosign.com",
				"role_code": "m"
			}
		],
		"invited_accounts": [
		]
	}
}
POST /team/remove_memberRemoves a user from your Team 

Description

Removes a user from your Team. If the user had an outstanding invitation to your Team the invitation will be expired.

Request Parameters

account_id OR email_address
The id or email address of the Account of the user to remove from your Team. The account id prevails if both are provided.

Response

Returns a Team object

Example requests / responses

POST https://[username]:[password]@api.hellosign.com/v3/team/remove_member

email_address=teammate@hellosign.com

CURL:

Request: 
curl -u 'me@hellosign.com:password' 'https://api.hellosign.com/v3/team/remove_member' \
	-F 'email_address=teammate@hellosign.com'

Response: 
{
	"team": {
		"name": "Team HelloSign",
		"accounts": [
			{
				"account_id": "5008b25c7f67153e57d5a357b1687968068fb465",
				"email_address": "me@hellosign.com",
				"role_code": "a"
			}
		],
		"invited_accounts": [
		]
	}
}
UnclaimedDraft A group of documents that a user can take ownership of by going to the claim URL

UnclaimedDraft

Response Object.
claim_url The URL to be used to claim this UnclaimedDraft.
URI Description
POST /unclaimed_draft/createCreates a new Draft that can be claimed using the claim URL. 

Description

Creates a new Draft that can be claimed using the claim URL. The first authenticated user to access the URL will claim the Draft and will be shown either the "Sign and send" or the "Request signature" page with the Draft loaded. Subsequent access to the claim URL will result in a 404. If the type is "send_document" then only the file parameter is required. If the type is "request_signature", then the identities of the signers and optionally the location of signing elements on the page are also required.

Request Parameters

file[]
The file(s) to send for signature.
type
The type of unclaimed draft to create. Use "send_document" to create a claimable file, and "request_signature" for a claimable signature request. If the type is "request_signature" then signers name and email_address are not optional.
subjectoptional
The subject in the email that will be sent to the signers.
messageoptional
The custom message in the email that will be sent to the signers.
signers[%i%][name]optional
The name of the signer. %i% is an integer that should be unique for each signer.
signers[%i%][email_address]optional
The email address of the signer. %i% is an integer that should be unique for each signer.
signers[%i%][order]optional
The order the signer is required to sign in. %i% is an integer that should be unique for each signer.
cc_email_addresses[]optional
The email addresses that should be CCed.
requester_email_addressoptional
The email address of the initiator of the SignatureRequest.
form_fields_per_documentoptional
The form fields that should appear on the document, expressed as a serialized JSON data structure which is a list of lists of the form fields. One list is required for each file[]. In the case of a file with no form fields, and empty list must be specified. Each field must identify which signer is supposed to fill out the form field, which type of form field it is, its location and size, and if it is required. The signer is identified by the offset (%i%) in the "signers" parameter. ReusableForm objects contain fields of the this type in "form_fields". If this parameter is not specified, a signature page will be affixed where all signers will be required to add their signature, signifying their agreement to all contained documents. 
[
				[
				{
					"name": "",
					"type": "text",
					"x": 112,
					"y": 328,
					"width": 100,
					"height": 16,
					"required": true,
					"signer": 2
				},
				{
					"name": "",
					"type": "signature",
					"x": 530,
					"y": 415,
					"width": 120,
					"height": 30,
					"required": true,
					"signer": 1
				}],
				[]
]

Response

Returns a UnclaimedDraft object

Example request / response

POST https://[username]:[password]@api.hellosign.com/v3/unclaimed_draft/create

file[0]=@Agreement.pdf
file[1]=@Appendix.doc

CURL:

Request: 
curl -u 'me@hellosign.com:password' 'https://api.hellosign.com/v3/unclaimed_draft/create' \
	-F 'file[0]=@Agreement.pdf' \
	-F 'file[1]=@Appendix.doc'

Response: 
{
	"unclaimed_draft": {
		"claim_url": "https:\/\/www.hellosign.com\/send\/resendDocs?root_snapshot_guids[]=7f967b7d06e154394eab693febedf61e8ebe49eb&snapshot_access_guids[]=fb848631&root_snapshot_guids[]=7aedaf31e12edf9f2672a0b2ddf028aca670e101&snapshot_access_guids[]=f398ef87"
	}
}
Events

Events will be POSTed to your Account.callback_url as they occur if an Account.callback_url has been set. If we cannot connect to your callback_url we will retry POSTing the event 7 times, with each retry interval being longer than the previous.

List of events

Event Description Attached Model
signature_request_viewed The SignatureRequest has been viewed. SignatureRequest
signature_request_signed A signer has completed all required fields on the SignatureRequest. SignatureRequest
signature_request_sent The SignatureRequest has been sent successfully. SignatureRequest
signature_request_all_signed All signers have completed all required fields for the SignatureRequest and the final PDF is ready to be downloaded using signature_request/final_copy. SignatureRequest
file_error We're unable to convert the file you provided. SignatureRequest

Example Event

Events posted to your callback url will be formatted as a JSON string contained in the json POST param. For example:

{
    "event": {
        "event_time": "1348177752", 
        "event_type": "signature_request_sent",
        "event_hash": "3a31324d1919d7cdc849ff407adf38fc01e01107d9400b028ff8c892469ca947"
    }, 
    "signature_request": {
        "cc_email_addresses": [], 
        "custom_fields": [], 
        "details_url": "https://www.hellosign.com/home/manage?guid=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."
    }
}

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.

Event Hash Verification

Each Event object in the callbacks contains an event_hash to help you verify that it's really coming from HelloSign. The event_hash is generated with the HMAC algorithm using your API Key as a key and SHA256 digest mode.

Your API Key can be found on the Settings page after you make your first API call.

Calculating event_hash

echo -n "${event_time}${event_type}" | openssl dgst -sha256 -hmac "${apikey}"

Calculating event_hash with PHP

hash_hmac('sha256', $event_time . $event_type, $apikey);

Calculating event_hash with Python

import hashlib, hmac 
hmac.new(apikey, (event_time + event_type), hashlib.sha256).hexdigest()

Calculating event_hash with Ruby

require 'openssl' 
OpenSSL::HMAC.hexdigest(OpenSSL::Digest::Digest.new('sha256'), apikey, (event_time + event_type))
Errors and Warnings

If an error or warning occurs, we'll return either an error or warning object in the JSON response.

List of errors

Error Description
bad_request The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.
unauthorized The email address and password combo you provided was invalid.
forbidden The requested action cannot be performed in the current context. Most of the time this happens when trying to access resources you don't have access to.
not_found The server has not found anything matching the Request-URI.
unknown An unknown error has occurred, please try again.
team_invite_failed The team invite request has failed. Most of the time this means the person you've invited already belongs to a team.
invalid_recipient The email address you provided for the recipient is not valid.
convert_failed We could not convert the document you provided.
signature_request_cancel_failed Could not cancel the Signature Request. Either you are not the requester or the Signature Request can no longer be cancelled.

Example Error

Only one error will be returned at a time. Here is an example of the JSON structure of the response (or error POSTed to your callback url):

{
    "error": {
        "error_msg": "Unauthorized user.", 
        "error_name": "unauthorized"
    }
}

List of warnings

Warning Description
unconfirmed The email address of the account making the Signature Request has not been confirmed. The Signature Request will be placed on hold until it is confirmed.

Example Warning

A response may contain one or more warnings. Here is an example of the JSON structure of the response:

{
    "warnings": [
        {
            "warning_msg": "This SignatureRequest will be placed on hold until the user confirms their email address.",
            "warning_name": "unconfirmed"
        }
    ]
}