Integrate the HelloSign API into your website to start accepting eSignatures quickly.

API Reference

Objects and Methods

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.

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

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

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

Description

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

NOTE This method is restricted to paid API users.

Request Parameters

email_address

Email address to run the verification for.

Response

Returns an Account object

Example requests / responses

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

email_address = some_user@hellosign.com

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

email_address = not_a_user@hellosign.com

SignatureRequest Response Object.

test_mode Whether this is a test signature request. Test requests have no legal value. Defaults to 0.

signature_request_id The id of the SignatureRequest.

requester_email_address The email address of the initiator of the SignatureRequest.

title The title the specified Account uses for the SignatureRequest.

subject The subject in the email that was initially sent to the signers.

message The custom message in the email that was initially sent to the signers.

is_complete Whether or not the SignatureRequest has been fully executed by all signers.

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.

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.

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.

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]

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

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%][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[1][group]=Authorized signatory
signers[1][1][name]=Jack
signers[1][1][email_address]=jack@example.com
signers[1][2][name]=Jill
signers[1][2][email_address]=jill@example.com
signers[1][3][name]=John
signers[1][3][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 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)
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) signer index identified by the offset %i% in the signers[%i%] parameter, indicating which signer should fill out the field

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
        }
    ],
    []
]

Response

Returns a SignatureRequest object

Example request / response

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

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

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

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%][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][1][name]=Jack
signers[HR][1][email_address]=jack@example.com
signers[HR][2][name]=Jill
signers[HR][2][email_address]=jill@example.com
signers[HR][3][name]=John
signers[HR][3][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)
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

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.

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}]

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%]

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)
*_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)

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)
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

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

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.

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

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.

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]

Description

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

Signers will no longer be able to sign and the request will be canceled. 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.

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.

It is recommended that a callback handler be implemented to listen for the "signature_request_canceled" event. This notification will be sent 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.

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]

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]

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)

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 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]

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]

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[]

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.

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 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)
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

metadata[%key%] optional

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

[
    [
        {
            "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
        }
    ],
    []
]

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

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

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%]

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.

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)
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

file[] or file_url[] optional

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}]

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).

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]

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

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

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

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.

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 containing the name and type of each custom field.

name The name of the Custom Field.

type The type of this Custom Field. Only 'text' and 'checkbox' are currently supported.

named_form_fields DEPRECATED Use "form_fields" under the "documents" array instead.

accounts An array of the Accounts that can use this Template.

account_id The id of the Account.

email_address The email address associated with the Account.

is_creator True if you are the owner of this template, false if it's been shared with you by a team member.

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.

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]

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

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

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

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

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.

Response

Returns a Template object

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"}]

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

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)

Response

Returns a PDF or ZIP file, or if get_url is set, a JSON object with a url to the file (PDFs only).

Example request / response

GET https://[api key]:@api.hellosign.com/v3/template/files/[:template_id]

Description

Overlays a new file with the overlay of an existing template. The new file(s) must have the same page count and 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]

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.

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]

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

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.

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

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

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

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

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

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

The email address of an Account on this Team to receive all documents, API apps (if applicable), and API key (if applicable) from 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

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.

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.

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[]

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.

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 index of the signer(%i) allowed to edit the custom field (optional, but required if 'required' is defined)
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

metadata[%key%] optional

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

[
    [
        {
            "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
        }
    ],
    []
]

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

Description

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

Request Parameters

test_mode optional

Whether this is a test, the signature request created from this draft will not be legally binding if set to 1. Defaults to 0.

client_id

Client id of the app you're using to create this draft. Visit our embedded page to learn more about this parameter.

file[] or file_url[]

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 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 index of the signer(%i%) allowed to edit the custom field (optional, but required if 'required' is defined)
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

use_text_tags or use_preexisting_fields optional

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

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

[
    [
        {
            "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
        }
    ],
    []
]

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

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 that embedded unclaimed drafts can only be accessed in embedded iFrames whereas normal drafts can be used and accessed on HelloSign.

Request Parameters

test_mode optional

Whether this is a test, the signature request created from this draft will not be legally binding if set to 1. Defaults to 0.

client_id

Client id of the app you're using to create this draft. Visit our embedded page to learn more about this parameter.

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

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)
required: a boolean describing if this field is required (default: false).

custom_fields[%CustomFieldName%] optional

DEPRECATED

file[] or file_url[] optional

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.

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"}]

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 that 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."

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

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.

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]

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

skip_subject_message optional

If the subject and message has already been provided, the user will not be prompted to edit them

Response

Returns an Embedded object

Example request / response

GET or POST https://[api key]:@api.hellosign.com/v3/embedded/edit_url/[:template_id]

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.

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

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]

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

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"}

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"}

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]

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
initials	An input field for initials
signature	A signature input field
text-merge	A text field that has default text set by the api, that is editable by a signer

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.

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
file_error	We're unable to convert the file you provided.	SignatureRequest	App & account callbacks
unknown_error	An unknown error occurred during while processing a signature request.	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	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

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

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.
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.

Searches can include queries on specific fields when hitting the "/v3/signature_request/list" or "/v3/template/list" endpoints.

NOTE: There may be a minor delay after creation of a signature request or template, and querying may not be immediately available for this object.

Here is an example of a GET request to "/v3/signature_request/list" using search queries:

curl 'https://api.hellosign.com/v3/signature_request/list?query=title:Field+Trip+Release+AND+from:me'\
	-u 'SIGN_IN_AND_CONFIRM_EMAIL_TO_SEE_YOUR_API_KEY_HERE:'

Search fields

Search terms that are not passed with a specific field will be matched against: to, from, title, subject, message, metadata, and filename. Queries on fields can be combined using AND and OR operators (operators are case sensitive). Dates may be passed in as ranges. Exclusive ranges are indicated with curly brackets {min TO max} and inclusive ranges with square brackets [min TO max]. Leading wildcards (*) are not valid queries. The table below lists all possible fields that can be queried.

Field Name	Description	Attached Model	Type
to	The email address or name of the signer (can use "me" to refer to yourself)	SignatureRequest only	String
from	The email address or name of the sender (can use "me" to refer to yourself)	SignatureRequest only	String
title	The title of the signature request or template	SignatureRequest & Template	String
subject	The subject of the email that is sent to the signers	SignatureRequest only	String
message	The message of the email that is sent to the signers	SignatureRequest & Template	String
metadata	The metadata attached to the signature request or template	SignatureRequest & Template	String
created	The creation date (and optional time) of the signature request or template For example: created:{2014-01-01+TO+2014-12-31}	SignatureRequest & Template	Date
complete	true returns a list of signature requests that all signers have signed. For example: complete:true	SignatureRequest only	Boolean
declined	true returns a list of signature requests that have been declined. For example: declined:true	SignatureRequest only	Boolean
awaiting_my_signature	A true value indicates the request requires your signature	SignatureRequest only	Boolean
test_mode	A true value indicates the signature request or template is a test and not legally binding	SignatureRequest & Template	Boolean
filename	The name of the file used to create the signature request or template	SignatureRequest & Template	String
owner	The email address or name of the template owner (can use "me" to refer to yourself)	Template only	String
template	A Template ID corresponding to a template used in a signature request.	SignatureRequest only	String

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 a Sapphire API 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 Sapphire API plan are immediately active in production. We recommend creating a test app for previewing white labeling changes.

White labeling is available exclusively on the new signer interface. For users with older accounts, please see the embedded signing walkthrough for more info on setting the uxVersion.

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	Almost done. By clicking "I Agree" you are legally signing this document and agreeing to be legally bound to the HelloSign Terms of Service.
terms2	Almost done. 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.

HelloSign

API

Products

The Fine Print

Trending Topics