The URL that HelloSign should POST events to.

The email address to create a new Account for.

Email address to run the verification for.

The id of the SignatureRequest to retrieve.

Which account to return SignatureRequests for. Must be a team member. Use "all" to indicate all team members. Defaults to your account.

Which page number of the SignatureRequest List to return. Defaults to 1.

Number of objects to be returned per page. Must be between 1 and 100. Default is 20.

String that includes search terms and/or fields to be used to filter the SignatureRequest objects.

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

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.

The title you want to assign to the SignatureRequest.

The subject in the email that will be sent to the signers.

The custom message in the email that will be sent to the signers.

The URL you want the signer redirected to after they successfully sign.

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.

The order the signer is required to sign in. %i% is an integer that should be unique for each signer.

The 4- to 12-character access code that will secure this signer's signature page.

An E.164 formatted phone number that will receive a code via SMS to access this signer's signature page.
Note: Not available in test mode and requires a Standard plan or higher.

To send to a signer group, specify the name of the group and assign the signers that are part of it under the same index. Any of the signers is eligible to sign for the entire group.
The following is an example of a signature request sent to a signer group of 3 signers:

signers[0][group]=Authorized signatory
signers[0][0][name]=Jack
signers[0][0][email_address]=jack@example.com
signers[0][1][name]=Jill
signers[0][1][email_address]=jill@example.com
signers[0][2][name]=John
signers[0][2][email_address]=john@example.com

The name of attachment.

The instructions for uploading the attachment.

The signer's unique number, see signers[%i%][name] for more details.

Determines if the attachment must be uploaded.

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 set to 'true')
  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)

The email addresses that should be CCed.

[boolean] Send with a value of 1 if you wish to enable Text Tags parsing in your document. Defaults to 0.

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

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.

The client ID of the ApiApp you want to associate with this request.

Allows signers to decline to sign a document if set to 1. Defaults to 0.

Allows signers to reassign their signature requests to other signers if set to 1. Defaults to 0.
Note: Only available for Premium plan.

[boolean] Send with a value of 'true' if you wish to enable Qualified Electronic Signatures (QES), which requires a face-to-face call to verify the signer's identity. Defaults to 'false'.
Note: QES is only available on the Premium API plan as an add-on purchase. Cannot be used in test_mode. Only works on requests with one signer.

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": "",
            "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 information for fields defined in form_fields_per_document. String-indexed JSON array with group_label and requirement keys. form_fields_per_document must contain fields referencing a group defined in form_field_groups.

The required shape of form_field_groups is

{
  "<group ID>": {
    "group_label": string,
    "requirement": string
  }
}

The following is an example of form_field_groups along with the required form_fields_per_document, prior to serialization to a string for the API request:

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

Conditional Logic rules for fields defined in form_fields_per_document.

• id: [string] must be unique
• trigger_operator: [string] currently only AND is supported
• triggers: [array] for identifying the "when" part of "when x do y"
• actions: [array] for identifying the "do" part of "when x do y"

The required shape of form_field_rules is

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

The following is an example of form_field_rules along with the required form_fields_per_document, prior to serialization to a string for the API request:

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

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.

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 Premium and higher.

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

The id of the ReusableForm to use when creating the SignatureRequest.

The title you want to assign to the SignatureRequest.

The subject in the email that will be sent to the signers.

The custom message in the email that will be sent to the signers.

The URL you want the signer redirected to after they successfully sign.

The name of the signer filling the role of RoleName.

The email address of the signer filling the role of RoleName.

The 4- to 12-character access code that will secure this signer's signature page.

The email address of the CC filling the role of RoleName. Required when a CC role exists for the ReusableForm.

The value to fill in for custom field with the name of CustomFieldName. Required when a CustomField exists in the ReusableForm.

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

Allows signers to decline to sign a document if set to 1. Defaults to 0.

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.

The title you want to assign to the SignatureRequest.

The subject in the email that will be sent to the signers.

The custom message in the email that will be sent to the signers.

The URL you want the signer redirected to after they successfully sign.

[boolean] Send with a value of 'true' if you wish to enable Qualified Electronic Signatures (QES), which requires a face-to-face call to verify the signer's identity. Defaults to 'false'.
Note: QES is only available on the Premium API plan as an add-on purchase. Cannot be used in test_mode. Only works on requests with one signer.

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.

The 4- to 12-character access code that will secure this signer's signature page. RoleName is case-sensitive.

An E.164 formatted phone number that will receive a code via SMS to access this signer's signature page.
Note: Not available in test mode and requires a Standard plan or higher.

To send to a signer group, specify the name of the group and assign the signers that are part of it under the same role. Any of the signers is eligible to sign for the entire group.
The following is an example of a signature request sent to a signer group of 3 signers assigned to the role name "HR":

signers[HR][group]=Authorized signatory
signers[HR][0][name]=Jack
signers[HR][0][email_address]=jack@example.com
signers[HR][1][name]=Jill
signers[HR][1][email_address]=jill@example.com
signers[HR][2][name]=John
signers[HR][2][email_address]=john@example.com

The email address of the CC filling the role of RoleName. Required when a CC role exists for the Template.

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 set to 'true')
  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)

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.

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.

The client ID of the ApiApp you want to associate with this request.

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.

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.

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

Allows signers to decline to sign a document if set to 1. Defaults to 0.

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.

The title you want to assign to the SignatureRequest.

The subject in the email that will be sent to the signers.

The custom message in the email that will be sent to the signers.

The URL you want the signer redirected to after they successfully sign.

signer_file is a CSV file defining values and options for signer fields. Required unless a signer_list is used, you may not use both. The CSV can have the following columns:

• name: the name of the signer filling the role of RoleName
• email_address: email address of the signer filling the role of RoleName
• pin: the 4- to 12-character access code that will secure this signer's signature page (optional)
• sms_phone_number: An E.164 formatted phone number that will receive a code via SMS to access this signer's signature page. (optional)
  Note: Not available in test mode and requires a Standard plan or higher.
• *_field: any column with a "_field" suffix will be treated as a custom field (optional)
  You may only specify field values here, any other options should be set in the custom_fields request parameter.

Example CSV:

name, email_address, pin, company_field

George, george@example.com, d79a3td, ABC Corp

Mary, mary@example.com, gd9as5b, 123 LLC

signer_list is a JSON array defining values and options for signer fields. Required unless a signer_file is used, you may not use both. Each element in the array can have the following two items:

• signers: an array of signers using the RoleName as keys (currently only one signer is supported per SignatureRequest)
• name: the name of the signer filling the role of RoleName
• email_address: email address of the signer filling the role of RoleName
• pin: the 4- to 12-character access code that will secure this signer's signature page (optional)
• sms_phone_number: An E.164 formatted phone number that will receive a code via SMS to access this signer's signature page. (optional)
  Note: Not available in test mode and requires a Standard plan or higher.
• custom_fields: an array of custom field values using the field name or API id as keys (optional)
  You may only specify field values here, any other options should be set in the custom_fields request parameter.

Example JSON:

[
  {
    "signers": {
      "Client": {
        "name": "George",
        "email_address": "george@example.com",
        "pin": "d79a3td"
      }
    },
    "custom_fields": {
      "company": "ABC Corp"
    }
  },
  {
    "signers": {
      "Client": {
        "name": "Mary",
        "email_address": "mary@example.com",
        "pin": "gd9as5b"
      }
    },
    "custom_fields": {
      "company": "123 LLC"
    }
  }
]

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 set to 'true')
  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)

The email address of the CC filling the role of RoleName. Required when a CC role exists for the Template.

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.

The client ID of the ApiApp you want to associate with this request.

The id of the SignatureRequest to send a reminder for.

The email address of the signer to send a reminder to.

The name of the signer to send a reminder to. Include if two or more signers share an email address.

The id of the SignatureRequest to update.

The signature ID for the recipient.

The new email address for the recipient.

The new name for the recipient.

The id of the incomplete SignatureRequest to cancel.

The id of the SignatureRequest to remove.

The id of the SignatureRequest to retrieve.

Set to "pdf" for a single merged document or "zip" for a collection of individual documents.

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)

Boolean. If true, the response will contain the file as base64 encoded string. Base64 encoding is only available for PDFs. (default = false)

The id of the SignatureRequest to retrieve.

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.

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.

The title you want to assign to the SignatureRequest.

The subject in the email that will be sent to the signers.

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.

The order the signer is required to sign in. %i% is an integer that should be unique for each signer.

The 4- to 12-character access code that will secure this signer's signature page.

An E.164 formatted phone number that will receive a code via SMS to access this signer's signature page.
Note: Not available in test mode and requires a Standard plan or higher.

The name of attachment.

The instructions for uploading the attachment.

The signer's unique number, see signers[%i%][name] for more details.

Determines if the attachment must be uploaded.

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 set to 'true')
  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)

The email addresses that should be CCed.

[boolean] Send with a value of 1 if you wish to enable Text Tags parsing in your document. Defaults to 0.

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

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.

Allows signers to decline to sign a document if set to 1. Defaults to 0.

Allows signers to reassign their signature requests to other signers if set to 1. Defaults to 0.
Note: Only available for Premium plan.

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": "",
            "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 information for fields defined in form_fields_per_document. String-indexed JSON array with group_label and requirement keys. form_fields_per_document must contain fields referencing a group defined in form_field_groups.

The required shape of form_field_groups is

{
  "<group ID>": {
    "group_label": string,
    "requirement": string
  }
}

The following is an example of form_field_groups along with the required form_fields_per_document, prior to serialization to a string for the API request:

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

Conditional Logic rules for fields defined in form_fields_per_document.

• id: [string] must be unique
• trigger_operator: [string] currently only AND is supported
• triggers: [array] for identifying the "when" part of "when x do y"
• actions: [array] for identifying the "do" part of "when x do y"

The required shape of form_field_rules is

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

The following is an example of form_field_rules along with the required form_fields_per_document, prior to serialization to a string for the API request:

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

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.

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 Premium and higher.

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.

The id of the ReusableForm to use when creating the SignatureRequest.

The title you want to assign to the SignatureRequest.

The subject in the email that will be sent to the signers.

The custom message in the email that will be sent to the signers.

The URL you want the signer redirected to after they successfully sign.

The name of the signer filling the role of RoleName.

The email address of the signer filling the role of RoleName.

The 4- to 12-character access code that will secure this signer's signature page.

The email address of the CC filling the role of RoleName. Required when a CC role exists for the ReusableForm.

The value to fill in for custom field with the name of CustomFieldName. Required when a CustomField exists in the ReusableForm.

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

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.

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.

The title you want to assign to the SignatureRequest.

The subject in the email that will be sent to the signers.

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.

The 4- to 12-character access code that will secure this signer's signature page. RoleName is case-sensitive.

An E.164 formatted phone number that will receive a code via SMS to access this signer's signature page.
Note: Not available in test mode and requires a Standard plan or higher.

The email address of the CC filling the role of RoleName. Required when a CC role exists for the Template.

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 set to 'true')
  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)

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.

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.

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.

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.

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

Allows signers to decline to sign a document if set to 1. Defaults to 0.

The client ID of the ApiApp you want to associate with this request.

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.

The title you want to assign to the SignatureRequest.

The subject in the email that will be sent to the signers.

The custom message in the email that will be sent to the signers.

The URL you want the signer redirected to after they successfully sign.

signer_file is a CSV file defining values and options for signer fields. Required unless a signer_list is used, you may not use both. The CSV can have the following columns:

• name: the name of the signer filling the role of RoleName
• email_address: email address of the signer filling the role of RoleName
• pin: the 4- to 12-character access code that will secure this signer's signature page (optional)
• sms_phone_number: An E.164 formatted phone number that will receive a code via SMS to access this signer's signature page. (optional)
  Note: Not available in test mode and requires a Standard plan or higher.
• *_field: any column with a "_field" suffix will be treated as a custom field (optional)
  You may only specify field values here, any other options should be set in the custom_fields request parameter.

Example CSV:

name, email_address, pin, company_field

George, george@example.com, d79a3td, ABC Corp

Mary, mary@example.com, gd9as5b, 123 LLC

signer_list is a JSON array defining values and options for signer fields. Required unless a signer_file is used, you may not use both. Each element in the array can have the following two items:

• signers: an array of signers using the RoleName as keys (currently only one signer is supported per SignatureRequest)
• name: the name of the signer filling the role of RoleName
• email_address: email address of the signer filling the role of RoleName
• pin: the 4- to 12-character access code that will secure this signer's signature page (optional)
• sms_phone_number: An E.164 formatted phone number that will receive a code via SMS to access this signer's signature page. (optional)
  Note: Not available in test mode and requires a Standard plan or higher.
• custom_fields: an array of custom field values using the field name or API id as keys (optional)
  You may only specify field values here, any other options should be set in the custom_fields request parameter.

Example JSON:

[
  {
    "signers": {
      "Client": {
        "name": "George",
        "email_address": "george@example.com",
        "pin": "d79a3td"
      }
    },
    "custom_fields": {
      "company": "ABC Corp"
    }
  },
  {
    "signers": {
      "Client": {
        "name": "Mary",
        "email_address": "mary@example.com",
        "pin": "gd9as5b"
      }
    },
    "custom_fields": {
      "company": "123 LLC"
    }
  }
]

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 set to 'true')
  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)

The email address of the CC filling the role of RoleName. Required when a CC role exists for the Template.

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.

The id of the SignatureRequest to release.

The id of the ReusableForm to retrieve.

Which page number of the ReusableForm List to return. Defaults to 1.

Number of objects to be returned per page. Must be between 1 and 100. Default is 20.

The id of the ReusableForm to give the Account access to.

The id or email address of the Account to give access to the ReusableForm. The account id prevails if both are provided.

The id of the ReusableForm to remove the Account's access to.

The id or email address of the Account to remove access to the ReusableForm. The account id prevails if both are provided.

The id of the Template to retrieve.

Which account to return Templates for. Must be a team member. Use "all" to indicate all team members. Defaults to your account.

Which page number of the Template List to return. Defaults to 1.

Number of objects to be returned per page. Must be between 1 and 100. Default is 20.

String that includes search terms and/or fields to be used to filter the Template objects.

The id of the Template to give the Account access to.

The id or email address of the Account to give access to the Template. The account id prevails if both are provided.

The id of the Template to remove the Account's access to.

The id or email address of the Account to remove access to the Template. The account id prevails if both are provided.

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 of the app you're using to create this draft.

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.

The template title

The template title (alias)

The default template email message

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.

The order in which this signer role is required to sign. %i% is an integer that should uniquely identify a signer role.

The name of attachment.

The instructions for uploading the attachment.

The signer's unique number, see signers[%i%][name] for more details.

Determines if the attachment must be uploaded.

The CC roles that must be assigned when using the template to send a signature request

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

Disables the "Me (Now)" option for the person preparing the document. Defaults to 0.

[boolean] Enable the detection of predefined PDF fields by setting the use_preexisting_fields to "1" (defaults to disabled, or "0").

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.

Allows signers to reassign their signature requests to other signers if set to 1. Defaults to 0. Note: Only available for Premium plan.

This allows the requester to specify whether the user is allowed to provide email addresses to CC when creating a template

This allows the requester to specify field options for signature requests created using the template.

• date_format: [string] allows requester to specify the date format (see list of allowed formats)
  Note: Only available for Premium and higher.

This allows the requester to specify editor options when a preparing a document.

• allow_edit_signers: [boolean] allows requesters to edit the list of signers (default: false)
• allow_edit_documents: [boolean] allows requesters to edit documents, including delete and add (default: false)

This allows the requester to enable the editor/preview experience.

• show_preview=1: [boolean] allows requesters to enable the editor/preview experience.
• show_preview=0: [boolean] allows requesters to disable the editor/preview experience.

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": "",
            "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 information for fields defined in form_fields_per_document. String-indexed JSON array with group_label and requirement keys. form_fields_per_document must contain fields referencing a group defined in form_field_groups.

The required shape of form_field_groups is

{
  "<group ID>": {
    "group_label": string,
    "requirement": string
  }
}

The following is an example of form_field_groups along with the required form_fields_per_document, prior to serialization to a string for the API request:

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

Conditional Logic rules for fields defined in form_fields_per_document.

• id: [string] must be unique
• trigger_operator: [string] currently only AND is supported
• triggers: [array] for identifying the "when" part of "when x do y"
• actions: [array] for identifying the "do" part of "when x do y"

The required shape of form_field_rules is

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

The following is an example of form_field_rules along with the required form_fields_per_document, prior to serialization to a string for the API request:

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

The id of the Template to delete.

The id of the template files to retrieve.

Set to "pdf" for a single merged document or "zip" for a collection of individual documents.

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)

Boolean. If true, the response will contain the file as base64 encoded string. Base64 encoding is only available for PDFs. (default = false)

The ID of the template whose files to update

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.

The new default template email subject

The new default template email message

Client ID of the app you're using to create this template

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

The id of the BulkSendJob to retrieve.

Which page number of the BulkSendJob List to return. Defaults to 1.

Number of objects to be returned per page. Must be between 1 and 100. Default is 20.

The (inclusive) start date for the report data in MM/DD/YYYY format.

The (inclusive) end date for the report data in MM/DD/YYYY format.

The type(s) of the report you are requesting. Allowed values are "user_activity" and "document_status". User activity reports contain list of all users and their activity during the specified date range. Document status report contain a list of signature requests created in the specified time range (and their status).

The name of your Team

The name of your Team

The id or email address of the Account of the user to invite to your Team. The account id prevails if both are provided.

The ID or email address of the Account to remove from your Team. The account ID prevails if both are provided.

The email address of an Account on this Team to receive all documents, templates, and API apps (if applicable) from the removed Account. If not provided, and on an Enterprise plan, this data will remain with the removed Account. Note: Only available for Enterprise plans.

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

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.

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.

The subject in the email that will be sent to the signers.

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.

The order the signer is required to sign in. %i% is an integer that should be unique for each signer.

The name of attachment.

The instructions for uploading the attachment.

The signer's unique number, see signers[%i%][name] for more details.

Determines if the attachment must be uploaded.

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 set to 'true')
  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)

The email addresses that should be CCed.

The URL you want signers redirected to after they successfully sign.

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

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

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.

Allows signers to decline to sign a document if set to 1. Defaults to 0.

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": "",
            "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 information for fields defined in form_fields_per_document. String-indexed JSON array with group_label and requirement keys. form_fields_per_document must contain fields referencing a group defined in form_field_groups.

The required shape of form_field_groups is

{
  "<group ID>": {
    "group_label": string,
    "requirement": string
  }
}

The following is an example of form_field_groups along with the required form_fields_per_document, prior to serialization to a string for the API request:

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

Conditional Logic rules for fields defined in form_fields_per_document.

• id: [string] must be unique
• trigger_operator: [string] currently only AND is supported
• triggers: [array] for identifying the "when" part of "when x do y"
• actions: [array] for identifying the "do" part of "when x do y"

The required shape of form_field_rules is

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

The following is an example of form_field_rules along with the required form_fields_per_document, prior to serialization to a string for the API request:

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

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.

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 Premium and higher.

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 of the app you're using to create this draft. Visit our embedded page to learn more about this parameter.

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.

The email address of the user that should be designated as the requester of this draft, if the draft type is "request_signature."

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.

The subject in the email that will be sent to the signers.

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.

The order the signer is required to sign in. %i% is an integer that should be unique for each signer.

The name of attachment.

The instructions for uploading the attachment.

The signer's unique number, see signers[%i%][name] for more details.

Determines if the attachment must be uploaded.

The email addresses that should be CCed.

The URL you want signers redirected to after they successfully sign.

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 set to 'true')
  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)

[boolean] Send with a value of 1 if you wish to enable Text Tags parsing in your document. Defaults to 0.

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

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

[boolean] The request created from this draft will also be signable in embedded mode if set to 1. Defaults to 0.

Disables the "Me (Now)" option for the person preparing the document. Does not work with type "send_document". Defaults to 0.

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.

Allows signers to decline to sign a document if set to 1. Defaults to 0.

Allows signers to reassign their signature requests to other signers if set to 1. Defaults to 0.
Note: Only available for Premium.

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": "",
            "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 information for fields defined in form_fields_per_document. String-indexed JSON array with group_label and requirement keys. form_fields_per_document must contain fields referencing a group defined in form_field_groups.

The required shape of form_field_groups is

{
  "<group ID>": {
    "group_label": string,
    "requirement": string
  }
}

The following is an example of form_field_groups along with the required form_fields_per_document, prior to serialization to a string for the API request:

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

Conditional Logic rules for fields defined in form_fields_per_document.

• id: [string] must be unique
• trigger_operator: [string] currently only AND is supported
• triggers: [array] for identifying the "when" part of "when x do y"
• actions: [array] for identifying the "do" part of "when x do y"

The required shape of form_field_rules is

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

The following is an example of form_field_rules along with the required form_fields_per_document, prior to serialization to a string for the API request:

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

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.

This allows the requester to specify whether the user is allowed to provide email addresses to CC when claiming the draft

The request from this draft will not automatically send to signers post-claim if set to 1. Requester must release the request from hold when ready to send. Defaults to 0.

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 Premium and higher.

This allows the requester to specify editor options when a preparing a document.

• allow_edit_signers: [boolean] allows requesters to edit the list of signers (default: false)
• allow_edit_documents: [boolean] allows requesters to edit documents, to delete only (default: false)

This allows the requester to enable the editor/preview experience.

• show_preview=1: [boolean] allows requesters to enable the editor/preview experience.
• show_preview=0: [boolean] allows requesters to disable the editor/preview experience.

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 of the app you're using to create this draft. Visit our embedded page to learn more about this parameter.

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.

The email address of the user that should be designated as the requester of this draft, if the draft type is "request_signature."

The title you want to assign to the SignatureRequest.

The subject in the email that will be sent to the signers.

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.

The email address of the CC filling the role of RoleName. Required when a CC role exists for the Template. RoleName is case-sensitive.

The URL you want the signer redirected to after they successfully sign.

The URL you want signers redirected to after they successfully request a signature.

[boolean] The request created from this draft will also be signable in embedded mode if set to 1. Defaults to 0.

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.

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 set to 'true')
  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).

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.

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.

Disables the "Me (Now)" option for the person preparing the document. Defaults to 0.

Allows signers to decline to sign a document if set to 1. Defaults to 0.

Allows signers to reassign their signature requests to other signers if set to 1. Defaults to 0. Note: Only available for Premium plan.

The request from this draft will not automatically send to signers post-claim if set to 1. Requester must release the request from hold when ready to send. Defaults to 0.

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.

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 Premium and higher.

This allows the requester to specify editor options when a preparing a document.

• allow_edit_signers: [boolean] allows requesters to edit the list of signers (default: false)
• allow_edit_documents: [boolean] allows requesters to edit documents, including delete and add (default: false)

This allows the requester to enable the editor/preview experience.

• show_preview=1: [boolean] allows requesters to enable the editor/preview experience.
• show_preview=0: [boolean] allows requesters to disable the editor/preview experience.

This allows the requester to enable the preview experience experience.

• preview_only=1: [boolean] allows requesters to enable the preview only experience.
• preview_only=0: [boolean] allows requesters to disable the preview only experience.

Note: This parameter overwrites show_preview=1 (if set).

The ID of the signature request to edit and resend

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

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

The URL you want signers redirected to after they successfully request a signature. Defaults to value from original embedded request.

The URL you want signers redirected to after they successfully sign.

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.

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

This allows the requester to specify editor options when a preparing a document.

• allow_edit_signers: [boolean] allows requesters to edit the list of signers (default: false)
• allow_edit_documents: [boolean] allows requesters to edit documents, including delete and add (default: false)

The id of the signature to get a signature url for

Whether this is a test, locked templates will only be available for editing if this is set to 1. Defaults to 0.

The id of the template to edit

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.

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.

If signer roles are already provided, the user will not be prompted to edit them

Note: this parameter will be deprecated in May 2020 and skipping the signer roles screen will become the default behavior. To enforce showing the signer roles screen, use the force_signer_roles parameter below.

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

Note: this parameter will be deprecated in May 2020 and skipping the subject message screen will become the default behavior. To enforce showing the subject message screen, use the force_subject_message parameter below.

Provide users the ability to review/edit the template signer roles.

Provide users the ability to review/edit the template subject and message.

This allows the requester to specify editor options when a preparing a document.

• allow_edit_signers: [boolean] allows requesters to edit the list of signers (default: false)
• allow_edit_documents: [boolean] allows requesters to edit documents, including delete and add (default: false)

This allows the requester to enable/disable to add or change CC roles when editing the template .

• allow_edit_ccs=1: [boolean] allows requesters to enable editing CC roles in template
• allow_edit_ccs=0: [boolean] allows requesters to disable editing CC roles in template

This allows the requester to enable the editor/preview experience.

• show_preview=1: [boolean] allows requesters to enable the editor/preview experience.
• show_preview=0: [boolean] allows requesters to disable the editor/preview experience.

This allows the requester to enable the preview experience experience.

• preview_only=1: [boolean] allows requesters to enable the preview only experience.
• preview_only=0: [boolean] allows requesters to disable the preview only experience.

Note: This parameter overwrites show_preview=1 (if set).

The client ID of the ApiApp to retrieve.

Which page number of the ApiApp List to return. Defaults to 1.

Number of objects to be returned per page. Must be between 1 and 100. Default is 20.

The name you want to assign to the ApiApp.

The domain name the ApiApp will be associated with.

The URL at which the ApiApp should receive event callbacks.

An image file to use as a custom logo in embedded contexts. (Only applies to some API plans)

The callback URL to be used for OAuth flows. (Required if oauth[scopes] is provided)

A comma-separated list of OAuth scopes to be granted to the app. (Required if oauth[callback_url] is provided).

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.

Determines if signers can use "Insert Everywhere" when signing a document.

The name you want to assign to the ApiApp.

The domain name the ApiApp will be associated with. (Only subdomain changes are allowed if the ApiApp is approved.)

The URL at which the ApiApp should receive event callbacks.

An image file to use as a custom logo in embedded contexts. (Only applies to some API plans)

The callback URL to be used for OAuth flows. (Required if oauth[scopes] is provided)

A comma-separated list of OAuth scopes to be granted to the app. (Required if oauth[callback_url] is provided)

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.

Determines if signers can use "Insert Everywhere" when signing a document.

The client id of the ApiApp to delete.