Manual Reference Pages

Constants

View as Markdown

Field types

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

TypeDescription
textA text input field
checkboxA yes/no checkbox
date_signedA date when a document was signed
dropdownAn input field for dropdowns
initialsAn input field for initials
radioAn input field for radios
signatureA signature input field
text-mergeA text field that has default text set by the api
checkbox-mergeA 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 typeDescription
textplaceholder: 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
dropdownoptions: 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"
hyperlinkcontent: String (required)
  Link Text.
  "content": "Click me!"

content_url: String (required)
  Link URL.
  "content_url": "http://example.com"
checkboxgroup: 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
radiogroup: 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.

RuleDescription
require_0-1Requires at most one checkbox within the group to be checked (radio button functionality)
require_1Requires only one checkbox within the group to be checked
require_1-ormoreRequires 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.

RuleDescription
require_0-1Makes group optional (signer does not have to select any radio option)
require_1Makes 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 typeDescription
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.

StatusDescription
successSignature request successfully completed
on_holdOn hold. This could be because the sending account needs to confirm its email address, or because of insufficient funds.
signedSignature completed but signature request still in progress
awaiting_signatureAwaiting signature
declinedSignature was declined
error_unknownUnknown error
error_fileFile could not be converted
error_component_positionInvalid form fields placement
error_text_tagFile contained invalid text tags
on_hold_by_requesterRequest was prepared for signature but has not been sent to signers. Requester must release the request from hold when ready to send.
error_invalid_emailInvalid email
expiredSignature expired and is no longer signable. See Signature Request Expiration Date

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.

TypeDescription
numbers_onlyNumbers only (negative and decimal values included)
letters_onlyLetters only (non-English letters included)
phone_number10- or 11-digit number
bank_routing_number9-digit number
bank_account_numberMinimum 6-digit number
email_addressEmail address
zip_code5- or 9-digit number
social_security_number9-digit number
employer_identification_number9-digit number
custom_regexCustom 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:

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

Populate Auto-Fill Fields

populate_auto_fill_fields is a new parameter we introduced to Dropbox Sign embedded API endpoints to give users more flexibility to choose which signature requests have auto-fill. This parameter enables auto-populating (Auto-Fill) fields for your signature requests. This feature pulls information from your signers, provided from either their own Dropbox Sign profile or from the name and email address entered in by the requester, and populates the information into the corresponding fields.

FieldDescriptionSupported Endpoints
populate_auto_fill_fieldsType: boolean
Default: false
Controls whether auto fill fields can automatically populate a signer’s information during signing.
⚠️ Note ⚠️: Keep your signer’s information safe by ensuring that the signer on your signature request is the intended party before using this feature. Auto-fill fields are only able to be assigned to signers.		signature_request/create_embedded

signature_request/create_embedded_with_template

unclaimed_draft/create_embedded

unclaimed_draft/create_embedded_with_template

Here’s an example using cURL:

$ 
$curl -X POST 'https://api.hellosign.com/v3/signature_request/create_embedded' \
>  -u 'YOUR_API_KEY:' \
>  -F 'client_id=YOUR_CLIENT_ID' \
>  -F 'files[0]=@mutual-NDA-example.pdf' \
>  -F 'signers[0][email_address]=jack@example.com' \
>  -F 'signers[0][name]=Jack' \
>  -F 'test_mode=1' \
>  -F 'populate_auto_fill_fields=1'

The available Auto-Fill fields are listed in the next section below.

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.

TypeDescription
firstNameText 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 } ] ]
lastNameText 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 } ] ]
nameText 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 } ] ]
emailText 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 } ] ]
companyText 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 } ] ]
titleText 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

FormatExample
MM / DD / YYYY02 / 24 / 2022
MM - DD - YYYY02 - 24 - 2022
DD / MM / YYYY24 / 02 / 2022
DD - MM - YYYY24 - 02 - 2022
YYYY / MM / DD2022 / 02 / 24
YYYY - MM - DD2022 - 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.

LocaleName
en-USEnglish US
en-GBEnglish (United Kingdom)
da-DKDansk
de-DEDeutsch
es-LAEspañol (Latinoamérica)
es-ESEspañol (España)
fr-FRFrançais
id-IDBahasa Indonesia
it-ITItaliano
ja-JP日本語
ko-KR한국어
ms-MYBahasa Malaysia
nb-NONorsk bokmål
nl-NLNederlands
pl-PLPolski
pt-BRPortuguês (Brasil)
ru-RUPусский
sv-SESvenska
th-THไทย
uk-UAУкраїнська
zh-CN中文（简体）
zh-TW中文（繁體）