Returns the properties and settings of your Account
Updates the properties and settings of your Account.
Creates a new HelloSign Account that is associated with the specified email_address.
Verifies whether an HelloSign Account exists for the given email address.
NOTE This method is restricted to paid API users.
Returns the status of the SignatureRequest specified by the signature_request_id parameter.
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.
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.
signers[0][group]=Authorized signatory signers[0][0][name]=Jack signers[0][0][email_address]=jack@example.com signers[0][1][name]=Jill signers[0][1][email_address]=jill@example.com signers[0][2][name]=John signers[0][2][email_address]=john@example.com
[ [ { "api_id": "uniqueIdHere_1", "name": "", "placeholder": "", "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 } ] ]
{ "<group ID>": { "group_label": string, "requirement": string } }
"form_fields_per_document": [ [ { "api_id": "uniqueIdHere_1", "name": "", "type": "radio", "x": 112, "y": 328, "width": 18, "height": 18, "required": false, "group": "RadioItemGroup1", "checked": 1, "signer": 0, "page": 1 }, { "api_id": "uniqueIdHere_2", "name": "", "type": "radio", "x": 112, "y": 370, "width": 18, "height": 18, "required": false, "group": "RadioItemGroup1", "checked": 0, "signer": 0, "page": 1 } ] ], "form_field_groups": { "RadioItemGroup1": { "group_label": "Radio Item Group 1", "requirement": "require_0-1" } }
{ { "id": string, "trigger_operator": "AND", "triggers": [ { "id": string, "operator": string, "value": string|string[]|int } ], "actions": [ { "field_id" | "group_id": string, "hidden": 0 | 1, "type": "change-field-visibility" | "change-group-visibility" } ] } }
"form_fields_per_document": [ [ { "api_id": "uniqueIdHere_1", "name": "", "type": "text", "x": 112, "y": 328, "width": 100, "height": 16, "required": true, "signer": 0, "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 } ] ], "form_field_rules": [ { "id": "rule_1", "trigger_operator": "AND", "triggers": [ { "id": "uniqueIdHere_1", "operator": "is", "value": "foo" } ], "actions": [ { "field_id": "uniqueIdHere_2", "hidden": 1, "type": "change-field-visibility" } ] } ]
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.
Creates and sends a new SignatureRequest based off of the Template specified with the template_id parameter.
signers[HR][group]=Authorized signatory signers[HR][0][name]=Jack signers[HR][0][email_address]=jack@example.com signers[HR][1][name]=Jill signers[HR][1][email_address]=jill@example.com signers[HR][2][name]=John signers[HR][2][email_address]=john@example.com
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 Standard plan and higher.
[ { "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" } } ]
Sends an email to the signer reminding them to sign the signature request. You cannot send a reminder within 1 hour of the last reminder that was sent. This includes manual AND automatic reminders.
NOTE: This action can not be used with embedded signature requests.
Updates the email address and/or the name for a given signer on a signature request. You can listen for the "signature_request_email_bounce" event on your app or account to detect bounced emails, and respond with this method.
NOTE: This action cannot be performed on a signature request with an appended signature page.
Cancels an incomplete signature request. This action is not reversible.
The request will be canceled and signers will no longer be able to sign. If they try to access the signature request
they will receive a HTTP 410 status code indicating that the resource has been deleted. Cancelation is asynchronous
and a successful call to this endpoint will return an empty 200 OK response if the signature request
is eligible to be canceled and has been successfully queued.
This 200 OK response does not indicate a successful cancelation of the signature request itself. The cancelation is
confirmed via the "signature_request_canceled" event. It is recommended that a callback handler be implemented to
listen for the "signature_request_canceled" event. This callback will be sent only when the cancelation has completed
successfully. If a callback handler has been configured and the event has not been received within 60 minutes of making the call,
check the status of the request in the API Dashboard and retry the cancelation if necessary.
To be eligible for cancelation, a signature request must have been sent successfully, must not yet
have been signed by all signers, and you must either be the sender or own the API app
under which it was sent. A partially signed signature request can be canceled.
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.
Obtain a copy of the current documents specified by the signature_request_id parameter.
Download the PDF copy of the finalized documents specified by the signature_request_id parameter. Deprecated, use GET /signature_request/files/[:signature_request_id].
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.
[ [ { "api_id": "uniqueIdHere_1", "name": "", "placeholder": "", "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 } ], [] ]
{ "<group ID>": { "group_label": string, "requirement": string } }
"form_fields_per_document": [ [ { "api_id": "uniqueIdHere_1", "name": "", "type": "radio", "x": 112, "y": 328, "width": 18, "height": 18, "required": false, "group": "RadioItemGroup1", "checked": 1, "signer": 0, "page": 1 }, { "api_id": "uniqueIdHere_2", "name": "", "type": "radio", "x": 112, "y": 370, "width": 18, "height": 18, "required": false, "group": "RadioItemGroup1", "checked": 0, "signer": 0, "page": 1 } ] ], "form_field_groups": { "RadioItemGroup1": { "group_label": "Radio Item Group 1", "requirement": "require_0-1" } }
{ { "id": string, "trigger_operator": "AND", "triggers": [ { "id": string, "operator": string, "value": string|string[]|int } ], "actions": [ { "field_id" | "group_id": string, "hidden": 0 | 1, "type": "change-field-visibility" | "change-group-visibility" } ] } }
"form_fields_per_document": [ [ { "api_id": "uniqueIdHere_1", "name": "", "type": "text", "x": 112, "y": 328, "width": 100, "height": 16, "required": true, "signer": 0, "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 } ] ], "form_field_rules": [ { "id": "rule_1", "trigger_operator": "AND", "triggers": [ { "id": "uniqueIdHere_1", "operator": "is", "value": "foo" } ], "actions": [ { "field_id": "uniqueIdHere_2", "hidden": 1, "type": "change-field-visibility" } ] } ]
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.
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.
Creates BulkSendJob which sends up to 250 SignatureRequests in bulk based off of the Template specified with the template_id parameter to be signed in an embedded iFrame. These embedded signature requests can only be signed in embedded iFrames whereas normal signature requests can only be signed on HelloSign.
NOTE: Only available for Standard plan and higher.
[ { "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" } } ]
Releases a held SignatureRequest that was claimed and prepared from an UnclaimedDraft. The owner of the Draft must indicate at Draft creation that the SignatureRequest created from the Draft should be held. Releasing the SignatureRequest will send requests to all signers.
Returns the ReusableForm specified by the id parameter. Deprecated, use GET /template/[:template_id].
Returns a list the ReusableForms that are accessible by you. Deprecated, use GET /template/list.
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].
Removes the specified Account's access to the specified ReusableForm. Deprecated, use POST /template/remove_user/[:template_id].
Returns the Template specified by the id parameter.
Returns a list of the Templates that are accessible by you.Take a look at our search guide to learn more about querying templates.
Gives the specified Account access to the specified Template. The specified Account must be a part of your Team.
Removes the specified Account's access to the specified Template.
The first step in an embedded template workflow. Creates a draft template that can then be further set up in the template 'edit' stage.
[ [ { "api_id": "uniqueIdHere_1", "name": "", "placeholder": "", "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 } ] ]
{ "<group ID>": { "group_label": string, "requirement": string } }
"form_fields_per_document": [ [ { "api_id": "uniqueIdHere_1", "name": "", "type": "radio", "x": 112, "y": 328, "width": 18, "height": 18, "required": false, "group": "RadioItemGroup1", "checked": 1, "signer": 0, "page": 1 }, { "api_id": "uniqueIdHere_2", "name": "", "type": "radio", "x": 112, "y": 370, "width": 18, "height": 18, "required": false, "group": "RadioItemGroup1", "checked": 0, "signer": 0, "page": 1 } ] ], "form_field_groups": { "RadioItemGroup1": { "group_label": "Radio Item Group 1", "requirement": "require_0-1" } }
{ { "id": string, "trigger_operator": "AND", "triggers": [ { "id": string, "operator": string, "value": string|string[]|int } ], "actions": [ { "field_id" | "group_id": string, "hidden": 0 | 1, "type": "change-field-visibility" | "change-group-visibility" } ] } }
"form_fields_per_document": [ [ { "api_id": "uniqueIdHere_1", "name": "", "type": "text", "x": 112, "y": 328, "width": 100, "height": 16, "required": true, "signer": 0, "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 } ] ], "form_field_rules": [ { "id": "rule_1", "trigger_operator": "AND", "triggers": [ { "id": "uniqueIdHere_1", "operator": "is", "value": "foo" } ], "actions": [ { "field_id": "uniqueIdHere_2", "hidden": 1, "type": "change-field-visibility" } ] } ]
Completely deletes the template specified from the account.
Obtain a copy of the original files specified by the template_id parameter.
Overlays a new file with the overlay of an existing template. The new file(s) must:
1) have the same or higher page count
2) the same orientation as the file(s) being replaced.
This will not overwrite or in any way affect the existing template. Both the existing
template and new template will be available for use after executing this
endpoint. Also note that this will decrement your template quota.
Overlaying new files is asynchronous and a successful call to this endpoint
will return an empty 200 OK response if the request passes initial validation checks.
It is recommended that a callback be implemented to listen for the
callback event. A "template_created" event will be sent when the files are updated or a "template_error"
event will be sent if there was a problem while updating the files. If a callback
handler has been configured and the event has not been received within 60 minutes of making the call,
check the status of the request in the API dashboard and retry the request if necessary.
If the page orientation or page count is different from the original template document,
we will notify you with a "template_error" callback event.
Returns the status of the BulkSendJob and its SignatureRequests specified by the bulk_send_job_id parameter.
Returns a list of BulkSendJob that you can access.
Request the creation of one or more report(s).
When the report(s) have been generated, you will receive an email (one per requested report type) containing a link to download the report as a CSV file.
The requested date range may be up to 12 months in duration, and start_date must not be more than 10 years in the past.
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.
Creates a new Team and makes you a member. You must not currently belong to a Team to invoke.
Updates the name of your Team.
Deletes your Team. Can only be invoked when you have a Team with only one member (yourself).
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.
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.
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.
[ [ { "api_id": "uniqueIdHere_1", "name": "", "placeholder": "", "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 } ], [] ]
{ "<group ID>": { "group_label": string, "requirement": string } }
"form_fields_per_document": [ [ { "api_id": "uniqueIdHere_1", "name": "", "type": "radio", "x": 112, "y": 328, "width": 18, "height": 18, "required": false, "group": "RadioItemGroup1", "checked": 1, "signer": 0, "page": 1 }, { "api_id": "uniqueIdHere_2", "name": "", "type": "radio", "x": 112, "y": 370, "width": 18, "height": 18, "required": false, "group": "RadioItemGroup1", "checked": 0, "signer": 0, "page": 1 } ] ], "form_field_groups": { "RadioItemGroup1": { "group_label": "Radio Item Group 1", "requirement": "require_0-1" } }
{ { "id": string, "trigger_operator": "AND", "triggers": [ { "id": string, "operator": string, "value": string|string[]|int } ], "actions": [ { "field_id" | "group_id": string, "hidden": 0 | 1, "type": "change-field-visibility" | "change-group-visibility" } ] } }
"form_fields_per_document": [ [ { "api_id": "uniqueIdHere_1", "name": "", "type": "text", "x": 112, "y": 328, "width": 100, "height": 16, "required": true, "signer": 0, "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 } ] ], "form_field_rules": [ { "id": "rule_1", "trigger_operator": "AND", "triggers": [ { "id": "uniqueIdHere_1", "operator": "is", "value": "foo" } ], "actions": [ { "field_id": "uniqueIdHere_2", "hidden": 1, "type": "change-field-visibility" } ] } ]
Creates a new Draft that can be claimed and used in an embedded iFrame. The first authenticated user to access the URL will claim the Draft and will be shown the "Request signature" page with the Draft loaded. Subsequent access to the claim URL will result in a 404. For this embedded endpoint the requester_email_address parameter is required.
NOTE: Embedded unclaimed drafts can only be accessed in embedded iFrames whereas normal drafts can be used and accessed on HelloSign.
[ [ { "api_id": "uniqueIdHere_1", "name": "", "placeholder": "", "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 } ], [] ]
{ "<group ID>": { "group_label": string, "requirement": string } }
"form_fields_per_document": [ [ { "api_id": "uniqueIdHere_1", "name": "", "type": "radio", "x": 112, "y": 328, "width": 18, "height": 18, "required": false, "group": "RadioItemGroup1", "checked": 1, "signer": 0, "page": 1 }, { "api_id": "uniqueIdHere_2", "name": "", "type": "radio", "x": 112, "y": 370, "width": 18, "height": 18, "required": false, "group": "RadioItemGroup1", "checked": 0, "signer": 0, "page": 1 } ] ], "form_field_groups": { "RadioItemGroup1": { "group_label": "Radio Item Group 1", "requirement": "require_0-1" } }
{ { "id": string, "trigger_operator": "AND", "triggers": [ { "id": string, "operator": string, "value": string|string[]|int } ], "actions": [ { "field_id" | "group_id": string, "hidden": 0 | 1, "type": "change-field-visibility" | "change-group-visibility" } ] } }
"form_fields_per_document": [ [ { "api_id": "uniqueIdHere_1", "name": "", "type": "text", "x": 112, "y": 328, "width": 100, "height": 16, "required": true, "signer": 0, "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 } ] ], "form_field_rules": [ { "id": "rule_1", "trigger_operator": "AND", "triggers": [ { "id": "uniqueIdHere_1", "operator": "is", "value": "foo" } ], "actions": [ { "field_id": "uniqueIdHere_2", "hidden": 1, "type": "change-field-visibility" } ] } ]
Creates a new Draft with a previously saved template that can be claimed and used in an embedded iFrame. The first authenticated user to access the URL will claim the Draft and will be shown the "Request signature" page with the Draft loaded. Subsequent access to the claim URL will result in a 404. For this embedded endpoint the requester_email_address parameter is required.
NOTE: Embedded unclaimed drafts can only be accessed in embedded iFrames whereas normal drafts can be used and accessed on HelloSign.
Creates a new signature request from an embedded request that can be edited prior to being sent to the recipients. Param, test_mode, can be edited prior to request. Signers can be edited in embedded editor. Requester's email address will remain unchanged if requester_email_address parameter is not set.
NOTE: Embedded unclaimed drafts can only be accessed in embedded iFrames whereas normal drafts can be used and accessed on HelloSign.
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.
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.
Note: For agreements with a large number of merge fields that need to be sent, please use POST request.
This is to ensure you don't surpass the GET request limit of URL length of 2048
Returns an object with information about an API App.
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.
Creates a new API App.
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.
Events will be POSTed to your callback URLs. There are two kinds of callbacks that can be defined:
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.
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.
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.
If an error or warning occurs, we'll return either an error or warning object in the JSON response.
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" } }
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" } ] }
These are the options you can specify for the "type" field.
Type | Description |
---|---|
text | A text input field |
checkbox | A yes/no checkbox |
date_signed | A date |
dropdown | An input field for dropdowns |
initials | An input field for initials |
radio | An input field for radios |
signature | A signature input field |
text-merge | A text field that has default text set by the api |
checkbox-merge | A checkbox field that has default value set by the api |
Different field types may have different options available to them within the form_fields_per_document parameter.
Field Type | Description |
---|---|
text |
placeholder: String (optional)
|
dropdown |
options: String[] (required)
|
hyperlink |
content: String (required)
|
checkbox |
group: String (optional)
|
radio |
group: String (required)
|
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 |
Radio field groups must define a 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 | Makes group optional (signer does not have to select any radio option) |
require_1 | Makes group required (signer has to select one radio option) |
Conditional logic allows adding an "if this, then that" flow to signature requests.
Field | Description |
---|---|
id
String |
Unique across all defined rules.
|
trigger_operator
String |
Currently only AND is supported. Support for OR is being
worked on.
|
triggers
Array |
An array of trigger definitions, the "if this" part of "if this, then that".
Currently only a single trigger per rule is allowed.
id: String (required)
|
actions
Array |
An array of action definitions, the "then that" part of "if this, then that".
Any number of actions may be attached to a single rule.
field_id: String (required)
|
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 |
List and details of possible warnings that can be returned.
Warning | Description |
---|---|
unconfirmed | The email address of the account making the Signature Request has not been confirmed. The Signature Request will be placed on hold until it is confirmed. |
custom_field_value_too_long | The value provided for a custom field is too long. The custom field will extend beyond the limits of its container and may not display the way you intended. |
custom_field_values_too_long | A summary of all values for custom fields that are too long |
parameter_ignored | One of the request parameters was ignored because it wasn't being used correctly |
non_pdf_text_tags | Text Tags were enabled for a file that is not a PDF, which may result in imprecise positioning. |
form_fields_overlap | Two or more of the form fields specified are overlapping, which may prevent signers from completing the document. |
form_fields_placement | Form fields must be placed within the document. |
deprecated_parameter | A parameter was provided which we no longer support. The value will be ignored. |
parameter_conflict | Two parameters have been provided which are in conflict. One parameter will be ignored. |
parameter_missing | An essential parameter was missing from the request and has been set to a default value. |
partial_success | The operation succeeded, but at least one non-essential part of the request failed. |
test_mode_only | A parameter was provided which will affect your app in test mode but will not affect it in production. Upgrade your account to use in production. |
empty_value | A non-essential parameter was provided but it does not have a value. The parameter will be ignored. |
add_member | A warning was generated while attempting to add a user to your team. |
parameter_invalid | A parameter was provided with an invalid value. The parameter will be modified or ignored. |
oauth_grants_revoked | OAuth user access grants have been revoked from this app due to a scope change. |
cc_disabled | The option to email a copy to the other signers and anyone CC'd is disabled for given account. |
reassign_unsupported | A template with signer reassignment was used on an endpoint that does not support it (e.g. bulk send with template). The template will still be used, but without signer reassignment enabled. |
duplicate_template_ids | Templates can only be used once in a signature request. A duplicated template ids was passed in the request. |
Here is the list of possible events that can be sent to your callbacks.
Event Type | Description | Attached Model | Reported to |
---|---|---|---|
signature_request_viewed | The SignatureRequest has been viewed. | SignatureRequest | App & account callbacks |
signature_request_signed | A signer has completed all required fields on the SignatureRequest. | SignatureRequest | App & account callbacks |
signature_request_downloadable | An updated version of the SignatureRequest PDF is available for download. | SignatureRequest | App & account callbacks |
signature_request_sent | The SignatureRequest has been sent successfully. | SignatureRequest | App & account callbacks |
signature_request_declined | The SignatureRequest was declined by a signer. | SignatureRequest | App & account callbacks |
signature_request_reassigned | The signer has reassigned their signature to a different signer. | SignatureRequest | App & account callbacks |
signature_request_remind | All signers have been sent a reminder to complete the SignatureRequest. | SignatureRequest | App & account callbacks |
signature_request_all_signed | All signers have completed all required fields for the SignatureRequest and the final PDF is ready to be downloaded using signature_request/files. | SignatureRequest | App & account callbacks |
signature_request_email_bounce | An email address for one of the signers on your signature request has bounced. May be correctable by using signature_request/update. | SignatureRequest | App & account callbacks |
signature_request_invalid | An error occurred while processing the signature request data on our back-end. For example: Invalid text tags or email address is not correct when using signature page |
SignatureRequest | App & account callbacks |
signature_request_canceled | The SignatureRequest has been canceled. | SignatureRequest | App & account callbacks |
signature_request_prepared | The SignatureRequest has been prepared but not sent. | SignatureRequest | App & account callbacks |
file_error | We're unable to convert the file you provided. | SignatureRequest | App & account callbacks |
unknown_error | An unknown error occurred while processing a signature request. | SignatureRequest | App & account callbacks |
sign_url_invalid | The embedded sign URL you provided is invalid or expired. | SignatureRequest | App & account callbacks |
account_confirmed | An account created via one of your apps has been confirmed. | Account | App callbacks only |
template_created | The Template has been created. | Template | App & account callbacks |
template_error | There was an error while creating your template. | Template | App & account callbacks |
For more info on handling callback events, see the events and callbacks walkthrough.
Callback events come along with a SignatureRequest object, under which you can find the list of associated Signatures. Each of these Signature object has a status_code field that describes its current state. The table below lists all possible codes.
Status | Description | Attached Model |
---|---|---|
success | Success | SignatureRequest |
on_hold | On hold. This could be because the sending account needs to confirm its email address, or because of insufficient funds. | SignatureRequest |
signed | Signed | SignatureRequest |
awaiting_signature | Awaiting signature | SignatureRequest |
declined | Declined | SignatureRequest |
error_unknown | Unknown error | SignatureRequest |
error_file | File could not be converted | SignatureRequest |
error_component_position | Invalid form fields placement | SignatureRequest |
error_text_tag | File contained invalid text tags | SignatureRequest |
on_hold_by_requester | Request was prepared for signature but has not been sent to signers. Requester must release the request from hold when ready to send. | SignatureRequest |
error_invalid_email | Invalid email | SignatureRequest |
Text fields accept an optional validation type, which must be met before the user can submit the signed document. This value can be specified in form fields, text tags, or on the web. These are the options you can specify for validation type.
Type | Description |
---|---|
numbers_only | Numbers only (negative and decimal values included) |
letters_only | Letters only (non-English letters included) |
phone_number | 10- or 11-digit number |
bank_routing_number | 9-digit number |
bank_account_number | Minimum 6-digit number |
email_address | Email address |
zip_code | 5- or 9-digit number |
social_security_number | 9-digit number |
employer_identification_number | 9-digit number |
custom_regex | Custom regular expression (See note below) |
"validation_type": "custom_regex", "validation_custom_regex": "A[0-9]{3}", "validation_custom_regex_format_label": "A000",
Text fields accept an optional auto fill type. This value can be specified in form fields, text tags, or on the web. Below are the options you can specify for auto fill type.
Type | Description |
---|---|
firstName |
Text Tag example: [text|req|signer1|Label|UniqueId|letters_only|firstName] Form field per document example:
[
[
{
"api_id": "field1",
"placeholder": "First Name",
"auto_fill_type": "firstName",
"name": "firstname",
"type": "text",
"x": 160,
"y": 80,
"page": 1,
"width": 206,
"height": 32,
"required": true,
"signer": 0
}
]
]
|
lastName |
Text Tag example: [text|req|signer1|Label|UniqueId|letters_only|lastName] Form field per document example:
[
[
{
"api_id": "field1",
"placeholder": "Last Name",
"auto_fill_type": "lastName",
"name": "lastName",
"type": "text",
"x": 160,
"y": 80,
"page": 1,
"width": 206,
"height": 32,
"required": true,
"signer": 0
}
]
]
|
name | This is full name. Text Tag example: [text|req|signer1|Label|UniqueId|letters_only|name] Form field per document example:
[
[
{
"api_id": "field1",
"placeholder": "Full Name",
"auto_fill_type": "name",
"name": "fullname",
"type": "text",
"x": 160,
"y": 80,
"page": 1,
"width": 206,
"height": 32,
"required": true,
"signer": 0
}
]
]
|
Text Tag example: [text|req|signer1|Label|UniqueId|email_address|email] Form field per document example:
[
[
{
"api_id": "field1",
"placeholder": "email",
"auto_fill_type": "email",
"name": "email",
"type": "text",
"x": 160,
"y": 80,
"page": 1,
"width": 206,
"height": 32,
"required": true,
"signer": 0
}
]
]
|
|
company |
Text Tag example: [text|req|signer1|Label|UniqueId|letters_only|company] Form field per document example:
[
[
{
"api_id": "field1",
"placeholder": "company",
"auto_fill_type": "company",
"name": "company",
"type": "text",
"x": 160,
"y": 80,
"page": 1,
"width": 206,
"height": 32,
"required": true,
"signer": 0
}
]
]
|
title |
Text Tag example: [text|req|signer1|Label|UniqueId|letters_only|title] Form field per document example:
[
[
{
"api_id": "field1",
"placeholder": "company",
"auto_fill_type": "company",
"name": "company",
"type": "text",
"x": 160,
"y": 80,
"page": 1,
"width": 206,
"height": 32,
"required": true,
"signer": 0
}
]
]
|
The following values can be specified as part of date_format in field_options.
Format | Example |
---|---|
MM / DD / YYYY | 05 / 18 / 2022 |
MM - DD - YYYY | 05 - 18 - 2022 |
DD / MM / YYYY | 18 / 05 / 2022 |
DD - MM - YYYY | 18 - 05 - 2022 |
YYYY / MM / DD | 2022 / 05 / 18 |
YYYY - MM - DD | 2022 - 05 - 18 |
Name | Value | Description |
---|---|---|
Account Access | account_access | Access to basic account information, such as email address and name. |
Signature Request Access | signature_request_access | Access to send, view, and update signature requests and to download document files. Signature requests must be made with oAuth token in order to access. |
Template Access | template_access | Access to view, create, and modify templates. |
Team Access | team_access | Access to view and modify team settings and team members. |
API App Access | api_app_access | Access to view, create, and modify embedded API apps. |
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.
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_CREATE_API_KEY_FIRST:'
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] Another example: created:{2014-01-05+TO+2014-01-10} |
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 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. White labeling is available as a paid add-on for Premium API plans, which you must have in order 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 who purchase the white labeling add-on for the Premium plan are immediately active in production. We recommend creating a test app for previewing white labeling changes. The white labeling options are passed in the create API app and update API app endpoints.
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 |
The legal_version element is related to our terms of service. Its default value is terms1.
Value | Description |
---|---|
terms1 | I agree to be legally bound by this document and the HelloSign Terms of Service. Click on 'I Agree' to sign this document. |
terms2 | By clicking "I Agree" you are legally signing this document and agreeing to the eSignature Terms of Service. |
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. |
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.