> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.hellosign.com/llms.txt.
> For full documentation content, see https://developers.hellosign.com/llms-full.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.hellosign.com/_mcp/server.

# Fields & Templates

> Form fields, field types, merge fields, text tags, and conditional logic in the Dropbox Sign API.

# 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](/api/manual-reference-pages/glossary/core-objects#document)** page
- Assigned to a **[Signer](/api/manual-reference-pages/glossary/signers-roles#signer)** or **[Signer Role](/api/manual-reference-pages/glossary/signers-roles#signer-role)**
- Belongs to a **[Signature Request](/api/manual-reference-pages/glossary/core-objects#signature-request)** or **[Template](/api/manual-reference-pages/glossary/core-objects#template)**
- May participate in **[Conditional Logic](#conditional-logic)** rules
- May be part of a **Field Group** (see [checkbox field grouping](/api/manual-reference-pages/constants#checkbox-field-grouping) and [radio field grouping](/api/manual-reference-pages/constants#radio-field-grouping))

---

## Field Types

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

| Type | Description | Signer Interaction |
| --- | --- | --- |
| `signature` | Electronic signature | Signer draws/types/uploads signature |
| `initials` | Signer's initials | Signer draws/types initials |
| `text` | Free-form text input | Signer types text |
| `date_signed` | Auto-filled signing date | Automatic (no signer action needed) |
| `checkbox` | A toggleable checkbox | Signer checks/unchecks |
| `radio` | A radio button (mutually exclusive within group) | Signer selects one option |
| `dropdown` | A dropdown/select menu | Signer picks from options |
| `hyperlink` | A clickable URL | Display only (not filled by signer) |
| `text-merge` | Pre-filled text (merge field) | Display only (sender fills at send time) |
| `checkbox-merge` | Pre-filled checkbox (merge field) | Display only (sender sets at send time) |

**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:**
```json
// Template defines merge fields:
"merge_fields": [
  { "name": "client_name", "type": "text" },
  { "name": "contract_amount", "type": "text" },
  { "name": "rush_delivery", "type": "checkbox" }
]

// At send time, provide values:
"custom_fields": [
  { "name": "client_name", "value": "Acme Corp" },
  { "name": "contract_amount", "value": "$50,000" },
  { "name": "rush_delivery", "value": true }
]
```

**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](/docs/guides/pre-filled-document-data/overview) 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...]
```

| Position | Value | Description |
| --- | --- | --- |
| 1 | Field type | `sig`, `initial`, `text`, `date_signed`, `checkbox`, `dropdown` |
| 2 | Requirement | `req` (required) or `noreq` (optional) |
| 3 | Signer ID | `signer1`, `signer2`, etc. or role name |
| 4+ | Options | Label, group name, dropdown options (varies by type) |

**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](/docs/walkthroughs/text-tags).

---

## 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:**
```json
{
  "triggerOperator": "AND",
  "triggers": [
    { "id": "field_api_id", "operator": "is", "value": "some_value" }
  ],
  "actions": [
    { "field_id": "target_field_api_id", "action": "show" }
  ]
}
```

**Trigger Operators:**
| Operator | Description |
| --- | --- |
| `is` | Field value equals the specified value |
| `is_not` | Field value does not equal the specified value |
| `has_any_value` | Field has been filled with any value |
| `is_empty` | Field has not been filled |

**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:**
| Concept | Who fills it | When | Signer can edit? |
| --- | --- | --- | --- |
| Form Field | Signer | During signing | Yes (it's their input) |
| Custom Field / Merge Field | Sender | At request creation | No (read-only) |
| Editable Custom Field | Sender provides default | At creation, signer can change | Yes |

**Related docs:** See [Pre-filled Document Data](/docs/guides/pre-filled-document-data/overview) for examples of passing values through `custom_fields`.