---
updatedAt: 2026-10-05T09:00:21.000Z
agentTools:
  projectIndex: https://developers.pandadoc.com/llms.txt
---

# How to Add Field Tags to Documents

Add interactive form fields to PDF, DocX, and RTF documents using text-based curly brace notation.

## Problem

You need to add interactive form fields (signatures, text inputs, checkboxes, dates, etc.) to a PDF, DocX, or RTF document that you upload to PandaDoc. Unlike [native PDF form fields](https://developers.pandadoc.com/docs/form-fields), field tags work across all three file formats and give you control over field placement directly in the document text.

## Prerequisites

* A PDF, DocX, or RTF file you can edit (using Microsoft Word, Google Docs, Adobe Acrobat, or similar)
* A PandaDoc API key or OAuth token
* Familiarity with the [Create Document from File Upload](https://developers.pandadoc.com/docs/create-document-from-file) endpoint

## Solution

### Step 1: Add field tags to your document

Place field tags directly in the text of your document using curly brace notation (`{...}`). PandaDoc parses these tags during document creation and converts them into interactive form fields.

A field tag follows this structure:

<Callout icon="🚧" theme="warn">
  You can only use the ":" (colon) symbol between variables. This symbol cannot be trailing.

  ![Field tag structure diagram: positions 1-5 are fieldType, \*, role, optId, and underscores](https://files.readme.io/a81fbf1-field-tag-structure.png "field-tag-structure.png")
</Callout>

The same structure in text form (the numbers correspond to the positions in the table below):

```text
{fieldType*:role:optId_____}
 │        │ │    │    └ 5. underscores (optional) - widen the field role    
 │        │ │    │                                                          
 │        │ │    └───── 4. optId (optional) - field ID for the fields object
 │        │ │                                                               
 │        │ └────────── 3. role (REQUIRED) - must match a role in recipients
 │        │                                                                 
 │        └──────────── 2. * (optional) - makes the field not required     
 │                                                                          
 └───────────────────── 1. fieldType - signature, or s for shorthand       
```

| Position | Key         | Description                                                                                                                  | Example                           |
| :------- | :---------- | :--------------------------------------------------------------------------------------------------------------------------- | :-------------------------------- |
| 1        | `fieldType` | **Required.** The field type (see supported types below).                                                                    | `signature`, or `s` for shorthand |
| 2        | `*`         | Optional. Add `*` to make the field not required.                                                                            | `*`                               |
| 3        | `role`      | **Required.** The recipient role this field is assigned to. Must match a role in the `recipients` array of your API request. | `s1`                              |
| 4        | `optId`     | Optional field ID. Use this to reference the field in the `fields` object of your API request for pre-filling values.        | `sigBox17`                        |
| 5        | `_____`     | Optional underscores to widen the field. The form field in PandaDoc scales to match the length and size of the tag.          | `_____`                           |

For example, `{textfield:user:name___}` creates a required text field assigned to the role "user" with the ID "name".

<Callout icon="❗️" theme="error">
  ### role is required

  Every field tag must include a role. A tag without a role fails processing with the error `One of field tags in PDF with type='{field}' doesn't have a role`. See the [error handling guide](https://developers.pandadoc.com/docs/create-document-from-file#error-handling).
</Callout>

<Callout icon="🚧" theme="warn">
  ### Role name restrictions

  Underscores are not supported in role names for a file with field tags.
</Callout>

Here is how a field tag in a PDF is converted to a text field in the PandaDoc document:

<Image src="https://files.readme.io/38afedf-ex3.png" align="center" />

[**Download a Sample PDF with Field Tags**](https://cdn2.hubspot.net/hubfs/2127247/public-templates/SamplePandaDocPdf_FieldTags.pdf)

### Step 2: Upload the file and configure fields in the API request

When creating a document from a file, set `parse_form_fields` to `false` (the default). Use the `fields` object to pre-fill values and assign roles for each field tag that has an `optId`:

```json
"fields": {
    "textfield": {
        "value": "Jane",
        "role": "user"
    },
    "dropdown": {
        "value": "opt1",
        "role": "user",
        "options": [
            "opt1",
            "opt2",
            "opt3"
        ]
    },
    "checkbox": {
        "value": true,
        "role": "user"
    },
    "date": {
        "value": "2022-05-20",
        "role": "user"
    },
    "initials": {
        "value": "",
        "role": "user"
    },
    "signature": {
        "value": "",
        "role": "user"
    }
}
```

### Step 3: Map roles to recipients

Each role referenced in a field tag must match a recipient in the `recipients` array:

```json
"recipients": [
    {
        "email": "jane@example.com",
        "first_name": "Jane",
        "last_name": "Doe",
        "role": "user"
    }
]
```

## Supported field types

| Field Type  | Short Notation |
| :---------- | :------------- |
| `textfield` | `t`            |
| `checkbox`  | `c`            |
| `signature` | `s`            |
| `date`      | `d`            |
| `initials`  | `i`            |
| `dropdown`  | `dd`           |
| `radio`     | `r`            |
| `stamp`     | `st`           |

### Radio button limitations

* Options within the same block must be **on the same page**.
* Preselection of options is not supported.
* Different blocks require **unique** IDs.
* Values for options must be **unique**.
* Each document supports **2 to 50** radio button options.

### Stamp limitations

* The stamp is square-shaped, with the field **height determined by its width**.
* If the field extends beyond the document boundaries, it will be **repositioned without changing size**.

## Verification

After creating the document, confirm that field tags were parsed correctly:

1. Check that the document transitions from `document.uploaded` to `document.draft` status (via [webhook](https://developers.pandadoc.com/docs/webhook-setup) or [polling](https://developers.pandadoc.com/reference/document-status)).
2. Open the document in the PandaDoc web app and verify that interactive fields appear in place of the field tags.
3. If the document moves to a failed state, check the [error handling guide](https://developers.pandadoc.com/docs/create-document-from-file#error-handling) for field tag validation errors.

## Related

* [Form Fields](https://developers.pandadoc.com/docs/form-fields) -- an alternative using native PDF form fields (PDF only)
* [Create a Document from File Upload](https://developers.pandadoc.com/docs/create-document-from-file) -- the full file upload how-to
* [Create Document from PDF API reference](https://developers.pandadoc.com/reference/create-document-from-pdf) -- complete endpoint parameters
* [Everything you need to know about Fields](https://support.pandadoc.com/hc/en-us/articles/360040595714--Editor-2-0-Fields) -- PandaDoc help center