Signature RequestContains information regarding documents that need to be signedContains information regarding documents that need to be signed
SignatureRequest Response Object.
test_mode Whether this is a test signature request. Test requests have no legal value. Defaults to 0.
signature_request_id The id of the SignatureRequest.
requester_email_address The email address of the initiator of the SignatureRequest.
title The title the specified Account uses for the SignatureRequest.
subject The subject in the email that was initially sent to the signers.
message The custom message in the email that was initially sent to the signers.
is_complete Whether or not the SignatureRequest has been fully executed by all signers.
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.
ACTION URI - Description
Send Embedded Signature Request with Template
POST /signature_request/create_embedded_with_template
Creates and sends a new SignatureRequest based off of a 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.

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 of the app you're using to create this embedded signature request. Visit our embedded page to learn more about this parameter.
template_id or template_ids[%i%]
Use template_id to create a SignatureRequest from a single Template. Use template_ids[%i%] to create a SignatureRequest from multiple templates, where %i% is an integer indicating the order in which the template will be used. Only template_id or template_ids[%i%] can be used, not both.
title optional
The title you want to assign to the SignatureRequest.
subject optional
The subject in the email that will be sent to the signers.
message optional
The custom message in the email that will be sent to the signers.
The name of the signer filling the role of RoleName. RoleName is case-sensitive.
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.
The email address of the CC filling the role of RoleName. Required when a CC role exists for the Template.
custom_fields optional
A JSON array defining values and options for custom fields. Required when a custom field exists in the Template.
  • name: the name, or "Field Label," of the custom field (the field's API ID can be used here as well)
  • value: the value of the custom field
  • editor: the RoleName allowed to edit the custom field (optional, but required if 'required' is defined)
    Note: Editable custom_fields are only supported for single signer requests. If more than one signer is assigned to the request any editor value is ignored and the field will not be editable.
  • required: a boolean describing if this field is required (default: false)
The value that will be used to populate the Custom Field with the name of CustomFieldName. The CustomFieldName is the case-sensitive "Field Label" assigned to the field when creating the template. The field's API ID can be used here as well. If the custom field is a checkbox, the value "true" indicates that it is checked by default.
metadata[%key%] optional
Key-value data that should be attached to the signature request. This metadata is included in all API responses and events involving the signature request. For example, use the metadata field to store a signer's order number for look up when receiving events for the signature request.

Each request can include up to 10 metadata keys, with key names up to 40 characters long and values up to 1000 characters long.
file[] or file_url[] optional
Append additional files to the signature request. HelloSign will parse the files for text tags. Text tags for signers not on the template will be ignored.

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

If signing_options are not defined in the request, the allowed types will default to those specified in the account settings.
Returns a SignatureRequest object
Example request / response
POST https://[api key]
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] =
ccs[Accounting][email_address] =
custom_fields = [{"name":"Cost", "value":"$20,000", "editor":"Client", "required":true}]
signing_options = {"draw": true, "type": true, "upload": true, "phone": false, "default": "draw"}