How to Use Native PDF Form Fields

Problem

You have a PDF with native form fields (created in Adobe Acrobat, Foxit, or similar) and you want PandaDoc to recognize them as interactive fields when you upload the file. This approach works only with PDFs and uses the form fields already embedded in the file, unlike text-based field tags which work across PDF, DocX, and RTF.

Prerequisites

A PDF file containing native form fields
A PandaDoc API key or OAuth token
Familiarity with the Create Document from File Upload endpoint

Solution

Step 1: Verify your PDF form fields are supported

PandaDoc supports the following native PDF form field types:

Field type	Supported	Notes
Text	Yes	Single- and multi-line text.
Date	Partial	Recognized as a date only when the PDF uses standard Acrobat-style date formatting; otherwise appears as text.
Checkbox	Yes
Dropdown (combo box)	Yes	Options and current value are captured.
List box	Yes	Exported like a dropdown; multiple selection is represented as multi-line dropdown-style output.
Radio button	Yes	Each option is captured; grouping follows the PDF.
Signature	Yes
Initials	No*	Not exported as a dedicated type. *May appear if the authoring tool stores them as a text or signature field.
Rich text	Limited	May export as plain text only; rich formatting is not preserved.
Password	Limited	May export like a normal text field; masking behavior is not preserved.
Buttons, barcode, image, file pick	No	Ignored during field export.

You can view and edit field names in your PDF editor (Adobe Acrobat, Foxit, etc.) before uploading.

Download a Sample PDF with Form Fields

Step 2: Upload the PDF with `parse_form_fields` enabled

Set parse_form_fields to true in your create document request. This tells PandaDoc to extract native form fields from the PDF.

🚧
Form fields vs. field tags
Set parse_form_fields to true for native form fields. Set it to false (the default) when using text-based field tags. Avoid using both in the same PDF; if both are present, you may get duplicate or overlapping fields.

Step 3: Pre-fill values and assign roles

Use each PDF field's name as the key in the fields object of your request body. See the Create Document from PDF API reference for the exact matching rules.

"fields": {
    "Name_Field": {
        "value": "Jane Doe",
        "role": "user"
    },
    "City_Dropdown": {
        "value": "New York",
        "role": "user"
    }
}

Each entry in the fields object requires:

Key	Description
`value`	The pre-filled value for the field.
`role`	The recipient role this field is assigned to. Must match a role in `recipients`.

Step 4: Map roles to recipients

Each role referenced in the fields object must match a recipient:

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

Verification

Check that the document transitions from document.uploaded to document.draft status (via webhook or polling).
Open the document in the PandaDoc web app and verify that form fields appear as interactive PandaDoc fields.
If the document fails, check the error handling guide for form field validation errors.

Field Tags -- an alternative using text-based bracket notation (supports PDF, DocX, and RTF)
Create a Document from File Upload -- the full file upload how-to
Create Document from PDF API reference -- complete endpoint parameters

Problem

Prerequisites

Solution

Step 1: Verify your PDF form fields are supported

Step 2: Upload the PDF with parse_form_fields enabled

Form fields vs. field tags

Step 3: Pre-fill values and assign roles

Step 4: Map roles to recipients

Verification

Related

Step 2: Upload the PDF with `parse_form_fields` enabled