Signature Request - Create Embedded | HelloSign API Documentation
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.
created_at Time the signature request was created.
is_complete Whether or not the SignatureRequest has been fully executed by all signers.
is_declined Whether or not the SignatureRequest has been declined by a signer.
has_error Whether or not an error occurred (either during the creation of the SignatureRequest or during one of the signings).
final_copy_uri (Deprecated) The relative URI where the PDF copy of the finalized documents can be downloaded. Only present when is_complete = true. This will be removed at some point; use the files_url instead.
files_url The URL where a copy of the request's documents can be downloaded.
signing_url The URL where a signer, after authenticating, can sign the documents. This should only be used by users with existing HelloSign accounts as they will be required to log in before signing.
details_url The URL where the requester and the signers can view the current status of the SignatureRequest.
cc_email_addresses A list of email addresses that were CCed on the SignatureRequest. They will receive a copy of the final PDF once all the signers have signed.
signing_redirect_url The URL you want the signer redirected to after they successfully sign.
custom_fields An array of Custom Field objects containing the name and type of each custom field.
name The name of the Custom Field.
type The type of this Custom Field. Only 'text' and 'checkbox' are currently supported.
value A text string for text fields or true/false for checkbox fields
required A boolean value denoting if this field is required.
editor The name of the Role that is able to edit this field.
response_data An array of form field objects containing the name, value, and type of each textbox or checkmark field filled in by the signers.
api_id The unique ID for this field.
signature_id The ID of the signature to which this response is linked.
name The name of the form field.
value The value of the form field.
required A boolean value denoting if this field is required.
type The type of this form field. See field types
signatures An array of signature obects, 1 for each signer.
signature_id Signature identifier.
signer_email_address The email address of the signer.
signer_name The name of the signer.
signer_role The role of the signer.
order If signer order is assigned this is the 0-based index for this signer.
status_code The current status of the signature. eg: awaiting_signature, signed, declined
decline_reason The reason provided by the signer for declining the request.
signed_at Time that the document was signed or null.
last_viewed_at The time that the document was last viewed by this signer or null.
last_reminded_at The time the last reminder email was sent to the signer or null.
has_pin Boolean to indicate whether this signature requires a PIN to access.
reassigned_by Email address of original signer who reassigned to this signer, or null.
reassignment_reason Reason provided by original signer who reassigned to this signer, or null.
error Error message pertaining to this signer, or null.
ACTION URI - Description
Send Embedded Signature Request
POST /signature_request/create_embedded
Creates a new SignatureRequest to be signed in an embedded window.

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 of the app you're using to create this embedded signature request. Visit our embedded page to learn more about this parameter.
file[] or file_url[]
Use file[] to indicate the uploaded file(s) to send for signature. Use file_url[] to have HelloSign download the file(s) to send for signature. Currently we only support use of either the file[] parameter or file_url[] parameter, not both.
title optional
The title you want to assign to the SignatureRequest.
subject optional
The subject in the email that will be sent to the signers.
message optional
The custom message in the email that will be sent to the signers.
The name of the signer. %i% is an integer that should be unique for each signer.
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 defining pre-set values in form_fields_per_document or Text Tags.
  • name: the name, or "Field Label," of the custom field (the field's API ID can be used here as well)
  • value: the value of the custom field
  • editor: the RoleName allowed to edit the custom field (optional, but required if 'required' is defined)
    Note: Editable custom_fields are only supported for single signer requests or the first signer of ordered signature requests. If more than one signer is assigned to the unordered signature request, any editor value is ignored and the field will not be editable.
  • required: a boolean describing if this field is required (default: false)
cc_email_addresses[] optional
The email addresses that should be CCed.
use_text_tags optional
[boolean] Send with a value of 1 if you wish to enable Text Tags parsing in your document. Defaults to 0.
hide_text_tags optional
[boolean] Send with a value of 1 if you wish to enable automatic Text Tag removal. Defaults to 0. When using Text Tags it is preferred that you set this to 0 and hide your tags with white text or something similar because the automatic removal system can cause unwanted clipping. See the Text Tags walkthrough for more details.
metadata[%key%] optional
Key-value data that should be attached to the signature request. This metadata is included in all API responses and events involving the signature request. For example, use the metadata field to store a signer's order number for look up when receiving events for the signature request.

Each request can include up to 10 metadata keys, with key names up to 40 characters long and values up to 1000 characters long.
allow_decline optional
Allows signers to decline to sign a document if set to 1. Defaults to 0.
allow_reassign optional
Allows signers to reassign their signature requests to other signers if set to 1. Defaults to 0.
Note: Only available for Gold plan and higher.
form_fields_per_document optional
The fields that should appear on the document, expressed as a 2-dimensional JSON array serialized to a string. The main array represents documents, with each containing an array of form fields. One document array is required for each file provided by the file[] parameter. In the case of a file with no fields, an empty list must be specified.

Each field must contain:
    1. api_id - (string) an identifier for the field that is unique across all documents in the request
    2. type - one of the Type options
    3. x & y - (int) location coordinates of the field in pixels
    4. page - (int) page in the document where the field should be placed (requires documents be PDF files)
        a. When the page number parameter is supplied, the API will use the new coordinate system.
        b. Check out the differences between both coordinate systems and how to use them.
    5. width & height - (int) size of the field in pixels
    6. required - (boolean) whether this field is required
    7. signer - (int | string) signer index identified by the offset %i% in the signers[%i%] parameter, indicating which signer should fill out the field. If your type is 'text-merge' you can set this to 'sender', so the field is non-editable by any signer.

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

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

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

            "api_id": "uniqueIdHere_1",
            "name": "",
            "type": "text",
            "x": 112,
            "y": 328,
            "width": 100,
            "height": 16,
            "required": true,
            "signer": 1,
            "page": 1,
            "validation_type": "numbers_only"
            "api_id": "uniqueIdHere_2",
            "name": "",
            "type": "signature",
            "x": 530,
            "y": 415,
            "width": 120,
            "height": 30,
            "required": true,
            "signer": 0,
            "page": 1
signing_options optional
This allows the requester to specify the types allowed for creating a signature.
  • draw: [boolean] allows drawing the signature (default: false)
  • type: [boolean] allows typing the signature (default: false)
  • upload: [boolean] allows uploading the signature (default: false)
  • phone: [boolean] allows using a smartphone to email the signature (default: false)
  • default: [string] the default type shown (limited to the above types) (required if signing_options defined)

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

Returns a SignatureRequest object
Example request / response
POST https://[api key]
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] =
signers[0][name] = Jack
signers[0][order] = 0
signers[1][email_address] =
signers[1][name] = Jill
signers[1][order] = 1
cc_email_addresses[0] =
cc_email_addresses[1] =
file[0] = @NDA.pdf
file[1] = @AppendixA.pdf
signing_options = {"draw": true, "type": true, "upload": true, "phone": false, "default": "draw"}