How to Add Field Tags to Documents

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, 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 endpoint

Solution

Step 1: Add field tags to your document

Place field tags directly in the text of your document using bracket notation. PandaDoc parses these tags during document creation and converts them into interactive form fields.

A field tag follows this structure:

🚧

You can only use the ":" (colon) symbol between variables. This symbol cannot be trailing.

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

🚧

Role name restrictions

Underscores are not supported in role names for a file with field tags.

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

Download a Sample PDF with Field Tags

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:

"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:

"recipients": [
    {
        "email": "[email protected]",
        "first_name": "Jane",
        "last_name": "Doe",
        "role": "user"
    }
]

Supported field types

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 or polling).
2. Open the document in the PandaDoc web app and verify that interactive fields appear in place of the bracket tags.
3. If the document moves to a failed state, check the error handling guide for field tag validation errors.

Related

• Form Fields -- an alternative using native PDF form fields (PDF only)
• Create a Document from File Upload -- the full file upload how-to
• Create Document from PDF API reference -- complete endpoint parameters
• Everything you need to know about Fields -- PandaDoc help center