API Reference
Objects and Methods
AccountContains information about an account and its settingsContains 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.
is_paid_hs Returns true if the user has a paid HelloSign account.
is_paid_hf Returns true f the user has a paid HelloFax account.
quotas An object detailing remaining monthly quotas.
templates_left API templates remaining.
api_signature_requests_left API signature requests remaining.
documents_left Signature requests remaining.
role_code The membership role for the team. a = Admin, 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
php
java
python
ruby
nodejs
POST /accountUpdates your Account's settings. 
Description

Updates the properties and settings of your Account.

Request Parameters
callback_url optional
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

curl
php
java
python
ruby
nodejs
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

curl
php
java
python
ruby
nodejs
POST /account/verifyVerify whether a HelloSign Account exists. 
Description

Verifies whether an HelloSign Account exists for the given email address.

NOTE This method is restricted to paid API users.

Request Parameters
email_address
Email address to run the verification for.
Response
Returns an Account object
Example requests / responses
POST https://[api key]:@api.hellosign.com/v3/account/verify

curl
php
java
python
ruby
nodejs
POST https://[api key]:@api.hellosign.com/v3/account/verify

curl
php
java
python
ruby
nodejs
Signature RequestContains information regarding documents that need to be signedContains information regarding documents that need to be signed
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. This should only be used by users with existing HelloSign accounts as they will be required to log in before signing.
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. Only 'text' and 'checkbox' are currently supported.
value A text string for text fields or true/false for checkbox fields
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
php
java
python
ruby
nodejs
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
page optional
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
php
java
python
ruby
nodejs
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_mode optional
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.
title optional
The title you want to assign to the SignatureRequest.
subject optional
The subject in the email that will be sent to the signers.
message optional
The custom message in the email that will be sent to the signers.
signing_redirect_url optional
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.
cc_email_addresses[] optional
The email addresses that should be CCed.
use_text_tags optional
[boolean] send with a value of "1" if you wish to enable Text Tags parsing in your document. If not set defaults to "0".
hide_text_tags optional
[boolean] send with a value of "0" if you wish to disable automatic Text Tag removal. If not set defaults to "1". When using Text Tags it is preferred that you set this to "0" and hide your tags with white text or something similar because the automatic removal system can cause unwanted clipping. See the Text Tags walkthrough for more details.
metadata[%key%] optional
Key-value data that should be attached to the signature request. This metadata is included in all API responses and events involving the signature request. For example, use the metadata field to store a signer's order number for look up when receiving events for the signature request.

Each request can include up to 10 metadata keys, with key names up to 40 characters long and values up to 500 characters long.
form_fields_per_document optional
The fields that should appear on the document, expressed as a 2-dimensional JSON array serialized to a string. The main array represents documents, with each containing an array of form fields. One document array is required for each file provided by the file[] parameter. In the case of a file with no fields, an empty list must be specified.

Each field must contain:
    1. api_id - (string) an identifier for the field that is unique across all documents in the request
    2. name - (string) a display name for the field
    3. type - one of the Type options
    4. x & y - (int) location coordinates of the field in pixels
    5. width & height - (int) size of the field in pixels
    6. required - (boolean) whether this field is required
    7. signer - (int) signer index identified by the offset %i% in the signers[%i%] parameter, indicating which signer should fill out the field

The following is an example of a form_fields_per_document for a 2-document request with a text field and signature field on the first document, prior to serialization to a string for the API request:

[
    [
        {
            "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
metadata[custom_id] = 1234
metadata[custom_text] = NDA #9
test_mode = 1

curl
php
java
python
ruby
nodejs
POST /signature_request/send_with_reusable_formDEPRECATED Creates 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. Deprecated, use POST /signature_request/send_with_template.

Request Parameters
test_mode optional
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.
title optional
The title you want to assign to the SignatureRequest.
subject optional
The subject in the email that will be sent to the signers.
message optional
The custom message in the email that will be sent to the signers.
signing_redirect_url optional
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.
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
php
java
python
ruby
nodejs
POST /signature_request/send_with_templateCreates and sends a new SignatureRequest based off of a Template. 
Description

Creates and sends a new SignatureRequest based off of the Template specified with the template_id parameter.

Request Parameters
test_mode optional
Whether this is a test, the signature request will not be legally binding if set to 1. Defaults to 0.
template_id or template_ids[%i%]
Use template_id to create a SignatureRequest from a single Template. Use template_ids[%i%] to create a SignatureRequest from multiple templates, where %i% is an integer indicating the order in which the template will be used. Only template_id or template_ids[%i%] can be used, not both.
title optional
The title you want to assign to the SignatureRequest.
subject optional
The subject in the email that will be sent to the signers.
message optional
The custom message in the email that will be sent to the signers.
signing_redirect_url optional
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.
ccs[%RoleName%][email_address] optional
The email address of the CC filling the role of RoleName. Required when a CC role exists for the Template.
custom_fields[%CustomFieldName%] optional
The value to fill in for custom field with the name of CustomFieldName. Required when a CustomField exists in the Template.
metadata[%key%] optional
Key-value data that should be attached to the signature request. This metadata is included in all API responses and events involving the signature request. For example, use the metadata field to store a signer's order number for look up when receiving events for the signature request.

Each request can include up to 10 metadata keys, with key names up to 40 characters long and values up to 500 characters long.
Response
Returns a SignatureRequest object
Example request / response
POST https://[api key]:@api.hellosign.com/v3/signature_request/send_with_template
template_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
php
java
python
ruby
nodejs
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
php
java
python
ruby
nodejs
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
php
java
python
ruby
nodejs
GET /signature_request/files/[:signature_request_id]Download the PDF copy of the current documents. 
Description

Download a copy of the current documents specified by the signature_request_id parameter.

Request Parameters
signature_request_id
The id of the SignatureRequest to retrieve.
file_type optional
set to either "pdf" for a single merged document or "zip" for a collection of individual documents.
Response
Returns a PDF or ZIP file
Example request / response
GET https://[api key]:@api.hellosign.com/v3/signature_request/files/[:signature_request_id]

curl
php
java
python
ruby
nodejs
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
php
java
python
ruby
nodejs
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_mode optional
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.
title optional
The title you want to assign to the SignatureRequest.
subject optional
The subject in the email that will be sent to the signers.
message optional
The custom message in the email that will be sent to the signers.
signing_redirect_url optional
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.
cc_email_addresses[] optional
The email addresses that should be CCed.
metadata[%key%] optional
Key-value data that should be attached to the signature request. This metadata is included in all API responses and events involving the signature request. For example, use the metadata field to store a signer's order number for look up when receiving events for the signature request.

Each request can include up to 10 metadata keys, with key names up to 40 characters long and values up to 500 characters long.
form_fields_per_document optional
The fields that should appear on the document, expressed as a 2-dimensional JSON array serialized to a string. The main array represents documents, with each containing an array of form fields. One document array is required for each file provided by the file[] parameter. In the case of a file with no fields, an empty list must be specified.

Each field must contain:
    1. api_id - (string) an identifier for the field that is unique across all documents in the request
    2. name - (string) a display name for the field
    3. type - one of the Type options
    4. x & y - (int) location coordinates of the field in pixels
    5. width & height - (int) size of the field in pixels
    6. required - (boolean) whether this field is required
    7. signer - (int) signer index identified by the offset %i% in the signers[%i%] parameter, indicating which signer should fill out the field

The following is an example of a form_fields_per_document for a 2-document request with a text field and signature field on the first document, prior to serialization to a string for the API request:

[
    [
        {
            "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
php
java
python
ruby
nodejs
POST /signature_request/create_embedded_with_reusable_formDEPRECATED Creates 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. Deprecated, use POST /signature_request/create_embedded_with_template.

Request Parameters
test_mode optional
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.
title optional
The title you want to assign to the SignatureRequest.
subject optional
The subject in the email that will be sent to the signers.
message optional
The custom message in the email that will be sent to the signers.
signing_redirect_url optional
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.
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
php
java
python
ruby
nodejs
POST /signature_request/create_embedded_with_templateCreates and sends a new SignatureRequest based off of a Template. 
Description

Creates a new SignatureRequest based on the given Template 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_mode optional
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.
template_id or template_ids[%i%]
Use template_id to create a SignatureRequest from a single Template. Use template_ids[%i%] to create a SignatureRequest from multiple templates, where %i% is an integer indicating the order in which the template will be used. Only template_id or template_ids[%i%] can be used, not both.
title optional
The title you want to assign to the SignatureRequest.
subject optional
The subject in the email that will be sent to the signers.
message optional
The custom message in the email that will be sent to the signers.
signing_redirect_url optional
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.
ccs[%RoleName%][email_address]
optional
The email address of the CC filling the role of RoleName. Required when a CC role exists for the Template.
custom_fields[%CustomFieldName%]
optional
The value to fill in for custom field with the name of CustomFieldName. Required when a CustomField exists in the Template.
metadata[%key%] optional
Key-value data that should be attached to the signature request. This metadata is included in all API responses and events involving the signature request. For example, use the metadata field to store a signer's order number for look up when receiving events for the signature request.

Each request can include up to 10 metadata keys, with key names up to 40 characters long and values up to 500 characters long.
Response
Returns a SignatureRequest object
Example request / response
POST https://[api key]:@api.hellosign.com/v3/signature_request/create_embedded_with_template
client_id = b6b8e7deaf8f0b95c029dca049356d4a2cf9710a
template_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
php
java
python
ruby
nodejs
Reusable FormDEPRECATED Use TemplateDEPRECATED Use Template
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. Only 'text' and 'checkbox' are currently supported.
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]DEPRECATED Gets a ReusableForm which includes a list of Accounts that can access it. 
Description

Returns the ReusableForm specified by the id parameter. Deprecated, use GET /template/[:template_id].

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
php
java
python
ruby
nodejs
GET /reusable_form/listDEPRECATED Lists your ReusableForms. 
Description

Returns a list the ReusableForms that are accessible by you. Deprecated, use GET /template/list.

Request Parameters
page optional
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
php
java
python
ruby
nodejs
POST /reusable_form/add_user/[:reusable_form_id]DEPRECATED 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. Deprecated, use POST /template/add_user/[:template_id].

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
php
java
python
ruby
nodejs
POST /reusable_form/remove_user/[:reusable_form_id]DEPRECATED Removes the specified Account's access to the specified ReusableForm. 
Description

Removes the specified Account's access to the specified ReusableForm. Deprecated, use POST /template/remove_user/[:template_id].

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
php
java
python
ruby
nodejs
TemplateContains information about the templates you and your team have createdContains information about the templates you and your team have created
Template Response Object.
template_id The id of the Template.
title The title of the Template. This will also be the default subject of the message sent to signers when using this Template 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 Template 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 Template.
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 Template.
name The name of the Role.
documents An array describing each document associated with this Template. 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. Only 'text' and 'checkbox' are currently supported.
named_form_fields DEPRECATED Use "form_fields" under the "documents" array instead.
accounts An array of the Accounts that can use this Template.
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 /template/[:template_id]Gets a Template which includes a list of Accounts that can access it. 
Description

Returns the Template specified by the id parameter.

Request Parameters
template_id
The id of the Template to retrieve.
Response
Returns a Template object
Example request / response
GET https://[api key]:@api.hellosign.com/v3/template/[:template_id]

curl
php
java
python
ruby
nodejs
GET /template/listLists your Templates. 
Description

Returns a list the Templates that are accessible by you.

Request Parameters
page optional
Which page number of the Template 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
templates
An array of Template objects.
Example request / response
GET https://[api key]:@api.hellosign.com/v3/template/list

curl
php
java
python
ruby
nodejs
POST /template/add_user/[:template_id]Gives the specified Account access to the specified Template. 
Description

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

Request Parameters
template_id
The id of the Template to give the Account access to.
account_id OR email_address
The id or email address of the Account to give access to the Template. The account id prevails if both are provided.
Response
Returns a Template object
Example request / response
POST https://[api key]:@api.hellosign.com/v3/template/add_user/[:template_id]
email_address = george@hellofax.com

curl
php
java
python
ruby
nodejs
POST /template/remove_user/[:template_id]Removes the specified Account's access to the specified Template. 
Description

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

Request Parameters
template_id
The id of the Template 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 Template. The account id prevails if both are provided.
Response
Returns a Template object
Example request / response
POST https://[api key]:@api.hellosign.com/v3/template/remove_user/[:template_id]
email_address = george@hellofax.com

curl
php
java
python
ruby
nodejs
TeamContains information about your team and its membersContains 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. a = Admin, 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
php
java
python
ruby
nodejs
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
php
java
python
ruby
nodejs
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
php
java
python
ruby
nodejs
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
php
java
python
ruby
nodejs
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 request / response
POST https://[api key]:@api.hellosign.com/v3/team/add_member
email_address = george@hellofax.com

curl
php
java
python
ruby
nodejs
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 request / response
POST https://[api key]:@api.hellosign.com/v3/team/remove_member
email_address = teammate@hellosign.com

curl
php
java
python
ruby
nodejs
Unclaimed DraftA group of documents that a user can take ownership of by going to the claim URLA 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.
signing_redirect_url The URL you want signers redirected to after they successfully sign.
expires_at When the link expires.
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.

Request Parameters
test_mode optional
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.
subject optional
The subject in the email that will be sent to the signers.
message optional
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_url optional
The URL you want signers redirected to after they successfully sign.
use_text_tags optional
[boolean] send with a value of "1" if you wish to enable Text Tags parsing in your document. If not set defaults to "0".
hide_text_tags optional
[boolean] send with a value of "0" if you wish to disable automatic Text Tag removal. If not set defaults to "1". When using Text Tags it is preferred that you set this to "0" and hide your tags with white text or something similar because the automatic removal system can cause unwanted clipping. See the Text Tags walkthrough for more details.
metadata[%key%] optional
Key-value data that should be attached to the signature request. This metadata is included in all API responses and events involving the signature request. For example, use the metadata field to store a signer's order number for look up when receiving events for the signature request.

Each request can include up to 10 metadata keys, with key names up to 40 characters long and values up to 500 characters long.
form_fields_per_document optional
The fields that should appear on the document, expressed as a 2-dimensional JSON array serialized to a string. The main array represents documents, with each containing an array of form fields. One document array is required for each file provided by the file[] parameter. In the case of a file with no fields, an empty list must be specified.

Each field must contain:
    1. api_id - (string) an identifier for the field that is unique across all documents in the request
    2. name - (string) a display name for the field
    3. type - one of the Type options
    4. x & y - (int) location coordinates of the field in pixels
    5. width & height - (int) size of the field in pixels
    6. required - (boolean) whether this field is required
    7. signer - (int) signer index identified by the offset %i% in the signers[%i%] parameter, indicating which signer should fill out the field

The following is an example of a form_fields_per_document for a 2-document request with a text field and signature field on the first document, prior to serialization to a string for the API request:

[
    [
        {
            "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 an 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
php
java
python
ruby
nodejs
POST /unclaimed_draft/create_embeddedCreates a new Draft that will be claimed for use in an embedded iFrame. 
Description

Creates a new Draft that can be claimed and used in an embedded iFrame. The first authenticated user to access the URL will claim the Draft and will be shown the "Request signature" page with the Draft loaded. Subsequent access to the claim URL will result in a 404. For this embedded endpoint the requester_email_address parameter is required. Note that embedded unclaimed drafts can only be accessed in embedded iFrames whereas normal drafts can be used and accessed on HelloSign.

Request Parameters
test_mode optional
Whether this is a test, the signature request created from this draft 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 draft. 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.
requester_email_address
The email address of the user that should be designated as the requester of this draft, if the draft type is "request_signature."
subject optional
The subject in the email that will be sent to the signers.
message optional
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_url optional
The URL you want signers redirected to after they successfully sign.
use_text_tags optional
[boolean] send with a value of "1" if you wish to enable Text Tags parsing in your document. If not set defaults to "0".
hide_text_tags optional
[boolean] send with a value of "0" if you wish to disable automatic Text Tag removal. If not set defaults to "1". When using Text Tags it is preferred that you set this to "0" and hide your tags with white text or something similar because the automatic removal system can cause unwanted clipping. See the Text Tags walkthrough for more details.
is_for_embedded_signing optional
[boolean] The request created from this draft will also be signable in embedded mode if set to "1". The default is "0".
metadata[%key%] optional
Key-value data that should be attached to the signature request. This metadata is included in all API responses and events involving the signature request. For example, use the metadata field to store a signer's order number for look up when receiving events for the signature request.

Each request can include up to 10 metadata keys, with key names up to 40 characters long and values up to 500 characters long.
form_fields_per_document optional
The fields that should appear on the document, expressed as a 2-dimensional JSON array serialized to a string. The main array represents documents, with each containing an array of form fields. One document array is required for each file provided by the file[] parameter. In the case of a file with no fields, an empty list must be specified.

Each field must contain:
    1. api_id - (string) an identifier for the field that is unique across all documents in the request
    2. name - (string) a display name for the field
    3. type - one of the Type options
    4. x & y - (int) location coordinates of the field in pixels
    5. width & height - (int) size of the field in pixels
    6. required - (boolean) whether this field is required
    7. signer - (int) signer index identified by the offset %i% in the signers[%i%] parameter, indicating which signer should fill out the field

The following is an example of a form_fields_per_document for a 2-document request with a text field and signature field on the first document, prior to serialization to a string for the API request:

[
    [
        {
            "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 an UnclaimedDraft object
Example request / response
POST https://[api key]:@api.hellosign.com/v3/unclaimed_draft/create_embedded
client_id = b6b8e7deaf8f0b95c029dca049356d4a2cf9710a
requester_email_address = jack@hellosign.com
file[0] = @Agreement.pdf
file[1] = @Appendix.doc
test_mode = 1

curl
php
java
python
ruby
nodejs
EmbeddedAn object that contains necessary information to set up embedded signingAn object that contains necessary information to set up embedded signing
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]
EventAn event sent to a callback urlAn event sent to a callback url
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 and in the Constants section where the list of possible events can be found.
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 event_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 defined.

Account callback

A callback url can be set up at the account level (Account.callback_url), in this case all events from all signature requests that you make, whether it is manually or via the API, will be reported to the given url.

App callbacks

App callbacks are more restrictive than account callbacks and are defined at the app level. In this case, only events from signature requests that have been created by the app get reported to the associated callback url. Event messages include a client_id field to indicate which app the event is being reported for (this is handy when several apps share the same callback url).

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 initials
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.
signature_request_invalid An error was detected with the signature request parameters during processing.
template_error An error occurred while creating your template.
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.
custom_field_value_too_long The value provided for a custom field is too long. The custom field will extend beyond the limits of its container and may not display the way you intended.
custom_field_values_too_long A summary of all values for custom fields that are too long
Event names

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

Event Type Description Attached Model Reported to
signature_request_viewed The SignatureRequest has been viewed. SignatureRequest Account & app callbacks
signature_request_signed A signer has completed all required fields on the SignatureRequest. SignatureRequest Account & app callbacks
signature_request_sent The SignatureRequest has been sent successfully. SignatureRequest Account & app callbacks
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/files . SignatureRequest Account & app callbacks
file_error We're unable to convert the file you provided. SignatureRequest Account & app callbacks
unknown_error An unknown error occurred during while processing a signature request. SignatureRequest Account & app callbacks
signature_request_invalid An error occurred while processing the signature request data on our back-end.

For example: Invalid text tags
SignatureRequest Account & app callbacks
account_confirmed An account created via one of your apps has been confirmed. Account App callback only
template_created The Template has been created. Template Account & app callbacks
template_error There was an error while creating your template. Template Account & app callbacks

For more info on handling callback events, see the events and callbacks walkthrough.

Signature status codes

Callback events come along with a SignatureRequest object, under which you can find the list of associated Signatures. Each of these Signature object has a status_code field that describes its current state. The table below lists all possible codes.

Status Description Attached Model
success Success SignatureRequest
on_hold On hold. This could be because the sending account needs to confirm its email address, or because of insufficient funds. SignatureRequest
signed Signed SignatureRequest
awaiting_signature Awaiting signature SignatureRequest
error_unknown Unknown error SignatureRequest
error_file File could not converted SignatureRequest
error_text_tag File contained invalid text tags SignatureRequest