Constants

Field types

These are the options you can specify for the type field.

Type Description
text A text input field
checkbox A yes/no checkbox
date_signed A date when a document was signed
dropdown An input field for dropdowns
initials An input field for initials
radio An input field for radios
signature A signature input field
text-merge A text field that has default text set by the api
checkbox-merge A checkbox field that has default value set by the api

Form fields per document

Different field types may have different options available to them within the form_fields_per_document parameter.

Field type Description
text placeholder: String (optional)
  Placeholder value for text field.
  "placeholder": "First Name"

auto_fill_type: String (optional)
  Auto fill type for populating fields automatically.
  "auto_fill_type": "email"
  Checkout the list of auto fill types to learn more about the possible values.

link_id: String (optional)
  Link two or more text fields. Enter data into one linked text field, which automatically fill all other linked text fields.
  "link_id": "linked_fields_id_1"

masked: Integer(optional)
  Masks entered data. For more information see Masking sensitive information.
  1 for masking the data in a text field, otherwise 0.
  "masked": 0
dropdown options: String[] (required)
  Array of string values representing dropdown values.
  "options": ["Option 1","Option 2"]

content: String (optional)
  Selected value in options array. Value must exist in array.
  "content": "Option 2"
hyperlink content: String (required)
  Link Text.
  "content": "Click me!"

content_url: String (required)
  Link URL.
  "content_url": "http://example.com"
checkbox group: String (optional)
  String referencing group defined in form_field_groups parameter.
  "group": "group_1"

checked: Integer (required)
  1 for checking the checkbox field by default, otherwise 0
  "checked": 1
radio group: String (required)
  String referencing group defined in form_field_groups parameter.
  "group": "group_1"

checked: Integer (required)
  1 for checking the radio field by default, otherwise 0
  "checked": 1

Checkbox field grouping

Checkbox field groups accept an optional validation rule, which must be met before the user can submit the signed document. These are the options you can specify for validation rule.

Rule Description
require_0-1 Requires at most one checkbox within the group to be checked (radio button functionality)
require_1 Requires only one checkbox within the group to be checked
require_1-ormore Requires at least one checkbox within the group to be checked

Radio field grouping

Radio field groups must define a validation rule, which must be met before the user can submit the signed document. These are the options you can specify for validation rule.

Rule Description
require_0-1 Makes group optional (signer does not have to select any radio option)
require_1 Makes group required (signer has to select one radio option)

Conditional logic

Conditional logic allows adding an "if this, then that" flow to signature requests.

Field type Description
id
String
Unique across all defined rules.
  "id": "rule_id_1"
trigger_operator
String
Currently only AND is supported.
  "id": "rule_id_1"
triggers
Array
An array of trigger definitions, the "if this" part of "if this, then that". Currently only a single trigger per rule is allowed.
ParameterDescription
id
String
(required)
Must reference the api_id of an existing field defined within form_fields_per_document.

Trigger and action fields and groups must belong to the same signer.
"id": "uniqueIdHere_1"
operator
String
(required)
Different field types allow different operator values:
FieldOperator
textis: exact match
not: not exact match
match: regular express, without "/".
    OK: [a-zA-Z0-9]
    Not OK: /[a-zA-Z0-9]/

Example: "operator": "is"
dropdownis: exact match, single value
not: not exact match, single value
any: exact match, array of values
none: not exact match, array of values

Example: "operator": "any"
checkboxis: exact match, single value
not: not exact match, single value

Example: "operator": "is"
radiois: exact match, single value
not: not exact match, single value

Example: "operator": "is"
value
String or String[]
(required)
The value to match against the operator.

When operator is one of the following, value must be String (single string):
  is
  not
  match
  Example: "value": "foobar"

When operator is one of the following, value must be String[] (array of strings):
  any
  none
  Example: "value": ["foo", "bar"]

checkbox: When type of trigger is checkbox, value must be 0 or 1:
  Example:"value": 0

checkbox: When type of trigger is radio, value must be 1:
  Example:"value": 1
actions
Array
An array of action definitions, the "then that" part of "if this, then that". Any number of actions may be attached to a single rule.

ParameterDescription
field_id
String
(required)
Must reference the api_id of an existing field defined within form_fields_per_document

Cannot use with group_id. Trigger and action fields must belong to the same signer.
Example: "field_id": "uniqueIdHere_1"
group_id
String
(required)
Must reference the ID of an existing group defined within form_field_groups

Cannot use with field_id. Trigger and action fields and groups must belong to the same signer.
Example: "group_id": "group_id_1"
hidden
Integer
(required)
1 to hide the target field when rule is satisfied, otherwise 0.
Example: "hidden": 1
type
String
(required)
Use change-field-visibility if field_id is used.
Use change-group-visibility if group_id is used.
Example:"type": "change-field-visibility"

Notes about conditional logic:

  1. Conditional logic can only be set up for one trigger field, not a combination of fields. For example, you can't specify IF dropdown = option1 **AND** textbox = "cat" , then show these selected fields.
  2. Conditional logic, both triggered and selected fields, must be limited to a specific signer. You can't set up a trigger field that, when complete by one signer, triggers fields for another signer.
  3. A field can act as a trigger field for multiple conditions. However, a field can only act as a selected field once.
  4. See our Adding conditional logic to documents page for more information on how conditional logic works within the Editor.

Signature status codes

The Signature Request response object contains a list of associated signatures. Each signature entry includes a status_code field that describes its current state. The table below lists all possible codes.

Status Description
success Signature request successfully completed
on_hold On hold. This could be because the sending account needs to confirm its email address, or because of insufficient funds.
signed Signature completed but signature request still in progress
awaiting_signature Awaiting signature
declined Signature was declined
error_unknown Unknown error
error_file File could not be converted
error_component_position Invalid form fields placement
error_text_tag File contained invalid text tags
on_hold_by_requester Request was prepared for signature but has not been sent to signers. Requester must release the request from hold when ready to send.
error_invalid_email Invalid email

Data validation types

Text fields accept an optional validation type, which must be met before the user can submit the signed document. This value can be specified in form fields, text tags, or on the web. These are the options you can specify for validation type.

Type Description
numbers_only Numbers only (negative and decimal values included)
letters_only Letters only (non-English letters included)
phone_number 10- or 11-digit number
bank_routing_number 9-digit number
bank_account_number Minimum 6-digit number
email_address Email address
zip_code 5- or 9-digit number
social_security_number 9-digit number
employer_identification_number 9-digit number
custom_regex Custom regular expression (See note below)

Notes about data validation types: When using custom_regex you are required to pass a second parameter, validation_custom_regex, and you can optionally provide validation_custom_regex_format_label for the error message the user will see in case of an invalid value. Here's an example:

Copy
Copied
  "validation_type": "custom_regex",
  "validation_custom_regex": "A[0-9]{3}",
  "validation_custom_regex_format_label": "A000",

Auto Fill types

Text fields accept an optional auto fill type. This value can be specified in form fields, text tags, or on the web. Below are the options you can specify for auto fill type.

Type Description
firstName Text Tag example:

[text|req|signer1|Label|UniqueId|letters_only|firstName]

form_fields_per_document example:

[ [ { "api_id": "field1", "placeholder": "First Name", "auto_fill_type": "firstName", "name": "firstname", "type": "text", "x": 160, "y": 80, "page": 1, "width": 206, "height": 32, "required": true, "signer": 0 } ] ]
lastName Text Tag example:

[text|req|signer1|Label|UniqueId|letters_only|lastName]

form_fields_per_document example:

[ [ { "api_id": "field1", "placeholder": "Last Name", "auto_fill_type": "lastName", "name": "lastname", "type": "text", "x": 160, "y": 80, "page": 1, "width": 206, "height": 32, "required": true, "signer": 0 } ] ]
name Text Tag example:

[text|req|signer1|Label|UniqueId|letters_only|name]

form_fields_per_document example:

[ [ { "api_id": "field1", "placeholder": "Full Name", "auto_fill_type": "name", "name": "fullname", "type": "text", "x": 160, "y": 80, "page": 1, "width": 206, "height": 32, "required": true, "signer": 0 } ] ]
email Text Tag example:

[text|req|signer1|Label|UniqueId|email_address|email]

form_fields_per_document example:

[ [ { "api_id": "field1", "placeholder": "email", "auto_fill_type": "email", "name": "email", "type": "text", "x": 160, "y": 80, "page": 1, "width": 206, "height": 32, "required": true, "signer": 0 } ] ]
company Text Tag example:

[text|req|signer1|Label|UniqueId|letters_only|company]

form_fields_per_document example:

[ [ { "api_id": "field1", "placeholder": "company", "auto_fill_type": "company", "name": "company", "type": "text", "x": 160, "y": 80, "page": 1, "width": 206, "height": 32, "required": true, "signer": 0 } ] ]
title Text Tag example:

[text|req|signer1|Label|UniqueId|letters_only|title]

form_fields_per_document example:

[ [ { "api_id": "field1", "placeholder": "title", "auto_fill_type": "title", "name": "title", "type": "text", "x": 160, "y": 80, "page": 1, "width": 206, "height": 32, "required": true, "signer": 0 } ] ]

Notes about auto fill types: Label, id, or validation can be skipped with the following example: [text|req|signer1||||firstName]

Date formats

Format Example
MM / DD / YYYY 02 / 24 / 2022
MM - DD - YYYY 02 - 24 - 2022
DD / MM / YYYY 24 / 02 / 2022
DD - MM - YYYY 24 - 02 - 2022
YYYY / MM / DD 2022 / 02 / 24
YYYY - MM - DD 2022 - 02 - 24

Supported locales

These are the locales you can specify for the locale field. They're case-sensitive. Note that this only affects locale preference in the settings page.

Locale Name
en-US English US
en-GB English (United Kingdom)
da-DK Dansk
de-DE Deutsch
es-LA Español (Latinoamérica)
es-ES Español (España)
fr-FR Français
id-ID Bahasa Indonesia
it-IT Italiano
ja-JP 日本語
ko-KR 한국어
ms-MY Bahasa Malaysia
nb-NO Norsk bokmål
nl-NL Nederlands
pl-PL Polski
pt-BR Português (Brasil)
ru-RU Pусский
sv-SE Svenska
th-TH ไทย
uk-UA Українська
zh-CN 中文(简体)
zh-TW 中文(繁體)