API Reference | HelloSign API Documentation
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_locked Returns true if the user has been locked out of their account by a team admin.
is_paid_hs Returns true if the user has a paid HelloSign account.
is_paid_hf Returns true if 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.
ACTION URI - Description
Get Account
GET /account
Returns 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
Update Account
POST /account
Updates 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
Create Account
POST /account/create
Signs up for a new HelloSign Account.
Description

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

Request Parameters
email_address
The email address to create a new Account for.
Response
Returns an Account object
Example request / response
POST https://[api key]:@api.hellosign.com/v3/account/create
Verify Account
POST /account/verify
Verify 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

  For existing account: {'account': {'email_address': 'EMAIL ADDRESS'}}
  For non-existing account: { }
Example requests / responses
POST https://[api key]:@api.hellosign.com/v3/account/verify
email_address = some_user@hellosign.com
POST https://[api key]:@api.hellosign.com/v3/account/verify
email_address = not_a_user@hellosign.com
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.
original_title Default Label for account.
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.
metadata The metadata attached to the signature request.
created_at Time the signature request was created.
is_complete Whether or not the SignatureRequest has been fully executed by all signers.
is_declined Whether or not the SignatureRequest has been declined by a signer.
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
required A boolean value denoting if this field is required.
api_id The unique ID for this field.
editor The name of the Role that is able to edit this field.
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.
required A boolean value denoting if this field is required.
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.
signer_role The role 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, declined
decline_reason The reason provided by the signer for declining the request.
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.
reassigned_by Email address of original signer who reassigned to this signer.
reassignment_reason Reason provided by original signer who reassigned to this signer.
error Error message pertaining to this signer, or null.
ACTION URI - Description
Get Signature Request
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]
List Signature Requests
GET /signature_request/list
Lists 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.

Take a look at our search guide to learn more about querying signature requests.

Request Parameters
account_id optional
Which account to return SignatureRequests for. Must be a team member. Use "all" to indicate all team members. Defaults to your account.
page optional
Which page number of the SignatureRequest List to return. Defaults to 1.
page_size optional
Number of objects to be returned per page. Must be between 1 and 100. Default is 20.
query optional
String that includes search terms and/or fields to be used to filter the SignatureRequest objects.
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
Send Signature Request
POST /signature_request/send
Creates 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.
signers[%i%][sms_phone_number] optional
An E.164 formatted phone number that will receive a code via SMS to access this signer's signature page.
Note: Not available in test mode and requires a Platinum plan or higher.
signers[%i%][group]
To send to a signer group, specify the name of the group and assign the signers that are part of it under the same index. Any of the signers is eligible to sign for the entire group.
The following is an example of a signature request sent to a signer group of 3 signers: 
signers[0][group]=Authorized signatory
signers[0][0][name]=Jack
signers[0][0][email_address]=jack@example.com
signers[0][1][name]=Jill
signers[0][1][email_address]=jill@example.com
signers[0][2][name]=John
signers[0][2][email_address]=john@example.com
attachments[%i%][name] optional
The name of attachment.
attachments[%i%][instructions] optional
The instructions for uploading the attachment.
attachments[%i%][signer_index] optional
The signer's unique number, see signers[%i%][name] for more details.
attachments[%i%][required] optional
Determines if the attachment must be uploaded.
custom_fields optional
A JSON array defining values and options for custom fields. Required when defining pre-set values in form_fields_per_document or Text Tags.
  • name: the name, or "Field Label," of the custom field (the field's API ID can be used here as well)
  • value: the value of the custom field
  • editor: the RoleName allowed to edit the custom field (optional, but required if 'required' is defined)
    Note: Editable custom_fields are only supported for single signer requests or the first signer of ordered signature requests. If more than one signer is assigned to the unordered signature request, any editor value is ignored and the field will not be editable.
  • required: a boolean describing if this field is required (default: false)
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. Defaults to 0.
hide_text_tags optional
[boolean] Send with a value of 1 if you wish to enable automatic Text Tag removal. Defaults to 0. 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 1000 characters long.
client_id optional
The client ID of the ApiApp you want to associate with this request.
allow_decline optional
Allows signers to decline to sign a document if set to 1. Defaults to 0.
allow_reassign optional
Allows signers to reassign their signature requests to other signers if set to 1. Defaults to 0.
Note: Only available for Gold plan and higher.
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. type - one of the Type options
    3. x & y - (int) location coordinates of the field in pixels
    4. page - (int) page in the document where the field should be placed (requires documents be PDF files)
        a. When the page number parameter is supplied, the API will use the new coordinate system.
        b. Check out the differences between both coordinate systems and how to use them.
    5. width & height - (int) size of the field in pixels
    6. required - (boolean) whether this field is required
    7. signer - (int | string) signer index identified by the offset %i% in the signers[%i%] parameter, indicating which signer should fill out the field. If your type is 'text-merge' you can set this to 'sender', so the field is non-editable by any signer.

Optionally, each field may contain a name (string) parameter. This is a display name for the field.

Each text field may contain a validation_type parameter. Check out the list of validation types to learn more about the possible values.

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 page of the 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": 1,
            "page": 1,
            "validation_type": "numbers_only"
        },
        {
            "api_id": "uniqueIdHere_2",
            "name": "",
            "type": "signature",
            "x": 530,
            "y": 415,
            "width": 120,
            "height": 30,
            "required": true,
            "signer": 0,
            "page": 1
        }
    ]
]
signing_options optional
This allows the requester to specify the types allowed for creating a signature.
  • draw: [boolean] allows drawing the signature (default: false)
  • type: [boolean] allows typing the signature (default: false)
  • upload: [boolean] allows uploading the signature (default: false)
  • phone: [boolean] allows using a smartphone to email the signature (default: false)
  • default: [string] the default type shown (limited to the above types) (required if signing_options defined)

Note: If signing_options are not defined in the request, the allowed types will default to those specified in the account settings.
field_options optional
This allows the requester to specify field options for a signature request.
  • date_format: [string] allows requester to specify the date format (see list of allowed formats)
    Note: Only available for Platinum and higher.

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
signing_options = {"draw": true, "type": true, "upload": true, "phone": false, "default": "draw"}
field_options = {"date_format": "DD - MM - YYYY"}
test_mode = 1
Send with Form
DEPRECATED
POST /signature_request/send_with_reusable_form
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
Send with Template
POST /signature_request/send_with_template
Creates 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.
allow_decline optional
Allows signers to decline to sign a document 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. RoleName is case-sensitive.
signers[%RoleName%][email_address]
The email address of the signer filling the role of RoleName. RoleName is case-sensitive.
signers[%RoleName%][pin] optional
The 4- to 12-character access code that will secure this signer's signature page. RoleName is case-sensitive.
signers[%RoleName%][sms_phone_number] optional
An E.164 formatted phone number that will receive a code via SMS to access this signer's signature page.
Note: Not available in test mode and requires a Platinum plan or higher.
signers[%RoleName%][group]
To send to a signer group, specify the name of the group and assign the signers that are part of it under the same role. Any of the signers is eligible to sign for the entire group.
The following is an example of a signature request sent to a signer group of 3 signers assigned to the role name "HR": 
signers[HR][group]=Authorized signatory
signers[HR][0][name]=Jack
signers[HR][0][email_address]=jack@example.com
signers[HR][1][name]=Jill
signers[HR][1][email_address]=jill@example.com
signers[HR][2][name]=John
signers[HR][2][email_address]=john@example.com
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 optional
A JSON array defining values and options for custom fields. Required when a custom field exists in the Template.
  • name: the name, or "Field Label," of the custom field (the field's API ID can be used here as well)
  • value: the value of the custom field
  • editor: the RoleName allowed to edit the custom field (optional, but required if 'required' is defined)
    Note: Editable custom_fields are only supported for single signer requests or the first signer of ordered signature requests. If more than one signer is assigned to the unordered signature request, any editor value is ignored and the field will not be editable.
  • required: a boolean describing if this field is required (default: false)
custom_fields[%CustomFieldName%] optional
DEPRECATED
The value that will be used to populate the Custom Field with the name of CustomFieldName. The CustomFieldName is the "Field Label" assigned to the field when creating the template. The field's case-sensitive API ID can be used here as well. If the custom field is a checkbox, the value "true" indicates that it is checked by default.
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 1000 characters long.
client_id optional
The client ID of the ApiApp you want to associate with this request.
file[] or file_url[] optional
Append additional files to the signature request. HelloSign will parse the files for text tags. Text tags for signers not on the template will be ignored.

Use file[] to pass the uploaded file(s). Use file_url[] to have HelloSign download the file(s). We currently only support use of either the file[] parameter or file_url[] parameter, not both.
signing_options optional
This allows the requester to specify the types allowed for creating a signature.
  • draw: [boolean] allows drawing the signature (default: false)
  • type: [boolean] allows typing the signature (default: false)
  • upload: [boolean] allows uploading the signature (default: false)
  • phone: [boolean] allows using a smartphone to email the signature (default: false)
  • default: the default type shown (limited to the above types) (required if signing_options defined)

If signing_options are not defined in the request, the allowed types will default to those specified in the account settings.
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 = [{"name":"Cost", "value":"$20,000", "editor":"Client", "required":true}]
signing_options = {"draw": true, "type": true, "upload": true, "phone": false, "default": "draw"}
Bulk Send with Template
POST /signature_request/bulk_send_with_template
Creates BulkSendJob which sends SignatureRequests in bulk based off of a Template.
Description

Creates BulkSendJob which sends up to 250 SignatureRequests in bulk based off of the Template specified with the template_id parameter.

NOTE: Only available for Gold plan and higher.

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.
allow_decline optional
Allows signers to decline to sign a document 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.
signer_file or signer_list
signer_file is a CSV file defining values and options for signer fields. Required unless a signer_list is used, you may not use both. The CSV can have the following columns:
  • name: the name of the signer filling the role of RoleName
  • email_address: email address of the signer filling the role of RoleName
  • pin: the 4- to 12-character access code that will secure this signer's signature page (optional)
  • sms_phone_number: An E.164 formatted phone number that will receive a code via SMS to access this signer's signature page. (optional)
    Note: Not available in test mode and requires a Platinum plan or higher.
  • *_field: any column with a "_field" suffix will be treated as a custom field (optional)
    You may only specify field values here, any other options should be set in the custom_fields request parameter.

Example CSV:
name, email_address, pin, company_field
George, george@example.com, d79a3td, ABC Corp
Mary, mary@example.com, gd9as5b, 123 LLC

signer_list is a JSON array defining values and options for signer fields. Required unless a signer_file is used, you may not use both. Each element in the array can have the following two items:
  • signers: an array of signers using the RoleName as keys (currently only one signer is supported per SignatureRequest)
    • name: the name of the signer filling the role of RoleName
    • email_address: email address of the signer filling the role of RoleName
    • pin: the 4- to 12-character access code that will secure this signer's signature page (optional)
    • sms_phone_number: An E.164 formatted phone number that will receive a code via SMS to access this signer's signature page. (optional)
      Note: Not available in test mode and requires a Platinum plan or higher.
  • custom_fields: an array of custom field values using the field name or API id as keys (optional)
    You may only specify field values here, any other options should be set in the custom_fields request parameter.

Example JSON: 
[
  {
    "signers": {
      "Client": {
        "name": "George",
        "email_address": "george@example.com",
        "pin": "d79a3td"
      }
    },
    "custom_fields": {
      "company": "ABC Corp"
    }
  },
  {
    "signers": {
      "Client": {
        "name": "Mary",
        "email_address": "mary@example.com",
        "pin": "gd9as5b"
      }
    },
    "custom_fields": {
      "company": "123 LLC"
    }
  }
]
custom_fields optional
A JSON array defining values and options for custom fields. You may also specify custom field values in the signer_list or signer_file, but all other options should be set here.
  • name: the name, or "Field Label," of the custom field (the field's API ID can be used here as well)
  • value: the value of the custom field
  • editor: the RoleName allowed to edit the custom field (optional, but required if 'required' is defined)
    Note: Editable custom_fields are only supported for single signer requests or the first signer of ordered signature requests. If more than one signer is assigned to the unordered signature request, any editor value is ignored and the field will not be editable.
  • required: a boolean describing if this field is required (default: false)
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.
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 1000 characters long.
client_id optional
The client ID of the ApiApp you want to associate with this request.
Response
Returns a BulkSendJob object
Example request / response
POST https://[api key]:@api.hellosign.com/v3/signature_request/bulk_send_with_template
template_id = c26b8a16784a872da37ea946b9ddec7c1e11dff6
subject = Purchase Order
message = Glad we could come to an agreement.
signer_list = [{"signers":{"Client":{"name":"George","email_address":"george@example.com"}},"custom_fields":{"Cost":"$20,000"}}]
ccs[Accounting][email_address] = accounting@hellosign.com
Send Request Reminder
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 hour of the last reminder that was sent. This includes manual AND automatic reminders.

NOTE: This action can not be used with embedded signature requests.

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.
name optional
The name of the signer to send a reminder to. Include if two or more signers share an email address.
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
Update Signature Request
POST /signature_request/update/[:signature_request_id]
Update an email address on a signature request.
Description

Updates the email address for a given signer on a signature request. You can listen for the "signature_request_email_bounce" event on your app or account to detect bounced emails, and respond with this method.

NOTE: This action cannot be performed on a signature request with an appended signature page.

Request Parameters
signature_request_id
The id of the SignatureRequest to update.
signature_id
The signature ID for the recipient.
email_address
The new email address for the recipient.
Response
Returns a SignatureRequest object
Example request / response
POST https://[api key]:@api.hellosign.com/v3/signature_request/update/[:signature_request_id]
Cancel Incomplete Signature Request
POST /signature_request/cancel/[:signature_request_id]
Cancels an incomplete SignatureRequest.
Description

Cancels an incomplete signature request. This action is not reversible.

The request will be canceled and signers will no longer be able to sign. If they try to access the signature request they will receive a HTTP 410 status code indicating that the resource has been deleted. Cancelation is asynchronous and a successful call to this endpoint will return an empty 200 OK response if the signature request is eligible to be canceled and has been successfully queued.

This 200 OK response does not indicate a successful cancelation of the signature request itself. The cancelation is confirmed via the "signature_request_canceled" event. It is recommended that a callback handler be implemented to listen for the "signature_request_canceled" event. This callback will be sent only when the cancelation has completed successfully. If a callback handler has been configured and the event has not been received within 60 minutes of making the call, check the status of the request in the API Dashboard and retry the cancelation if necessary.

To be eligible for cancelation, a signature request must have been sent successfully, must not yet have been signed by all signers, and you must either be the sender or own the API app under which it was sent. A partially signed signature request can be canceled.

NOTE: To remove your access to a completed signature request, use the endpoint:
POST /signature_request/remove/[:signature_request_id].

Request Parameters
signature_request_id
The id of the incomplete SignatureRequest to cancel.
Example request / response
POST https://[api key]:@api.hellosign.com/v3/signature_request/cancel/[:signature_request_id]
Remove Signature Request Access
POST /signature_request/remove/[:signature_request_id]
Remove access to a completed SignatureRequest.
Description

Removes your access to a completed signature request. This action is not reversible.

The signature request must be fully executed by all parties (signed or declined to sign). Other parties will continue to maintain access to the completed signature request document(s).

Unlike /signature_request/cancel, this endpoint is synchronous and your access will be immediately removed. Upon successful removal, this endpoint will return a 200 OK response.

Request Parameters
signature_request_id
The id of the SignatureRequest to remove.
Example request / response
POST https://[api key]:@api.hellosign.com/v3/signature_request/remove/[:signature_request_id]
Get Files
GET /signature_request/files/[:signature_request_id]
Obtain a copy of the current documents.
Description

Obtain 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 "pdf" for a single merged document or "zip" for a collection of individual documents.
get_url optional
Boolean. If true, the response will contain a url link to the file instead. Links are only available for PDFs and have a TTL of 3 days. (default = false)
get_data_uri optional
Boolean. If true, the response will contain the file as base64 encoded string. Base64 encoding is only available for PDFs. (default = false)
Response
Returns a PDF or ZIP file, or if get_url is set, a JSON object with a url to the file (PDFs only). If get_data_uri is set, a JSON object with a data_uri representing the base64 encoded file (PDFs only) is returned.
If the files are currently being prepared, a status code of 409 will be returned instead.
Example request / response
GET https://[api key]:@api.hellosign.com/v3/signature_request/files/[:signature_request_id]
Get Final Copy PDF
DEPRECATED
GET /signature_request/final_copy/[:signature_request_id]
Download the PDF copy of the finalized documents.
Description

Download the PDF copy of the finalized documents specified by the signature_request_id parameter. 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]
Send Embedded Signature Request
POST /signature_request/create_embedded
Creates a new SignatureRequest to be signed in an embedded window.
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.
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.
signers[%i%][sms_phone_number] optional
An E.164 formatted phone number that will receive a code via SMS to access this signer's signature page.
Note: Not available in test mode and requires a Platinum plan or higher.
attachments[%i%][name] optional
The name of attachment.
attachments[%i%][instructions] optional
The instructions for uploading the attachment.
attachments[%i%][signer_index] optional
The signer's unique number, see signers[%i%][name] for more details.
attachments[%i%][required] optional
Determines if the attachment must be uploaded.
custom_fields optional
A JSON array defining values and options for custom fields. Required when defining pre-set values in form_fields_per_document or Text Tags.
  • name: the name, or "Field Label," of the custom field (the field's API ID can be used here as well)
  • value: the value of the custom field
  • editor: the RoleName allowed to edit the custom field (optional, but required if 'required' is defined)
    Note: Editable custom_fields are only supported for single signer requests or the first signer of ordered signature requests. If more than one signer is assigned to the unordered signature request, any editor value is ignored and the field will not be editable.
  • required: a boolean describing if this field is required (default: false)
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. Defaults to 0.
hide_text_tags optional
[boolean] Send with a value of 1 if you wish to enable automatic Text Tag removal. Defaults to 0. 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 1000 characters long.
allow_decline optional
Allows signers to decline to sign a document if set to 1. Defaults to 0.
allow_reassign optional
Allows signers to reassign their signature requests to other signers if set to 1. Defaults to 0.
Note: Only available for Gold plan and higher.
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. type - one of the Type options
    3. x & y - (int) location coordinates of the field in pixels
    4. page - (int) page in the document where the field should be placed (requires documents be PDF files)
        a. When the page number parameter is supplied, the API will use the new coordinate system.
        b. Check out the differences between both coordinate systems and how to use them.
    5. width & height - (int) size of the field in pixels
    6. required - (boolean) whether this field is required
    7. signer - (int | string) signer index identified by the offset %i% in the signers[%i%] parameter, indicating which signer should fill out the field. If your type is 'text-merge' you can set this to 'sender', so the field is non-editable by any signer.

Optionally, each field may contain a name (string) parameter. This is a display name for the field.

Each text field may contain a validation_type parameter. Check out the list of validation types to learn more about the possible values.

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 page of the 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": 1,
            "page": 1,
            "validation_type": "numbers_only"
        },
        {
            "api_id": "uniqueIdHere_2",
            "name": "",
            "type": "signature",
            "x": 530,
            "y": 415,
            "width": 120,
            "height": 30,
            "required": true,
            "signer": 0,
            "page": 1
        }
    ],
    []
]
signing_options optional
This allows the requester to specify the types allowed for creating a signature.
  • draw: [boolean] allows drawing the signature (default: false)
  • type: [boolean] allows typing the signature (default: false)
  • upload: [boolean] allows uploading the signature (default: false)
  • phone: [boolean] allows using a smartphone to email the signature (default: false)
  • default: [string] the default type shown (limited to the above types) (required if signing_options defined)

Note: If signing_options are not defined in the request, the allowed types will default to those specified in the account settings.
field_options optional
This allows the requester to specify field options for a signature request.
  • date_format: [string] allows requester to specify the date format (see list of allowed formats)
    Note: Only available for Platinum and higher.

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
signing_options = {"draw": true, "type": true, "upload": true, "phone": false, "default": "draw"}
Send Embedded Signature Request with Form
DEPRECATED
POST /signature_request/create_embedded_with_reusable_form
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
Send Embedded Signature Request with Template
POST /signature_request/create_embedded_with_template
Creates 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.
allow_decline optional
Allows signers to decline to sign a document 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.
signers[%RoleName%][name]
The name of the signer filling the role of RoleName. RoleName is case-sensitive.
signers[%RoleName%][email_address]
The email address of the signer filling the role of RoleName. RoleName is case-sensitive.
signers[%RoleName%][pin] optional
The 4- to 12-character access code that will secure this signer's signature page. RoleName is case-sensitive.
signers[%RoleName%][sms_phone_number] optional
An E.164 formatted phone number that will receive a code via SMS to access this signer's signature page.
Note: Not available in test mode and requires a Platinum plan or higher.
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 optional
A JSON array defining values and options for custom fields. Required when a custom field exists in the Template.
  • name: the name, or "Field Label," of the custom field (the field's API ID can be used here as well)
  • value: the value of the custom field
  • editor: the RoleName allowed to edit the custom field (optional, but required if 'required' is defined)
    Note: Editable custom_fields are only supported for single signer requests or the first signer of ordered signature requests. If more than one signer is assigned to the unordered signature request, any editor value is ignored and the field will not be editable.
  • required: a boolean describing if this field is required (default: false)
custom_fields[%CustomFieldName%]
optional
DEPRECATED
The value that will be used to populate the Custom Field with the name of CustomFieldName. The CustomFieldName is the case-sensitive "Field Label" assigned to the field when creating the template. The field's API ID can be used here as well. If the custom field is a checkbox, the value "true" indicates that it is checked by default.
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 1000 characters long.
file[] or file_url[] optional
Append additional files to the signature request. HelloSign will parse the files for text tags. Text tags for signers not on the template will be ignored.

Use file[] to pass the uploaded file(s). Use file_url[] to have HelloSign download the file(s). We currently only support use of either the file[] parameter or file_url[] parameter, not both.
signing_options optional
This allows the requester to specify the types allowed for creating a signature.
  • draw: [boolean] allows drawing the signature (default: false)
  • type: [boolean] allows typing the signature (default: false)
  • upload: [boolean] allows uploading the signature (default: false)
  • phone: [boolean] allows using a smartphone to email the signature (default: false)
  • default: the default type shown (limited to the above types) (required if signing_options defined)

If signing_options are not defined in the request, the allowed types will default to those specified in the account settings.
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 = [{"name":"Cost", "value":"$20,000", "editor":"Client", "required":true}]
signing_options = {"draw": true, "type": true, "upload": true, "phone": false, "default": "draw"}
Embedded Bulk Send with Template
POST /signature_request/bulk_create_embedded_with_template
Creates BulkSendJob which sends SignatureRequests in bulk based off of a Template to be signed in an embedded window.
Description

Creates BulkSendJob which sends up to 250 SignatureRequests in bulk based off of the Template specified with the template_id parameter to be signed in an embedded iFrame. These embedded signature requests can only be signed in embedded iFrames whereas normal signature requests can only be signed on HelloSign.

NOTE: Only available for Gold plan and higher.

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.
allow_decline optional
Allows signers to decline to sign a document if set to 1. Defaults to 0.
client_id
The client ID of the ApiApp you want to associate with this request.
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.
signer_file or signer_list
signer_file is a CSV file defining values and options for signer fields. Required unless a signer_list is used, you may not use both. The CSV can have the following columns:
  • name: the name of the signer filling the role of RoleName
  • email_address: email address of the signer filling the role of RoleName
  • pin: the 4- to 12-character access code that will secure this signer's signature page (optional)
  • sms_phone_number: An E.164 formatted phone number that will receive a code via SMS to access this signer's signature page. (optional)
    Note: Not available in test mode and requires a Platinum plan or higher.
  • *_field: any column with a "_field" suffix will be treated as a custom field (optional)
    You may only specify field values here, any other options should be set in the custom_fields request parameter.

Example CSV:
name, email_address, pin, company_field
George, george@example.com, d79a3td, ABC Corp
Mary, mary@example.com, gd9as5b, 123 LLC

signer_list is a JSON array defining values and options for signer fields. Required unless a signer_file is used, you may not use both. Each element in the array can have the following two items:
  • signers: an array of signers using the RoleName as keys (currently only one signer is supported per SignatureRequest)
    • name: the name of the signer filling the role of RoleName
    • email_address: email address of the signer filling the role of RoleName
    • pin: the 4- to 12-character access code that will secure this signer's signature page (optional)
    • sms_phone_number: An E.164 formatted phone number that will receive a code via SMS to access this signer's signature page. (optional)
      Note: Not available in test mode and requires a Platinum plan or higher.
  • custom_fields: an array of custom field values using the field name or API id as keys (optional)
    You may only specify field values here, any other options should be set in the custom_fields request parameter.

Example JSON: 
[
  {
    "signers": {
      "Client": {
        "name": "George",
        "email_address": "george@example.com",
        "pin": "d79a3td"
      }
    },
    "custom_fields": {
      "company": "ABC Corp"
    }
  },
  {
    "signers": {
      "Client": {
        "name": "Mary",
        "email_address": "mary@example.com",
        "pin": "gd9as5b"
      }
    },
    "custom_fields": {
      "company": "123 LLC"
    }
  }
]
custom_fields optional
A JSON array defining values and options for custom fields. You may also specify custom field values in the signer_list or signer_file, but all other options should be set here.
  • name: the name, or "Field Label," of the custom field (the field's API ID can be used here as well)
  • value: the value of the custom field
  • editor: the RoleName allowed to edit the custom field (optional, but required if 'required' is defined)
    Note: Editable custom_fields are only supported for single signer requests or the first signer of ordered signature requests. If more than one signer is assigned to the unordered signature request, any editor value is ignored and the field will not be editable.
  • required: a boolean describing if this field is required (default: false)
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.
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 1000 characters long.
Response
Returns a BulkSendJob object
Example request / response
POST https://[api key]:@api.hellosign.com/v3/signature_request/bulk_create_embedded_with_template
template_id = c26b8a16784a872da37ea946b9ddec7c1e11dff6
subject = Purchase Order
message = Glad we could come to an agreement.
signer_list = [{"signers":{"Client":{"name":"George","email_address":"george@example.com"}},"custom_fields":{"Cost":"$20,000"}}]
ccs[Accounting][email_address] = accounting@hellosign.com
client_id = 1a659d9ad95bccd307ecad78d72192f8
Release On-Hold Signature Request
POST /signature_request/release_hold/[:signature_request_id]
Releases a SignatureRequest from hold.
Description

Releases a held SignatureRequest that was claimed and prepared from an UnclaimedDraft. The owner of the Draft must indicate at Draft creation that the SignatureRequest created from the Draft should be held. Releasing the SignatureRequest will send requests to all signers.

Request Parameters
signature_request_id
The id of the SignatureRequest to release.
Response
Returns a SignatureRequest object
Example request / response
POST https://[api key]:@api.hellosign.com/v3/signature_request/release_hold/[:signature_request_id]
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).
ACTION URI - Description
Get Reusable Form
DEPRECATED
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. 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]
List Reusable Forms
DEPRECATED
GET /reusable_form/list
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.
page_size optional
Number of objects to be returned per page. Must be between 1 and 100. Default is 20.
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
Add User Access to Form
DEPRECATED
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. 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
Remove User Access to Form
DEPRECATED
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. 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
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 overridden 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 overridden when sending the SignatureRequest.
metadata The metadata attached to the template.
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 displayed first and the highest last.
field_groups An array of Form Field Group objects.
name The name of the form field group.
rule The rule used to validate checkboxes in the form field group. See checkbox field grouping.
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.
group The name of the group this field is in. If this field is not a group, this defaults to null.
custom_fields An array of Custom Field objects
name The name of the Custom Field.
type The type of this Custom Field. Only 'text' and 'checkbox' are currently supported.
x The horizontal offset in pixels for this field.
y The vertical offset in pixels for this field.
width The width in pixels of this field.
height The height in pixels of this field.
required Boolean showing whether or not this field is required.
group The name of the group this field is in. If this field is not a group, this defaults to null.
avg_text_length Average text length in custom field.
num_lines Number of lines.
num_chars_per_line Number of character per line.
named_form_fields DEPRECATED Use "form_fields" under the "documents" array instead.
reusable_form_id DEPRECATED
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_locked Returns true if the user has been locked out of their account by a team admin.
is_paid_hs Returns true if the user has a paid HelloSign account.
is_paid_hf Returns true if 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.
is_creator True if you are the owner of this template, false if it's been shared with you by a team member.
is_embedded True if this template was created using an embedded flow, false if it was created on our website.
can_edit Indicates whether edit rights have been granted to you by the owner (always true if that's you).
is_locked True if you exceed Template quota; these can only be used in test mode. False if the template is included with the Template quota; these can be used at any time.
ACTION URI - Description
Get Template
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]
List Templates
GET /template/list
Lists your Templates.
Description

Returns a list of the Templates that are accessible by you.

Take a look at our search guide to learn more about querying templates.

Request Parameters
account_id optional
Which account to return Templates for. Must be a team member. Use "all" to indicate all team members. Defaults to your account.
page optional
Which page number of the Template List to return. Defaults to 1.
page_size optional
Number of objects to be returned per page. Must be between 1 and 100. Default is 20.
query optional
String that includes search terms and/or fields to be used to filter the Template objects.
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
Add User Access to Template
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
Remove User Access to Template
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
Create Embedded Template Draft
POST /template/create_embedded_draft
Creates an embedded template draft for further editing.
Description

The first step in an embedded template workflow. Creates a draft template that can then be further set up in the template 'edit' stage.

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.
file[] OR file_url[]
Use file[] to indicate the uploaded file(s) to use for the template. Use file_url[] to have HelloSign download the file(s) to use for the template. Currently we only support use of either the file[] parameter or file_url[] parameter, not both.
title optional
The template title
subject optional
The template title (alias)
message optional
The default template email message
signer_roles[%i%][name]
The role name of the signer that will be displayed when the template is used to create a signature request. %i% is an integer that should uniquely identify a signer role.
signer_roles[%i%][order] optional
The order in which this signer role is required to sign. %i% is an integer that should uniquely identify a signer role.
attachments[%i%][name] optional
The name of attachment.
attachments[%i%][instructions] optional
The instructions for uploading the attachment.
attachments[%i%][signer_index] optional
The signer's unique number, see signers[%i%][name] for more details.
attachments[%i%][required] optional
Determines if the attachment must be uploaded.
cc_roles[] optional
The CC roles that must be assigned when using the template to send a signature request
merge_fields optional
The merge fields that can be placed on the template's document(s) by the user claiming the template draft. These are typically fields that can be pre-populated by your application when using the resulting template to send a signature request. Each merge field object must have two parameters: name and type. Names must be unique and type can only be "text" or "checkbox".
skip_me_now optional
Disables the "Me (Now)" option for the person preparing the document. Defaults to 0.
use_preexisting_fields optional
[boolean] Enable the detection of predefined PDF fields by setting the use_preexisting_fields to "1" (defaults to disabled, or "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 1000 characters long.
allow_reassign optional
Allows signers to reassign their signature requests to other signers if set to 1. Defaults to 0. Note: Only available for Gold plan and higher.
allow_ccs optional
This allows the requester to specify whether the user is allowed to provide email addresses to CC when creating a template
field_options optional
This allows the requester to specify field options for signature requests created using the template.
  • date_format: [string] allows requester to specify the date format (see list of allowed formats)
    Note: Only available for Platinum and higher.

editor_options optional
This allows the requester to specify editor options when a preparing a document.
  • allow_edit_signers: [boolean] allows requesters to edit the list of signers (default: false)
  • allow_edit_documents: [boolean] allows requesters to edit documents, including delete and add (default: false)

Response
Returns a Template object with parameters : "template_id", "edit_url", "expires_at"
Example request / response
POST https://[api key]:@api.hellosign.com/v3/template/create_embedded_draft
test_mode = 1
client_id = 37dee8d8440c66d54cfa05d92c160882
file[0] = @NDA.pdf
title = Test Template
subject = Please sign this document
message = For your approval.
signer_roles[0][name] = Client
signer_roles[0][order] = 0
signer_roles[1][name] = Witness
signer_roles[1][order] = 1
cc_roles[0] = Manager
merge_fields = [{"name":"Full Name","type":"text"},{"name":"Is Registered?","type":"checkbox"}]
field_options = {"date_format": "DD - MM - YYYY"}
Delete Template
POST /template/delete/[:template_id]
Deletes the specified template.
Description

Completely deletes the template specified from the account.

Request Parameters
template_id
The id of the Template to delete.
Example request / response
POST https://[api key]:@api.hellosign.com/v3/template/delete/[:template_id]
template_id = 5de8179668f2033afac48da1868d0093bf133266
Get Template Files
GET /template/files/[:template_id]
Obtain a copy of a template's original files.
Description

Obtain a copy of the original files specified by the template_id parameter.

Request Parameters
template_id
The id of the template files to retrieve.
file_type optional
Set to "pdf" for a single merged document or "zip" for a collection of individual documents.
get_url optional
Boolean. If true, the response will contain a url link to the file instead. Links are only available for PDFs and have a TTL of 3 days. (default = false)
get_data_uri optional
Boolean. If true, the response will contain the file as base64 encoded string. Base64 encoding is only available for PDFs. (default = false)
Response
Returns a PDF or ZIP file, or if get_url is set, a JSON object with a url to the file (PDFs only). If get_data_uri is set, a JSON object with a data_uri representing the base64 encoded file (PDFs only) is returned.
If the files are currently being prepared, a status code of 409 will be returned instead.
Example request / response
GET https://[api key]:@api.hellosign.com/v3/template/files/[:template_id]
Update Template Files
POST /template/update_files/[:template_id]
Overlays a new file with the overlay of an existing template.
Description

Overlays a new file with the overlay of an existing template. The new file(s) must:
1) have the same or higher page count
2) the same orientation as the file(s) being replaced.

This will not overwrite or in any way affect the existing template. Both the existing template and new template will be available for use after executing this endpoint. Also note that this will decrement your template quota.

Overlaying new files is asynchronous and a successful call to this endpoint will return an empty 200 OK response if the request passes initial validation checks.

It is recommended that a callback be implemented to listen for the callback event. A "template_created" event will be sent when the files are updated or a "template_error" event will be sent if there was a problem while updating the files. If a callback handler has been configured and the event has not been received within 60 minutes of making the call, check the status of the request in the API dashboard and retry the request if necessary.

If the page orientation or page count is different from the original template document, we will notify you with a "template_error" callback event.

Request Parameters
template_id
The ID of the template whose files to update
file[] or file_url[]
Use file[] to pass the uploaded file(s). Use file_url[] to have HelloSign download the file(s). We currently only support use of either the file[] parameter or file_url[] parameter, not both.
subject optional
The new default template email subject
message optional
The new default template email message
client_id optional
Client ID of the app you're using to create this template
test_mode optional
Whether this is a test. The signature request created from this template will not be legally binding if set to 1. Defaults to 0.
Response
Returns a template ID
Example request / response
POST https://[api key]:@api.hellosign.com/v3/template/update_files/[:template_id]
Bulk Send JobContains information about bulk sent signature requestsContains information about bulk sent signature requests
BulkSendJob Response Object.
bulk_send_job_id The id of the BulkSendJob.
total The total amount of SignatureRequests queued for sending.
is_creator True if you are the owner of this BulkSendJob, false if it's been shared with you by a team member.
created_at Time that the BulkSendJob was created.
ACTION URI - Description
Get Bulk Send Job
GET /bulk_send_job/[:bulk_send_job_id]
Gets a BulkSendJob that includes all SignatureRequests it has sent.
Description

Returns the status of the BulkSendJob and its SignatureRequests specified by the bulk_send_job_id parameter.

Request Parameters
bulk_send_job_id
The id of the BulkSendJob to retrieve.
Response
Returns a BulkSendJob object
Response Parameters
bulk_send_job
A BulkSendJob object.
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/bulk_send_job/[:bulk_send_job_id]
List Bulk Send Jobs
GET /bulk_send_job/list
Lists the BulkSendJob that you have access to.
Description

Returns a list of BulkSendJob that you can access.

Request Parameters
page optional
Which page number of the BulkSendJob List to return. Defaults to 1.
page_size optional
Number of objects to be returned per page. Must be between 1 and 100. Default is 20.
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
bulk_send_jobs
An array of BulkSendJob objects.
Example request / response
GET https://[api key]:@api.hellosign.com/v3/bulk_send_job/list
ReportProvides insights into your team's user activity and document statusProvides insights into your team's user activity and document status
Report Response Object.
success A message indicating the requested operation's success
start_date The (inclusive) start date for the report data in MM/DD/YYYY format.
end_date The (inclusive) end date for the report data in MM/DD/YYYY format.
report_type A comma-separated list of the report type(s) that were requested.
ACTION URI - Description
Create Report
POST /report/create
Creates one or more report(s).
Description

Request the creation of one or more report(s).

When the report(s) have been generated, you will receive an email (one per requested report type) containing a link to download the report as a CSV file. The requested date range may be up to 12 months in duration, and start_date must not be more than 10 years in the past.

Request Parameters
start_date
The (inclusive) start date for the report data in MM/DD/YYYY format.
end_date
The (inclusive) end date for the report data in MM/DD/YYYY format.
report_type[]
The type(s) of the report you are requesting. Allowed values are "user_activity" and "document_status". User activity reports contain list of all users and their activity during the specified date range. Document status report contain a list of signature requests created in the specified time range (and their status).
Response
Returns a Report object
Example request / response
POST https://[api key]:@api.hellosign.com/v3/report/create
start_date = 09/01/2020
end_date = 09/01/2020
report_type[0] = user_activity
report_type[1] = document_status
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.
is_locked Returns true if the user has been locked out of their account by a team admin.
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.
ACTION URI - Description
Get Team
GET /team
Gets 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
Create Team
POST /team/create
Creates 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
Update Team
POST /team
Updates 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
Delete Team
POST /team/destroy
Deletes 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
Add User to Team
POST /team/add_member
Adds or invites a user to your Team
Description

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 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
Remove User from Team
POST /team/remove_member
Removes a user from your Team
Description

Removes the provided user Account from your Team. If the Account had an outstanding invitation to your Team, the invitation will be expired. If you choose to transfer documents from the removed Account to an Account provided in the new_owner_email_address parameter (available only for Enterprise plans), the response status code will be 201, which indicates that your request has been queued but not fully executed.

Request Parameters
account_id OR email_address
The ID or email address of the Account to remove from your Team. The account ID prevails if both are provided.
new_owner_email_address optional
The email address of an Account on this Team to receive all documents, templates, and API apps (if applicable) from the removed Account. If not provided, and on an Enterprise plan, this data will remain with the removed Account. Note: Only available for Enterprise plans.
Response
Returns a Team object
Example request / response
POST https://[api key]:@api.hellosign.com/v3/team/remove_member
email_address = teammate@hellosign.com
new_owner_email_address = new_teammate@hellosign.com
Unclaimed DraftA group of documents that a user can take ownership of via the claim URLA group of documents that a user can take ownership of via the claim URL
UnclaimedDraft Response Object.
signature_request_id The ID of the signature request that is represented by this UnclaimedDraft.
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.
requesting_redirect_url The URL you want signers redirected to after they successfully request a signature (Will only be returned in the response if it is applicable to the request.).
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.
ACTION URI - Description
Create Unclaimed Draft
POST /unclaimed_draft/create
Creates 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.
attachments[%i%][name] optional
The name of attachment.
attachments[%i%][instructions] optional
The instructions for uploading the attachment.
attachments[%i%][signer_index] optional
The signer's unique number, see signers[%i%][name] for more details.
attachments[%i%][required] optional
Determines if the attachment must be uploaded.
custom_fields optional
A JSON array defining values and options for custom fields. Required when defining pre-set values in form_fields_per_document or Text Tags.
  • name: the name, or "Field Label," of the custom field (the field's API ID can be used here as well)
  • value: the value of the custom field
  • editor: the RoleName allowed to edit the custom field (optional, but required if 'required' is defined)
    Note: Editable custom_fields are only supported for single signer requests or the first signer of ordered signature requests. If more than one signer is assigned to the unordered signature request, any editor value is ignored and the field will not be editable.
  • required: a boolean describing if this field is required (default: false)
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 or use_preexisting_fields optional
[boolean] Set use_text_tags to 1 to enable Text Tags parsing in your document (defaults to disabled, or 0). Alternatively, if your PDF contains pre-defined fields, enable the detection of these fields by setting the use_preexisting_fields to 1 (defaults to disabled, or 0). Currently we only support use of either use_text_tags or use_preexisting_fields parameter, not both.
hide_text_tags optional
[boolean] Send with a value of 1 if you wish to enable automatic Text Tag removal. Defaults to 0. 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 1000 characters long.
allow_decline optional
Allows signers to decline to sign a document if set to 1. Defaults to 0.
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. type - one of the Type options
    3. x & y - (int) location coordinates of the field in pixels
    4. page - (int) page in the document where the field should be placed (requires documents be PDF files)
        a. When the page number parameter is supplied, the API will use the new coordinate system.
        b. Check out the differences between both coordinate systems and how to use them.
    5. width & height - (int) size of the field in pixels
    6. required - (boolean) whether this field is required
    7. signer - (int | string) signer index identified by the offset %i% in the signers[%i%] parameter, indicating which signer should fill out the field. If your type is 'text-merge' you can set this to 'sender', so the field is non-editable by any signer.

Optionally, each field may contain a name (string) parameter. This is a display name for the field.

Each text field may contain a validation_type parameter. Check out the list of validation types to learn more about the possible values.

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 page of the 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": 1,
            "page": 1,
            "validation_type": "numbers_only"
        },
        {
            "api_id": "uniqueIdHere_2",
            "name": "",
            "type": "signature",
            "x": 530,
            "y": 415,
            "width": 120,
            "height": 30,
            "required": true,
            "signer": 0,
            "page": 1
        }
    ],
    []
]
signing_options optional
This allows the requester to specify the types allowed for creating a signature.
  • draw: [boolean] allows drawing the signature (default: false)
  • type: [boolean] allows typing the signature (default: false)
  • upload: [boolean] allows uploading the signature (default: false)
  • phone: [boolean] allows using a smartphone to email the signature (default: false)
  • default: [string] the default type shown (limited to the above types) (required if signing_options defined)

Note: If signing_options are not defined in the request, the allowed types will default to those specified in the account settings.
field_options optional
This allows the requester to specify field options for a signature request.
  • date_format: [string] allows requester to specify the date format (see list of allowed formats)
    Note: Only available for Platinum and higher.

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
Create Embedded Unclaimed Draft
POST /unclaimed_draft/create_embedded
Creates 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: 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."
type optional
The type of the draft. By default this is "request_signature", but you can set it to "send_document" if you want to self sign a document and download it.
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.
attachments[%i%][name] optional
The name of attachment.
attachments[%i%][instructions] optional
The instructions for uploading the attachment.
attachments[%i%][signer_index] optional
The signer's unique number, see signers[%i%][name] for more details.
attachments[%i%][required] optional
Determines if the attachment must be uploaded.
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.
custom_fields optional
A JSON array defining values and options for custom fields. Required when defining pre-set values in form_fields_per_document or Text Tags.
  • name: the name, or "Field Label," of the custom field (the field's API ID can be used here as well)
  • value: the value of the custom field
  • editor: the RoleName allowed to edit the custom field (optional, but required if 'required' is defined)
    Note: Editable custom_fields are only supported for single signer requests or the first signer of ordered signature requests. If more than one signer is assigned to the unordered signature request, any editor value is ignored and the field will not be editable.
  • required: a boolean describing if this field is required (default: false)
use_text_tags optional
[boolean] Send with a value of 1 if you wish to enable Text Tags parsing in your document. Defaults to 0.
hide_text_tags optional
[boolean] Send with a value of 1 if you wish to enable automatic Text Tag removal. Defaults to 0. 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.
use_text_tags or use_preexisting_fields optional
[boolean] Set use_text_tags to 1 to enable Text Tags parsing in your document (defaults to disabled, or 0). Alternatively, if your PDF contains pre-defined fields, enable the detection of these fields by setting the use_preexisting_fields to 1 (defaults to disabled, or 0). Currently we only support use of either use_text_tags or use_preexisting_fields parameter, not both.
is_for_embedded_signing optional
[boolean] The request created from this draft will also be signable in embedded mode if set to 1. Defaults to 0.
skip_me_now optional
Disables the "Me (Now)" option for the person preparing the document. Does not work with type "send_document". Defaults to 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 1000 characters long.
allow_decline optional
Allows signers to decline to sign a document if set to 1. Defaults to 0.
allow_reassign optional
Allows signers to reassign their signature requests to other signers if set to 1. Defaults to 0.
Note: Only available for Gold plan and higher.
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. type - one of the Type options
    3. x & y - (int) location coordinates of the field in pixels
    4. page - (int) page in the document where the field should be placed (requires documents be PDF files)
        a. When the page number parameter is supplied, the API will use the new coordinate system.
        b. Check out the differences between both coordinate systems and how to use them.
    5. width & height - (int) size of the field in pixels
    6. required - (boolean) whether this field is required
    7. signer - (int | string) signer index identified by the offset %i% in the signers[%i%] parameter, indicating which signer should fill out the field. If your type is 'text-merge' you can set this to 'sender', so the field is non-editable by any signer.

Optionally, each field may contain a name (string) parameter. This is a display name for the field.

Each text field may contain a validation_type parameter. Check out the list of validation types to learn more about the possible values.

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 page of the 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": 1,
            "page": 1,
            "validation_type": "numbers_only"
        },
        {
            "api_id": "uniqueIdHere_2",
            "name": "",
            "type": "signature",
            "x": 530,
            "y": 415,
            "width": 120,
            "height": 30,
            "required": true,
            "signer": 0,
            "page": 1
        }
    ],
    []
]
signing_options optional
This allows the requester to specify the types allowed for creating a signature.
  • draw: [boolean] allows drawing the signature (default: false)
  • type: [boolean] allows typing the signature (default: false)
  • upload: [boolean] allows uploading the signature (default: false)
  • phone: [boolean] allows using a smartphone to email the signature (default: false)
  • default: [string] the default type shown (limited to the above types) (required if signing_options defined)

Note: If signing_options are not defined in the request, the allowed types will default to those specified in the account settings.
allow_ccs optional
This allows the requester to specify whether the user is allowed to provide email addresses to CC when claiming the draft
hold_request optional
The request from this draft will not automatically send to signers post-claim if set to 1. Requester must release the request from hold when ready to send. Defaults to 0.
field_options optional
This allows the requester to specify field options for a signature request.
  • date_format: [string] allows requester to specify the date format (see list of allowed formats)
    Note: Only available for Platinum and higher.

editor_options optional
This allows the requester to specify editor options when a preparing a document.
  • allow_edit_signers: [boolean] allows requesters to edit the list of signers (default: false)
  • allow_edit_documents: [boolean] allows requesters to edit documents, to delete only (default: false)

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
Create Embedded Unclaimed Draft with Template
POST /unclaimed_draft/create_embedded_with_template
Creates a new Draft using an existing template that will be claimed for use in an embedded iFrame.
Description

Creates a new Draft with a previously saved template 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: 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.
template_id or template_ids[%i%]
Use template_id to create a request from a single Template. Use template_ids[%i%] to create a request 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.
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."
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.
signers[%RoleName%][name]
The name of the signer filling the role of RoleName. RoleName is case-sensitive.
signers[%RoleName%][email_address]
The email address of the signer filling the role of RoleName. RoleName is case-sensitive.
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. RoleName is case-sensitive.
signing_redirect_url optional
The URL you want the signer redirected to after they successfully sign.
requesting_redirect_url optional
The URL you want signers redirected to after they successfully request a signature.
is_for_embedded_signing optional
[boolean] The request created from this draft will also be signable in embedded mode if set to 1. Defaults to 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 1000 characters long.
custom_fields optional
A JSON array defining values for custom fields. Required when a custom field exists in the Template.
  • name: the name, or "Field Label," of the custom field (the field's API ID can be used here as well)
  • value: the value of the custom field
  • editor: the RoleName allowed to edit the custom field (optional, but required if 'required' is defined)
    Note: Editable custom_fields are only supported for single signer requests or the first signer of ordered signature requests. If more than one signer is assigned to the unordered signature request, any editor value is ignored and the field will not be editable.
  • required: a boolean describing if this field is required (default: false).
custom_fields[%CustomFieldName%] optional
DEPRECATED
The value that will be used to populate the Custom Field with the name of CustomFieldName. The CustomFieldName is the case-sensitive "Field Label" assigned to the field when creating the template. The field's API ID can be used here as well. If the custom field is a checkbox, the value "true" indicates that it is checked by default.
file[] or file_url[] optional
Append additional files to the signature request. HelloSign will parse the files for text tags. Text tags for signers not on the template will be ignored.

Use file[] to pass the uploaded file(s). Use file_url[] to have HelloSign download the file(s). We currently only support use of either the file[] parameter or file_url[] parameter, not both.
skip_me_now optional
Disables the "Me (Now)" option for the person preparing the document. Defaults to 0.
allow_decline optional
Allows signers to decline to sign a document if set to 1. Defaults to 0.
allow_reassign optional
Allows signers to reassign their signature requests to other signers if set to 1. Defaults to 0. Note: Only available for Gold plan and higher.
hold_request optional
The request from this draft will not automatically send to signers post-claim if set to 1. Requester must release the request from hold when ready to send. Defaults to 0.
signing_options optional
This allows the requester to specify the types allowed for creating a signature.
  • draw: [boolean] allows drawing the signature (default: false)
  • type: [boolean] allows typing the signature (default: false)
  • upload: [boolean] allows uploading the signature (default: false)
  • phone: [boolean] allows using a smartphone to email the signature (default: false)
  • default: the default type shown (limited to the above types) (required if signing_options defined)

If signing_options are not defined in the request, the allowed types will default to those specified in the account settings.
field_options optional
This allows the requester to specify field options for a signature request.
  • date_format: [string] allows requester to specify the date format (see list of allowed formats)
    Note: Only available for Platinum and higher.

editor_options optional
This allows the requester to specify editor options when a preparing a document.
  • allow_edit_signers: [boolean] allows requesters to edit the list of signers (default: false)
  • allow_edit_documents: [boolean] allows requesters to edit documents, including delete and add (default: false)

Response
Returns an UnclaimedDraft object
Example request / response
POST https://[api key]:@api.hellosign.com/v3/unclaimed_draft/create_embedded_with_template
client_id = b6b8e7deaf8f0b95c029dca049356d4a2cf9710a
template_id = 61a832ff0d8423f91d503e76bfbcc750f7417c78
requester_email_address = jack@hellosign.com
signers[Client][name] = George
signers[Client][email_address] = george@example.com
ccs[Accounting][email_address] = accounting@hellosign.com
custom_fields = [{"name":"Cost", "value":"$20,000"}]
Unclaimed Draft Edit and Resend
POST /unclaimed_draft/edit_and_resend/[:signature_request_id]
Creates a new signature request from an embedded request that can be edited prior to being sent.
Description

Creates a new signature request from an embedded request that can be edited prior to being sent to the recipients. Param, test_mode, can be edited prior to request. Signers can be edited in embedded editor. Requester's email address will remain unchanged if requester_email_address parameter is not set.

NOTE: Embedded unclaimed drafts can only be accessed in embedded iFrames whereas normal drafts can be used and accessed on HelloSign.

Request Parameters
signature_request_id
The ID of the signature request to edit and resend
client_id
Client ID of the app you're using to create this draft. Visit our embedded page to learn more about this parameter.
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.
requesting_redirect_url optional
The URL you want signers redirected to after they successfully request a signature. Defaults to value from original embedded request.
signing_redirect_url optional
The URL you want signers redirected to after they successfully sign.
is_for_embedded_signing optional
The request created from this draft will also be signable in embedded mode if set to 1. Defaults to 0. Defaults to value from original request if not set.
requester_email_address optional
The email address of the user that should be designated as the requester of this draft. If not set, original requester's email address will be used."
editor_options optional
This allows the requester to specify editor options when a preparing a document.
  • allow_edit_signers: [boolean] allows requesters to edit the list of signers (default: false)
  • allow_edit_documents: [boolean] allows requesters to edit documents, including delete and add (default: false)

Response
Returns an UnclaimedDraft object
Example request / response
POST https://[api key]:@api.hellosign.com/v3/unclaimed_draft/edit_and_resend/[:signature_request_id]
client_id = b6b8e7deaf8f0b95c029dca049356d4a2cf9710a
test_mode = 1
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.
ACTION URI - Description
Get Embedded Sign URL
GET /embedded/sign_url/[:signature_id]
Retrieves an embedded signing object.
Description

Retrieves an embedded object containing a signature url that can be opened in an iFrame. Note that templates created via the embedded template process will only be accessible through the API.

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]
Get Embedded Template Edit URL
GET or POST /embedded/edit_url/[:template_id]
Retrieves an embedded template object.
Description

Retrieves an embedded object containing a template url that can be opened in an iFrame. Note that only templates created via the embedded template process are available to be edited with this endpoint.

Request Parameters
test_mode optional
Whether this is a test, locked templates will only be available for editing if this is set to 1. Defaults to 0.
template_id
The id of the template to edit
cc_roles optional
The CC roles that must be assigned when using the template to send a signature request. To remove all CC roles, pass in a single role with no name. For use in a POST request.
merge_fields optional
The merge fields that can be placed on the template's document(s) by the user editing the template. These are typically fields that can be pre-populated by your application when using the resulting template to send a signature request. Each merge field object must have two parameters: name and type. Names must be unique and type can only be "text" or "checkbox". Existing fields for removed merge fields will not be removed from the document, but will default to empty if no custom field is supplied with the signature request. To remove all merge fields, pass in an empty json array. For use in a POST request.
skip_signer_roles optional
If signer roles are already provided, the user will not be prompted to edit them

Note: this parameter will be deprecated in May 2020 and skipping the signer roles screen will become the default behavior. To enforce showing the signer roles screen, use the force_signer_roles parameter below.
skip_subject_message optional
If the subject and message has already been provided, the user will not be prompted to edit them

Note: this parameter will be deprecated in May 2020 and skipping the subject message screen will become the default behavior. To enforce showing the subject message screen, use the force_subject_message parameter below.
force_signer_roles optional
Provide users the ability to review/edit the template signer roles.
force_subject_message optional
Provide users the ability to review/edit the template subject and message.
editor_options optional
This allows the requester to specify editor options when a preparing a document.
  • allow_edit_signers: [boolean] allows requesters to edit the list of signers (default: false)
  • allow_edit_documents: [boolean] allows requesters to edit documents, including delete and add (default: false)

allow_edit_css optional
This allows the requester to enable/disable to add or change CC roles when editing the template .
  • allow_edit_css=1: [boolean] allows requesters to enable editing CC roles in template
  • allow_edit_css=0: [boolean] allows requesters to disable editing CC roles in template

Response
Returns an Embedded object
Example request / response
GET or POST https://[api key]:@api.hellosign.com/v3/embedded/edit_url/[:template_id]
API AppContains information about an API AppContains information about an API App
ApiApp Response Object.
client_id The app's client ID
created_at The time that the app was created
name The name of the app
domain The domain name associated with the app
callback_url The app's callback URL (for events)
is_approved Boolean to indicate if the app has been approved
owner_account An object describing the app's owner
account_id The owner account's ID
email_address The owner account's email address
options An object with options that override account settings
can_insert_everywhere Boolean denoting if signers can "Insert Everywhere" in one click while signing a document
oauth An object describing the app's OAuth properties, or null if OAuth is not configured for the app
callback_url The app's OAuth callback URL
secret The app's OAuth secret, or null if the app does not belong to user
scopes Array of OAuth scopes used by the app
charges_users Boolean indicating whether the app owner or the account granting permission is billed for OAuth requests
white_labeling_options An object with options to customize the app's signer page
ACTION URI - Description
Get API App
GET /api_app/[:client_id]
Gets an API App.
Description

Returns an object with information about an API App.

Request Parameters
client_id
The client ID of the ApiApp to retrieve.
Response
Returns an API App object
Example request / response
GET https://[api key]:@api.hellosign.com/v3/api_app/[:client_id]
List API Apps
GET /api_app/list
Lists your API Apps.
Description

Returns a list of API Apps that are accessible by you. If you are on a team with an Admin or Developer role, this list will include apps owned by teammates.

Request Parameters
page optional
Which page number of the ApiApp List to return. Defaults to 1.
page_size optional
Number of objects to be returned per page. Must be between 1 and 100. Default is 20.
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
api_apps
An array of ApiApp objects.
Example request / response
GET https://[api key]:@api.hellosign.com/v3/api_app/list
Create API App
POST /api_app
Creates a new API App.
Description

Creates a new API App.

Request Parameters
name
The name you want to assign to the ApiApp.
domain
The domain name the ApiApp will be associated with.
callback_url optional
The URL at which the ApiApp should receive event callbacks.
custom_logo_file optional
An image file to use as a custom logo in embedded contexts. (Only applies to some API plans)
oauth[callback_url] optional
The callback URL to be used for OAuth flows. (Required if oauth[scopes] is provided)
oauth[scopes] optional
A comma-separated list of OAuth scopes to be granted to the app. (Required if oauth[callback_url] is provided).
white_labeling_options optional
An array of elements and values serialized to a string, to be used to customize the app's signer page. (Only applies to some API plans)

Take a look at our white labeling guide to learn more.
options[can_insert_everywhere] optional
Determines if signers can use "Insert Everywhere" when signing a document.
Response
Returns an API App object
Example request / response
POST https://[api key]:@api.hellosign.com/v3/api_app
name = My Production App
domain = example.com
oauth[callback_url] = https://example.com/oauth
oauth[scopes] = basic_account_info,request_signature
white_labeling_options = {"primary_button_color":"#00b3e6","primary_button_text_color":"#ffffff"}
Update API App
POST /api_app/[:client_id]
Updates an existing API App.
Description

Updates an existing API App. Can only be invoked for apps you own. Only the fields you provide will be updated. If you wish to clear an existing optional field, provide an empty string.

Request Parameters
name optional
The name you want to assign to the ApiApp.
domain optional
The domain name the ApiApp will be associated with. (Only subdomain changes are allowed if the ApiApp is approved.)
callback_url optional
The URL at which the ApiApp should receive event callbacks.
custom_logo_file optional
An image file to use as a custom logo in embedded contexts. (Only applies to some API plans)
oauth[callback_url] optional
The callback URL to be used for OAuth flows. (Required if oauth[scopes] is provided)
oauth[scopes] optional
A comma-separated list of OAuth scopes to be granted to the app. (Required if oauth[callback_url] is provided)
white_labeling_options optional
An array of elements and values serialized to a string, to be used to customize the app's signer page. (Only applies to some API plans)

Take a look at our white labeling guide to learn more.
options[can_insert_everywhere] optional
Determines if signers can use "Insert Everywhere" when signing a document.
Response
Returns an API App object
Example request / response
POST https://[api key]:@api.hellosign.com/v3/api_app/[:client_id]
name = New Name
callback_url = http://example.com/hellosign
white_labeling_options = {"primary_button_color":"#00b3e6","primary_button_text_color":"#ffffff"}
Delete API App
DELETE /api_app/[:client_id]
Deletes an API App.
Description

Deletes an API App. Can only be invoked for apps you own.

Request Parameters
client_id
The client id of the ApiApp to delete.
Example request / response
DELETE https://[api key]:@api.hellosign.com/v3/api_app/[:client_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 or signature_request_viewed.
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 Callbacks

This type of callback URL can be set up at the account level (either by setting it through an API request to "/v3/account" or on the Account Settings page on hellosign.com).

All signature request events that involve your account are reported to this URL. This includes events such as receiving a signature request, or when a signature request you've sent is signed by someone. Events are reported to the account callback URL for either requests originating on hellosign.com, or on a partner site, via an embedded flow.

App Callbacks

This type of callback URL is set up at the API app level. API apps are used to identify a partner integration and configure embedded flows (embedded signing, embedded requesting, and embedded templates) and OAuth providers.

All events that involve signature requests created by an API app are reported to this URL. The event will include a client_id field to indicate which app the event is being reported for, which allows multiple API apps to share the same callback URL.

Callback Response Format

The default format for messages sent to your callbacks is a multipart ('form/multipart') POST request, with the message details in a POST field named 'json'.

The Java SDK includes an event parsing class, and you can access this field in the $_POST array on PHP. For other platforms, either a library function, such as cgi.parse_multipart (for python) or ActionDispatch::Http::UploadedFile for Rails, or third party options, such as multer for node, may be useful.

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
dropdown An input field for dropdowns
initials An input field for initials
radio An input field for radios
signature A signature input field
text-merge A text field that has default text set by the api
checkbox-merge A checkbox field that has default value set by the api
Checkbox field grouping

Checkbox field groups accept an optional validation rule, which must be met before the user can submit the signed document. These are the options you can specify for validation rule.

Rule Description
require_0-1 Requires at most one checkbox within the group to be checked (radio button functionality)
require_1 Requires only one checkbox within the group to be checked
require_1-ormore Requires at least one checkbox within the group to be checked
Error names

List and details of possible errors that can be returned.

Error Description HTTP Code
bad_request The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications. 400
unauthorized The credentials you have supplied are invalid. 401
payment_required Your account must be credited before the requested action is possible. 402
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. 403
not_found The server has not found anything matching the Request-URI. 404
conflict Your request was well-formed but it cannot be completed to a conflict of some kind. 409
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. 403
invalid_recipient The email address you provided for the recipient is not valid. 400
signature_request_cancel_failed Could not cancel the Signature Request. Either you are not the requester or the Signature Request is fully executed. 400
signature_request_remove_failed Could not remove your access to the Signature Request. Either you are not a party to the request, or it is not yet fully executed. 400
maintenance The request could not be completed because we are currently performing site maintenance. 503
deleted The request was cancelled or deleted. 410
unknown An unknown error has occurred, please try again. Varied, usually 500
method_not_supported The HTTP method used is not supported for the API endpoint being called. 405
signature_request_invalid An error was detected with the signature request parameters during processing. N/A
template_error An error occurred while creating your template. N/A
invalid_reminder A signature request reminder attempt was invalid. This is usually due to the reminder being made against an embedded request N/A
exceeded_rate Your account's API request rate limit has been exceeded. 403
invalid_file A file was invalid. This is usually due to an unsupported file format or a file that exceeds maximum file sizes. N/A
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
parameter_ignored One of the request parameters was ignored because it wasn't being used correctly
non_pdf_text_tags Text Tags were enabled for a file that is not a PDF, which may result in imprecise positioning.
form_fields_overlap Two or more of the form fields specified are overlapping, which may prevent signers from completing the document.
form_fields_placement Form fields must be placed within the document.
deprecated_parameter A parameter was provided which we no longer support. The value will be ignored.
parameter_conflict Two parameters have been provided which are in conflict. One parameter will be ignored.
parameter_missing An essential parameter was missing from the request and has been set to a default value.
partial_success The operation succeeded, but at least one non-essential part of the request failed.
test_mode_only A parameter was provided which will affect your app in test mode but will not affect it in production. Upgrade your account to use in production.
empty_value A non-essential parameter was provided but it does not have a value. The parameter will be ignored.
add_member A warning was generated while attempting to add a user to your team.
parameter_invalid A parameter was provided with an invalid value. The parameter will be modified or ignored.
oauth_grants_revoked OAuth user access grants have been revoked from this app due to a scope change.
cc_disabled The option to email a copy to the other signers and anyone CC'd is disabled for given account.
reassign_unsupported A template with signer reassignment was used on an endpoint that does not support it (e.g. bulk send with template). The template will still be used, but without signer reassignment enabled.
duplicate_template_ids Templates can only be used once in a signature request. A duplicated template ids was passed in the request.
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 App & account callbacks
signature_request_signed A signer has completed all required fields on the SignatureRequest. SignatureRequest App & account callbacks
signature_request_downloadable An updated version of the SignatureRequest PDF is available for download. SignatureRequest App & account callbacks
signature_request_sent The SignatureRequest has been sent successfully. SignatureRequest App & account callbacks
signature_request_declined The SignatureRequest was declined by a signer. SignatureRequest App & account callbacks
signature_request_reassigned The signer has reassigned their signature to a different signer. SignatureRequest App & account callbacks
signature_request_remind All signers have been sent a reminder to complete the SignatureRequest. SignatureRequest App & account 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 App & account callbacks
signature_request_email_bounce An email address for one of the signers on your signature request has bounced. May be correctable by using signature_request/update. SignatureRequest App & account callbacks
signature_request_invalid An error occurred while processing the signature request data on our back-end.

For example: Invalid text tags or email address is not correct when using signature page 		SignatureRequest App & account callbacks
signature_request_canceled The SignatureRequest has been canceled. SignatureRequest App & account callbacks
signature_request_prepared The SignatureRequest has been prepared but not sent. SignatureRequest App & account callbacks
file_error We're unable to convert the file you provided. SignatureRequest App & account callbacks
unknown_error An unknown error occurred while processing a signature request. SignatureRequest App & account callbacks
sign_url_invalid The embedded sign URL you provided is invalid or expired. SignatureRequest App & account callbacks
account_confirmed An account created via one of your apps has been confirmed. Account App callbacks only
template_created The Template has been created. Template App & account callbacks
template_error There was an error while creating your template. Template App & account 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
declined Declined SignatureRequest
error_unknown Unknown error SignatureRequest
error_file File could not be converted SignatureRequest
error_component_position Invalid form fields placement SignatureRequest
error_text_tag File contained invalid text tags SignatureRequest
on_hold_by_requester Request was prepared for signature but has not been sent to signers. Requester must release the request from hold when ready to send. SignatureRequest
Data validation types

Text fields accept an optional validation type, which must be met before the user can submit the signed document. This value can be specified in form fields, text tags, or on the web. These are the options you can specify for validation type.

Type Description
numbers_only Numbers only (negative and decimal values included)
letters_only Letters only (non-English letters included)
phone_number 10- or 11-digit number
bank_routing_number 9-digit number
bank_account_number Minimum 6-digit number
email_address Email address
zip_code 5- or 9-digit number
social_security_number 9-digit number
employer_identification_number 9-digit number
custom_regex Custom regular expression (See note below)
NOTE: When using custom_regex you are required to pass a second parameter validation_custom_regex and you can optionally provide validation_custom_regex_format_label for the error message the user will see in case of an invalid value. Here's an example: 

        "validation_type": "custom_regex",
        "validation_custom_regex": "A[0-9]{3}",
        "validation_custom_regex_format_label": "A000",
Date Formats

The following values can be specified as part of date_format in field_options.

Format Example
MM / DD / YYYY 06 / 13 / 2021
MM - DD - YYYY 06 - 13 - 2021
DD / MM / YYYY 13 / 06 / 2021
DD - MM - YYYY 13 - 06 - 2021
YYYY / MM / DD 2021 / 06 / 13
YYYY - MM - DD 2021 - 06 - 13
OAuth scopes where users are charged
Name Value Description
Account Access account_access Access to basic account information, such as email address and name.
Signature Request Access signature_request_access Access to send, view, and update signature requests and to download document files. Signature requests must be made with oAuth token in order to access.
Template Access template_access Access to view, create, and modify templates.
Team Access team_access Access to view and modify team settings and team members.
API App Access api_app_access Access to view, create, and modify embedded API apps.
OAuth scopes where the app owner is charged
Name Value Description
Basic Account Info (limited) basic_account_info Access basic account information, such as email address and name.
Send Signature Requests (limited) request_signature Send signature requests, access statuses and document files.
White Labeling

White labeling is a term for branding a product that you have purchased. Our white labeling allows you to personalize the logo, color scheme, and legal text of the signer page, making our product blend seamlessly into yours.

Before you can do anything with white labeling, you will need to create an app. You must have an API 2k plan (or higher) to use white labeling in production mode. Otherwise, you can only use it in test mode. All updates made to white labeling options by users with a minimum API 2k plan are immediately active in production. We recommend creating a test app for previewing white labeling changes.

The white labeling options are passed in the create API app and update API app endpoints.

Custom colors

All customizable color elements require valid six-character hexidecimal codes for values. All elements are optional, and any element that you choose not to customize will be set to its default value. If you choose not to customize the value for an element that has a hover state, its hover state will inherit from its active state.

The primary button color is shared with other elements: the word, "Loading," on the loading page, the required fields counter circle, the selected tab in the signature modal, the border of the secondary button, the border of the selected signature image, and the color block on the confirmation page.

The table below lists all customizable color elements.

Element Default
page_background_color #F7F8F9
header_background_color #1A1A1A
text_color1 #808080
text_color2 #FFFFFF
link_color #00B3E6
primary_button_color #00B3E6
primary_button_text_color #FFFFFF
primary_button_color_hover #00B3E6
primary_button_text_color_hover #FFFFFF
secondary_button_color #FFFFFF
secondary_button_text_color #00B3E6
secondary_button_color_hover #FFFFFF
secondary_button_text_color_hover #00B3E6

Here is a layout of customizable elements:

Some customizable color elements must meet a minimum contrast ratio of 2.1 with adjacent elements, for usability reasons. The contrast element header_background_color_light is not customizable. It has a value of #F7F8F9.

Take a look at this contrast ratio UI and formula to learn more about contrast.

Element Contrast elements
text_color1 header_background_color_light
text_color2 header_background_color
primary_button_color header_background_color, header_background_color_light
primary_button_text_color primary_button_color
primary_button_text_color_hover primary_button_color_hover
secondary_button_text_color secondary_button_color
secondary_button_text_color_hover secondary_button_color_hover
Legal version

The legal_version element is related to our terms of service. Its default value is terms1.

Value Description
terms1 I agree to be legally bound by this document and the HelloSign Terms of Service. Click on 'I Agree' to sign this document.
terms2 By clicking "I Agree" you are legally signing this document and agreeing to the eSignature Terms of Service.
Error types

Validation errors are JSON-encoded and returned as a value on error_msg (for more info on errors, see the errors and warnings guide). An error includes the error type and the invalid element name or names. Here is a list and details of possible error types that can be returned:

Error Description
invalid_element_name Invalid element name.
invalid_legal_version Invalid value passed for legal_version.
invalid_hex_code Invalid hex code.
invalid_contrast_ratio Contrast ratio is less than minimum 2.1.
Example

Here is an example of a white labeled embedded signer page.

Scranton Paper’s Partner Portal is the company’s internal tool for managing Partnerships. Pamela is logged in and is signing a mutual NDA with a new partner, JN Projects. HelloSign’s signing functionality is white labeled and embedded within the portal.

The signer page is embedded within Scranton Paper’s Partner Portal
Click to sign signature box
Choose multiple signature options
The signature is displayed within document
Click the 'I agree' button to confirm signed document
The document is signed and completed
NOTE: White Labeling is also available for non-embedded.