Fields & Templates

Form fields (the interactive elements signers fill out), how they are placed on documents, and advanced field features like merge fields, text tags, and conditional logic.

Form Field

Brief: An interactive element placed on a document that a signer must fill out (signature, text input, checkbox, etc.).

Description: A UI element positioned on a specific page of a document. Each field is assigned to a particular signer (or signer role in templates) and has a type that determines what input it collects. Fields have precise coordinates (x, y) and dimensions (width, height) relative to the document page.

Relationships:

• Placed on a Document page
• Assigned to a Signer or Signer Role
• Belongs to a Signature Request or Template
• May participate in Conditional Logic rules
• May be part of a Field Group (see checkbox field grouping and radio field grouping)

Field Types

Brief: The category of a form field that determines what input it accepts and how it renders.

Field Validation:

• text fields can have validation rules: numbers_only, letters_only, phone_number, bank_routing_number, bank_account_number, email_address, zip_code, social_security_number, employer_identification_number

Important Distinctions:

• signature and initials are distinct legal concepts and are not interchangeable.
• date_signed auto-populates with the date the signer actually signs; it is not set by the sender.
• text fields are filled by the signer, while text-merge fields are pre-filled by the sender and are read-only for signers.

Merge Field

Brief: A placeholder in a Template that is filled with dynamic data at send time by the sender, not the signer.

Description: Allows injecting dynamic content into a Template when creating a Signature Request. Unlike regular form fields (filled by signers), merge fields are pre-populated by the sender via the API. Useful for contract-specific details like names, dates, or amounts.

Types: text or checkbox

Example:

1
// Template defines merge fields:
2
"merge_fields": [
3
  { "name": "client_name", "type": "text" },
4
  { "name": "contract_amount", "type": "text" },
5
  { "name": "rush_delivery", "type": "checkbox" }
6
]
7
8
// At send time, provide values:
9
"custom_fields": [
10
  { "name": "client_name", "value": "Acme Corp" },
11
  { "name": "contract_amount", "value": "$50,000" },
12
  { "name": "rush_delivery", "value": true }
13
]

Important Distinctions:

• In the API request body, merge field values are passed via the custom_fields parameter despite being conceptually different from Custom Fields.
• Unfilled merge fields appear blank on the document.
• Merge fields are read-only for signers.

Related docs: See Pre-filled Document Data for template, text tag, and form field examples.

Text Tags

Brief: Special text strings placed directly in a document that are automatically converted into form fields during processing.

Description: An alternative to positioning fields via the API or editor. Specially-formatted text strings are embedded directly in a document (e.g., in a Word file or PDF). When uploaded, Dropbox Sign detects these tags and converts them into form fields. The tag text is removed and replaced with the interactive field.

Format:

[sig|req|signer1]           → Required signature field for signer 1
[initial|req|signer2]       → Required initials for signer 2
[text|noreq|signer1|Label]  → Optional text field for signer 1
[date_signed|req|signer1]   → Required date_signed for signer 1
[checkbox|req|signer1|Group] → Required checkbox in a group
[dropdown|req|signer1|Label|Option1|Option2|Option3] → Dropdown

Tag Structure:

[field_type|requirement|signer_identifier|label|options...]

Important Distinctions:

• When text tags are processed, the tag text disappears and is replaced by the form field. Account for this when positioning other elements.
• Text tags and API-positioned fields can coexist on the same document — both will be created.

Related docs: See the Text Tags walkthrough.

Conditional Logic

Brief: Rules that show or hide form fields based on signer interactions with other fields.

Description: Allows creating dynamic forms where fields appear or disappear based on signer input on trigger fields. Rules consist of triggers (conditions) and actions (fields to show/hide).

Structure:

1
{
2
  "triggerOperator": "AND",
3
  "triggers": [
4
    { "id": "field_api_id", "operator": "is", "value": "some_value" }
5
  ],
6
  "actions": [
7
    { "field_id": "target_field_api_id", "action": "show" }
8
  ]
9
}

Trigger Operators:

Trigger Combination:

• AND — All triggers must be satisfied
• OR — At least one trigger must be satisfied

Actions:

• show — Make the target field visible and interactive
• hide — Make the target field invisible and non-required

Supported Trigger Field Types: checkbox, radio, dropdown, text

Important Distinctions:

• Circular dependencies (Field A shows Field B, Field B shows Field A) should be avoided.
• Hidden fields are cleared when hidden — they do not retain their values.

Custom Fields (Pre-filled Fields)

Brief: Fields that are pre-filled by the sender with static data before the signer sees the document.

Description: In the API, the custom_fields parameter serves two purposes:

1. Providing values for Merge Fields defined in templates
2. Pre-filling named fields with data

These are read-only for signers unless explicitly marked as editable.

Important Distinction:

Related docs: See Pre-filled Document Data for examples of passing values through custom_fields.