API Documentation

Objects and Methods

Account Contains information about an account and its settings [+] Expand

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.
is_paid_hs If the user has a paid HelloSign license will return true.
is_paid_hf If the user has a paid HelloFax license will return true.
quotas An object detailing remaining monthly quotas.
templates_left API templates remaining.
api_signature_requests_left API signature requests remaining.
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://[api key]:@api.hellosign.com/v3/account

CURL:

Request:
curl 'https://api.hellosign.com/v3/account' \
	-u '141d6455477a9b088112f7cb1389bad6792d587514b81c9c390770aca043eaa8:'

Response:
{
    "account": {
        "account_id": "5008b25c7f67153e57d5a357b1687968068fb465",
        "email_address": "me@hellosign.com",
        "is_paid_hs" : true,
        "is_paid_hf" : false,
        "quotas" : {
        	"templates_left": null,
        	"api_signature_requests_left": 1250
        },
        "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://[api key]:@api.hellosign.com/v3/account

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

CURL:

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

Response:
{
    "account": {
        "account_id": "5008b25c7f67153e57d5a357b1687968068fb465",
        "email_address": "me@hellosign.com",
        "is_paid_hs" : true,
        "is_paid_hf" : false,
        "quotas" : {
        	"templates_left": null,
        	"api_signature_requests_left": 1250
        },
        "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://[api key]:@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",
		"is_paid_hs" : false,
		"is_paid_hf" : false,
		"quotas" : {
			"templates_left": "1",
			"api_signature_requests_left": 0
		},
		"callback_url": null,
		"role_code": null
	}
}
SignatureRequest Contains information regarding documents that need to be signed [+] Expand

SignatureRequest

Response Object.
test_mode Whether this is a test signature request. Test requests have no legal value. Defaults to 0.
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 occurred (either during the creation of the SignatureRequest or during one of the signings).
final_copy_uri (Deprecated) The relative URI where the PDF copy of the finalized documents can be downloaded. Only present when is_complete = true. This will be removed at some point; use the files_url instead.
files_url The URL where a copy of the request's documents can be downloaded.
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.
signing_redirect_url The URL you want the signer redirected to after they successfully sign.
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' and 'checkmark' are the only valid values.
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.
api_id The unique ID for this field.
signature_id The ID of the signature to which this response is linked.
name The name of the form field.
value The value of the form field.
type The type of this form field. See field types
signatures An array of signature obects, 1 for each signer.
signature_id Signature identifier.
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.
has_pin Boolean to indicate whether this signature requires a PIN to access.
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://[api key]:@api.hellosign.com/v3/signature_request/[:signature_request_id]

CURL:

Request:
curl 'https://api.hellosign.com/v3/signature_request/fa5c8a0b0f492d768749333ad6fcc214c111e967' \
	-u '141d6455477a9b088112f7cb1389bad6792d587514b81c9c390770aca043eaa8:'

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": [
			{
				"api_id": "80c678_1",
				"name": "Needs Express Shipping",
				"value": true,
				"type": "checkbox"
			},
			{
				"api_id": "80c678_2",
				"name": "Shipping Address",
				"value": "1212 Park Avenuee",
				"type": "text"
			},
			{
				"api_id": "80c678_3",
				"name": "DateSigned",
				"value": "09\/01\/2012",
				"type": "text"
			}
		],
		"signing_url": null,
		"signing_redirect_url": null,
		"details_url": "https:\/\/www.hellosign.com\/home\/manage?locate=fa5c8a0b0f492d768749333ad6fcc214c111e967",
		"requester_email_address": "me@hellosign.com",
		"signatures": [
			{
				"signature_id": "78caf2a1d01cd39cea2bc1cbb340dac3",
				"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,
				"has_pin" : false
			}
		],
		"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://[api key]:@api.hellosign.com/v3/signature_request/list

CURL:

Request:
curl 'https://api.hellosign.com/v3/signature_request/list?page=1' \
	-u '141d6455477a9b088112f7cb1389bad6792d587514b81c9c390770aca043eaa8:'

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",
			"signing_redirect_url": null,
			"details_url": "https:\/\/www.hellosign.com\/home\/manage?locate=d10338cad145e1cb68afc828348c3fe3bd534bb1",
			"requester_email_address": "me@hellosign.com",
			"signatures": [
				{
					"signature_id": "78caf2a1d01cd39cea2bc1cbb340dac3",
					"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,
					"has_pin" : false
				},
				{
					"signature_id": "616629ed37f8588d28600be17ab5d6b7",
					"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,
					"has_pin" : false
				}
			],
			"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": [
				{
					"api_id": "uniqueIdHere_1",
					"name": "Needs Express Shipping",
					"value": true,
					"type": "checkbox"
				},
				{
					"api_id": "uniqueIdHere_2",
					"name": "Shipping Address",
					"value": "1212 Park Avenuee",
					"type": "text"
				},
				{
					"api_id": "uniqueIdHere_3",
					"name": "DateSigned",
					"value": "09\/01\/2012",
					"type": "date_signed"
				}
			],
			"signing_url": null,
			"signing_redirect_url": null,
			"details_url": "https:\/\/www.hellosign.com\/home\/manage?locate=fa5c8a0b0f492d768749333ad6fcc214c111e967",
			"requester_email_address": "me@hellosign.com",
			"signatures": [
				{
					"signature_id": "5687fb7bd5aaacb1689728762b600c74",
					"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

test_modeoptional
Whether this is a test, the signature request will not be legally binding if set to 1. Defaults to 0.
file[] or file_url[]
Use file[] to indicate the uploaded file(s) to send for signature. Use file_url[] to have HelloSign download the file(s) to send for signature. Currently we only support use of either the file[] parameter or file_url[] parameter, not both.
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.
signing_redirect_urloptional
The URL you want the signer redirected to after they successfully sign.
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.
signers[%i%][pin]optional
The 4- to 12-character access code that will secure this signer's signature page. You must have a business plan to use this feature.
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". The type is one of the Type options.
[
				[
				{
					"api_id": "uniqueIdHere_1",
					"name": "",
					"type": "text",
					"x": 112,
					"y": 328,
					"width": 100,
					"height": 16,
					"required": true,
					"signer": 2
				},
				{
					"api_id": "uniqueIdHere_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://[api key]:@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[0]=@NDA.pdf
file[1]=@AppendixA.pdf

CURL:

Request:
curl 'https://api.hellosign.com/v3/signature_request/send' \
	-u '141d6455477a9b088112f7cb1389bad6792d587514b81c9c390770aca043eaa8:' \
	-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[0]=@NDA.pdf' \
	-F 'file[1]=@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",
		"signing_redirect_url": null,
		"details_url": "https:\/\/www.hellosign.com\/home\/manage?locate=a9f4825edef25f47e7b4c14ce8100d81d1693160",
		"requester_email_address": "me@hellosign.com",
		"signatures": [
			{
				"signature_id": "78caf2a1d01cd39cea2bc1cbb340dac3",
				"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,
				"has_pin": false
			},
			{
				"signature_id": "616629ed37f8588d28600be17ab5d6b7",
				"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,
				"has_pin": false
			}
		],
		"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

test_modeoptional
Whether this is a test, the signature request will not be legally binding if set to 1. Defaults to 0.
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.
signing_redirect_urloptional
The URL you want the signer redirected to after they successfully sign.
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.
signers[%RoleName%][pin]optional
The 4- to 12-character access code that will secure this signer's signature page. You must have a business plan to use this feature.
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://[api key]:@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 'https://api.hellosign.com/v3/signature_request/send_with_reusable_form' \
	-u '141d6455477a9b088112f7cb1389bad6792d587514b81c9c390770aca043eaa8:' \
	-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",
		"signing_redirect_url": null,
		"details_url": "https:\/\/www.hellosign.com\/home\/manage?locate=17d163069282df5eb63857d31ff4a3bffa9e46c0",
		"requester_email_address": "me@hellosign.com",
		"signatures": [
			{
				"signature_id": "10ab1cd037d9b6cba7975d61ff428c8d",
				"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,
				"has_pin": false
			}
		],
		"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 1 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://[api key]:@api.hellosign.com/v3/signature_request/remind/[:signature_request_id]

email_address=john@example.com

CURL:

Request:
curl 'https://api.hellosign.com/v3/signature_request/remind/2f9781e1a8e2045224d808c153c2e1d3df6f8f2f' \
	-u '141d6455477a9b088112f7cb1389bad6792d587514b81c9c390770aca043eaa8:' \
	-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",
		"signing_redirect_url": null,
		"details_url": "https:\/\/www.hellosign.com\/home\/manage?locate=2f9781e1a8e2045224d808c153c2e1d3df6f8f2f",
		"requester_email_address": "me@hellosign.com",
		"signatures": [
			{
				"signature_id": "5687fb7bd5aaacb1689728762b600c74",
				"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,
				"has_pin" : false
			}
		],
		"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://[api key]:@api.hellosign.com/v3/signature_request/cancel/[:signature_request_id]

CURL:

Request:
curl 'https://api.hellosign.com/v3/signature_request/cancel/2f9781e1a8e2045224d808c153c2e1d3df6f8f2f' \
	-u '141d6455477a9b088112f7cb1389bad6792d587514b81c9c390770aca043eaa8:'\
	-X POST

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

Description

Download the PDF copy of the current 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://[api key]:@api.hellosign.com/v3/signature_request/files/[:signature_request_id]

CURL:

Request:
curl 'https://api.hellosign.com/v3/signature_request/files/fa5c8a0b0f492d768749333ad6fcc214c111e967' \
	-u '141d6455477a9b088112f7cb1389bad6792d587514b81c9c390770aca043eaa8:' -o files.pdf

Response:
N/A (File will be created)
GET /signature_request/final_copy/[:signature_request_id]DEPRECATED Download the PDF copy of the finalized documents. 

Description

Download the PDF copy of the finalized documents specified by the signature_request_id parameter. Deprecated, use GET /signature_request/files/[:signature_request_id].

Request Parameters

signature_request_id
The id of the SignatureRequest to retrieve.

Response

Returns a PDF

Example request / response

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

CURL:

Request:
curl 'https://api.hellosign.com/v3/signature_request/final_copy/75cdf7dc8b323d43b347e4a3614d1f822bd09491' \
	-u '141d6455477a9b088112f7cb1389bad6792d587514b81c9c390770aca043eaa8:' -o final-copy.pdf

Response:
N/A (File will be created)
POST /signature_request/create_embeddedCreates and sends a new SignatureRequest with the submitted documents. 

Description

Creates a new SignatureRequest with the submitted documents to be signed in an embedded iFrame . 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. Note that embedded signature requests can only be signed in embedded iFrames whereas normal signature requests can only be signed on HelloSign.

Request Parameters

test_modeoptional
Whether this is a test, the signature request will not be legally binding if set to 1. Defaults to 0.
client_id
Client id of the app you're using to create this embedded signature request. Visit our embedded page to learn more about this parameter.
file[] or file_url[]
Use file[] to indicate the uploaded file(s) to send for signature. Use file_url[] to have HelloSign download the file(s) to send for signature. Currently we only support use of either the file[] parameter or file_url[] parameter, not both.
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.
signing_redirect_urloptional
The URL you want the signer redirected to after they successfully sign.
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.
signers[%i%][pin]optional
The 4- to 12-character access code that will secure this signer's signature page. You must have a business plan to use this feature.
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". The type is one of the Type options.
[
                [
                {
                    "api_id": "uniqueIdHere_1",
                    "name": "",
                    "type": "text",
                    "x": 112,
                    "y": 328,
                    "width": 100,
                    "height": 16,
                    "required": true,
                    "signer": 2
                },
                {
                    "api_id": "uniqueIdHere_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://[api key]:@api.hellosign.com/v3/signature_request/create_embedded

client_id=b6b8e7deaf8f0b95c029dca049356d4a2cf9710a
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[0]=@NDA.pdf
file[1]=@AppendixA.pdf

CURL:

Request:
curl 'https://api.hellosign.com/v3/signature_request/create_embedded' \
	-u '141d6455477a9b088112f7cb1389bad6792d587514b81c9c390770aca043eaa8:' \
	-F 'client_id=b6b8e7deaf8f0b95c029dca049356d4a2cf9710a' \
	-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[0]=@NDA.pdf' \
	-F 'file[1]=@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",
        "signing_redirect_url": null,
        "details_url": "https:\/\/www.hellosign.com\/home\/manage?locate=a9f4825edef25f47e7b4c14ce8100d81d1693160",
        "requester_email_address": "me@hellosign.com",
        "signatures": [
            {
                "signature_id": "78caf2a1d01cd39cea2bc1cbb340dac3",
                "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,
                "has_pin" : false
            },
            {
                "signature_id": "616629ed37f8588d28600be17ab5d6b7",
                "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,
                "has_pin" : false
            }
        ],
        "cc_email_addresses": [
            "lawyer@hellosign.com",
            "lawyer@example.com"
        ]
    }
}
POST /signature_request/create_embedded_with_reusable_formCreates and sends a new SignatureRequest based off of a ReusableForm. 

Description

Creates a new SignatureRequest based on the given ReusableForm to be signed in an embedded iFrame. Note that embedded signature requests can only be signed in embedded iFrames whereas normal signature requests can only be signed on HelloSign.

Request Parameters

test_modeoptional
Whether this is a test, the signature request will not be legally binding if set to 1. Defaults to 0.
client_id
Client id of the app you're using to create this embedded signature request. Visit our embedded page to learn more about this parameter.
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.
signing_redirect_urloptional
The URL you want the signer redirected to after they successfully sign.
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.
signers[%RoleName%][pin]optional
The 4- to 12-character access code that will secure this signer's signature page. You must have a business plan to use this feature.
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://[api key]:@api.hellosign.com/v3/signature_request/create_embedded_with_reusable_form

client_id=b6b8e7deaf8f0b95c029dca049356d4a2cf9710a
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 'https://api.hellosign.com/v3/signature_request/create_embedded_with_reusable_form' \
	-u '141d6455477a9b088112f7cb1389bad6792d587514b81c9c390770aca043eaa8:' \
	-F 'client_id=b6b8e7deaf8f0b95c029dca049356d4a2cf9710a' \
	-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",
        "signing_redirect_url": null,
        "details_url": "https:\/\/www.hellosign.com\/home\/manage?locate=17d163069282df5eb63857d31ff4a3bffa9e46c0",
        "requester_email_address": "me@hellosign.com",
        "signatures": [
            {
                "signature_id": "78caf2a1d01cd39cea2bc1cbb340dac3",
                "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,
                "has_pin" : false
            }
        ],
        "cc_email_addresses": [
            "accounting@hellosign.com"
        ]
    }
}
ReusableForm Contains information about the templates you and your team have created [+] Expand

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.
name Name of the associated file
index Document ordering, the lowest index is diplayed first and the highest last.
form_fields An array of Form Field objects containing the name and type of each named textbox and checkmark field.
api_id A unique id for the form field.
name The name of the form field.
type The type of this form field. See field types
x The horizontal offset in pixels for this form field.
y The vertical offset in pixels for this form field.
width The width in pixels of this form field.
height The height in pixels 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.
named_form_fields DEPRECATED Use "form_fields" under the "documents" array instead.
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.
is_creator True if you are the owner of this template, false if it's been shared with you by a team member.
can_edit Indicates whether edit rights have been granted to you by the owner (always true if that's you).
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://[api key]:@api.hellosign.com/v3/reusable_form/[:reusable_form_id]

CURL:

Request:
curl 'https://api.hellosign.com/v3/reusable_form/f57db65d3f933b5316d398057a36176831451a35' \
	-u '141d6455477a9b088112f7cb1389bad6792d587514b81c9c390770aca043eaa8:'

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": [
					{
						"api_id": "0ec7a7_1",
						"name": "VendorName",
						"type": "text",
						"x": 160,
						"y": 141,
						"width": 80,
						"height": 30,
						"required": true
					},
					{
						"api_id": "0ec7a7_2",
						"name": "VendorTitle",
						"type": "text",
						"x": 160,
						"y": 181,
						"width": 80,
						"height": 30,
						"required": true
					},
					{
						"api_id": "0ec7a7_3",
						"name": "ManagerName",
						"type": "text",
						"x": 160,
						"y": 221,
						"width": 80,
						"height": 30,
						"required": true
					},
					{
						"api_id": "0ec7a7_4",
						"name": "ManagerTitle",
						"type": "text",
						"x": 160,
						"y": 251,
						"width": 80,
						"height": 30,
						"required": true
					},
					{
						"api_id": "0ec7a7_5",
						"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://[api key]:@api.hellosign.com/v3/reusable_form/list

CURL:

Request:
curl 'https://api.hellosign.com/v3/reusable_form/list?page=1' \
	-u '141d6455477a9b088112f7cb1389bad6792d587514b81c9c390770aca043eaa8:'

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": [
					{
						"api_id": "0ec7a7_1",
						"name": "VendorName",
						"type": "text",
						"x": 160,
						"y": 141,
						"width": 80,
						"height": 30,
						"required": true
					},
					{
						"api_id": "0ec7a7_2",
						"name": "VendorTitle",
						"type": "text",
						"x": 160,
						"y": 181,
						"width": 80,
						"height": 30,
						"required": true
					},
					{
						"api_id": "0ec7a7_3",
						"name": "ManagerName",
						"type": "text",
						"x": 160,
						"y": 221,
						"width": 80,
						"height": 30,
						"required": true
					},
					{
						"api_id": "0ec7a7_4",
						"name": "ManagerTitle",
						"type": "text",
						"x": 160,
						"y": 251,
						"width": 80,
						"height": 30,
						"required": true
					},
					{
						"api_id": "0ec7a7_5",
						"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://[api key]:@api.hellosign.com/v3/reusable_form/add_user/[:reusable_form_id]

email_address=george@hellofax.com

CURL:

Request:
curl 'https://api.hellosign.com/v3/reusable_form/add_user/21f920ec2b7f4b6bb64d3ed79f26303843046536' \
	-u '141d6455477a9b088112f7cb1389bad6792d587514b81c9c390770aca043eaa8:' \
	-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": [
					{
						"api_id": "0ec7a7_1",
						"name": "VendorName",
						"type": "text",
						"x": 160,
						"y": 141,
						"width": 80,
						"height": 30,
						"required": true
					},
					{
						"api_id": "0ec7a7_2",
						"name": "VendorTitle",
						"type": "text",
						"x": 160,
						"y": 181,
						"width": 80,
						"height": 30,
						"required": true
					},
					{
						"api_id": "0ec7a7_3",
						"name": "ManagerName",
						"type": "text",
						"x": 160,
						"y": 221,
						"width": 80,
						"height": 30,
						"required": true
					},
					{
						"api_id": "0ec7a7_4",
						"name": "ManagerTitle",
						"type": "text",
						"x": 160,
						"y": 251,
						"width": 80,
						"height": 30,
						"required": true
					},
					{
						"api_id": "0ec7a7_5",
						"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://[api key]:@api.hellosign.com/v3/reusable_form/remove_user/[:reusable_form_id]

email_address=george@hellofax.com

CURL:

Request:
curl 'https://api.hellosign.com/v3/reusable_form/remove_user/21f920ec2b7f4b6bb64d3ed79f26303843046536' \
	-u '141d6455477a9b088112f7cb1389bad6792d587514b81c9c390770aca043eaa8:' \
	-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": [
					{
						"api_id": "0ec7a7_1",
						"name": "VendorName",
						"type": "text",
						"x": 160,
						"y": 141,
						"width": 80,
						"height": 30,
						"required": true
					},
					{
						"api_id": "0ec7a7_2",
						"name": "VendorTitle",
						"type": "text",
						"x": 160,
						"y": 181,
						"width": 80,
						"height": 30,
						"required": true
					},
					{
						"api_id": "0ec7a7_3",
						"name": "ManagerName",
						"type": "text",
						"x": 160,
						"y": 221,
						"width": 80,
						"height": 30,
						"required": true
					},
					{
						"api_id": "0ec7a7_4",
						"name": "ManagerTitle",
						"type": "text",
						"x": 160,
						"y": 251,
						"width": 80,
						"height": 30,
						"required": true
					},
					{
						"api_id": "0ec7a7_5",
						"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 [+] Expand

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://[api key]:@api.hellosign.com/v3/team

CURL:

Request:
curl 'https://api.hellosign.com/v3/team' \
	-u '141d6455477a9b088112f7cb1389bad6792d587514b81c9c390770aca043eaa8:'

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://[api key]:@api.hellosign.com/v3/team/create

name=Team America World Police

CURL:

Request:
curl 'https://api.hellosign.com/v3/team/create' \
	-u '141d6455477a9b088112f7cb1389bad6792d587514b81c9c390770aca043eaa8:' \
	-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.

Request Parameters

name
The name of your Team

Response

Returns a Team object

Example request / response

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

name=New Team Name

CURL:

Request:
curl 'https://api.hellosign.com/v3/team' \
	-u '141d6455477a9b088112f7cb1389bad6792d587514b81c9c390770aca043eaa8:' \
	-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://[api key]:@api.hellosign.com/v3/team/destroy

CURL:

Request:
curl 'https://api.hellosign.com/v3/team/destroy' \
	-u '141d6455477a9b088112f7cb1389bad6792d587514b81c9c390770aca043eaa8:'\
	-X POST

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://[api key]:@api.hellosign.com/v3/team/add_member

email_address=george@hellofax.com

CURL:

Request:
curl 'https://api.hellosign.com/v3/team/add_member' \
	-u '141d6455477a9b088112f7cb1389bad6792d587514b81c9c390770aca043eaa8:' \
	-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://[api key]:@api.hellosign.com/v3/team/remove_member

email_address=teammate@hellosign.com

CURL:

Request:
curl 'https://api.hellosign.com/v3/team/remove_member' \
	-u '141d6455477a9b088112f7cb1389bad6792d587514b81c9c390770aca043eaa8:' \
	-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 [+] Expand

UnclaimedDraft

Response Object.
claim_url The URL to be used to claim this UnclaimedDraft.
signing_redirect_url The URL you want signers redirected to after they successfully sign.
test_mode Whether this is a test draft. Signature requests made from test drafts have no legal value. Defaults to 0.
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

test_modeoptional
Whether this is a test, the signature request created from this draft will not be legally binding if set to 1. Defaults to 0.
file[] or file_url[]
Use file[] to indicate the uploaded file(s) to send for signature. Use file_url[] to have HelloSign download the file(s) to send for signature. Currently we only support use of either the file[] parameter or file_url[] parameter, not both.
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.
signing_redirect_urloptional
The URL you want signers redirected to after they successfully sign.
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. The type is one of the Type options.
[
				[
				{
					"api_id": "uniqueIdHere_1",
					"name": "",
					"type": "text",
					"x": 112,
					"y": 328,
					"width": 100,
					"height": 16,
					"required": true,
					"signer": 2
				},
				{
					"api_id": "uniqueIdHere_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://[api key]:@api.hellosign.com/v3/unclaimed_draft/create

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

CURL:

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

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",
		"signing_redirect_url" : null,
		"test_mode": 1
	}
}
Embedded An object that contains necessary information to set up embedded signing. [+] Expand
HelloSign allows you to embed the signing page on your site in an iFrame, without the need for the end-user to create a HelloSign account. Take a look at our embedded signing walkthrough for more information about this.

Embedded

Response Object.
sign_url URL of the signature page to display in the embedded iFrame.
expires_at When the link expires.
URI Description
GET /embedded/sign_url/[:signature_id]Retrieves a embedded signing object. 

Description

Retrieves an embedded object containing a signature url that can be opened in an iFrame.

Request Parameters

signature_id
The id of the signature to get a signature url for

Response

Returns an Embedded object

Example request / response

GET https://[api key]:@api.hellosign.com/v3/embedded/sign_url/[:signature_id]

CURL:

Request:
curl 'https://api.hellosign.com/v3/embedded/sign_url/50e3542f738adfa7ddd4cbd4c00d2a8ab6e4194b' \
	-u '141d6455477a9b088112f7cb1389bad6792d587514b81c9c390770aca043eaa8:'

Response:
{
    "embedded": {
        "sign_url": "https://api.hellosign.com/editor/embeddedSign?signature_id=50e3542f738adfa7ddd4cbd4c00d2a8ab6e4194b&token=b6b8e7deaf8f0b95c029dca049356d4a2cf9710a",
        "expires_at": 1398268186
    }
}
Event An event sent to a callback url. [+] Expand
HelloSign keeps you updated by sending events to the callback urls you specified. More details about events and callbacks can be found in the events/callbacks walkthrough.

Event

account_guid DEPRECATED Use reported_for_account_id instead
client_id DEPRECATED Use reported_for_app_id instead
event A complete description of this event
event_time When the event was created (UNIX timestamp)
event_type Type of event being reported, see event types for more details
event_hash Unique hash of this event, see hash verification for more details
event_metadata A map of values containing data related to this event.
related_signature_id Signature associated with this event. Only set when even_type is signature_request_signed.
reported_for_account_id Id of the account this event is reported for.
reported_for_app_id Client id of the app this event is reported for.
signature_request Related signature request. Only present when the event is signature-related.

Callbacks

Events will be POSTed to your callback urls. There are two kinds of callbacks that can be setup.

The first one is at the account level (Account.callback_url) and is where messages will be sent whenever an event involving your account occurs. You can set this callback by using the account API call
The other callback URL is defined at the app level, it will get notified whenever the app is involved. The event message will include a client_id field to identify the app.

NOTE: If you happen to use the same callback across accounts or apps, it is possible that you will receive duplicate events. If you've already processed an event, you may want to ignore it and return a successful response. Use the event hash to identify unique events.

Take a look at our events and callbacks guide to learn more on this topic.

Warnings and Errors

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

Example Error


A response may only contain one error at most. Check out the list of error names to learn more about the possible values of error_name and their meaning. 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"
    }
}

Example Warning


A response may contain one or more warnings. Check out the list of warning names to learn more about the possible values of warning_name and their meaning. 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"
        }
    ]
}

Constants

Field types


These are the options you can specify for the "type" field.

Type Description
text A text input field
checkbox A yes/no checkbox
date_signed A date
initials An input field for intials
signature A signature input field

Error names


List and details of possible errors that can be returned.

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 credentials you have supplied are invalid.
payment_required Your account must be credited before the requested action is possible.
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.
conflict Your request was well-formed but it cannot be completed to a conflict of some kind.
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.
maintenance The request could not be completed because we are currently performing site maintenance.
deleted The request was cancelled or deleted.
unknown An unknown error has occurred, please try again.
method_not_supported The HTTP method used is not supported for the API endpoint being called.

Warning names


List and details of possible warnings that can be returned.

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.

Event names


Here is the list of possible events that can be sent to your callbacks.

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