Fill a PDF form over NextPDF Connect (Pro)

At a glance

Fill interactive PDF form fields over NextPDF Connect with XML Forms Data Format (XFDF). The signing and forms tool is fill_form. The Pro tool provider registers new FillFormTool(), whose protocol name is fill_form. fill_form is a Pro-tier tool. At boot, the server checks for the Pro package with class_exists() and registers the tool only when the package is present. With Core alone, fill_form is absent from the registry.

Install

composer require nextpdf/server
composer require nextpdf/pro

Bind a transport. Then confirm that the tool exists with diagnostic.capabilities (see environment-diagnostics). Do not assume a fixed tool set.

Conceptual overview

XFDF maps field names to values with <field> elements. Each name must match an AcroForm field that already exists in the target document. The interactive-form field dictionary holds each field (ISO 32000-2 §12.7), and the supplied value becomes the field’s value (ISO 32000-2 §12.7). If a name matches no field, the tool skips it instead of treating it as an error. The tool reports how many fields it filled and how many it skipped.

API surface

Tool	Tier	Role	Risk tier
`create_pdf`	Core	Open the session	Safe
`fill_form`	Pro	Apply XFDF values to AcroForm fields	Caution
`output_pdf`	Core	Render and return the PDF	Approval Required / Review (base64)

Tool names are the registry’s protocol names. The tool catalog is the catalog of record. The installed tier determines which tools are available. Pro tools appear only when the Pro package is installed.

Code sample — Quick start

create_pdf (or load a template that already has form fields).
fill_form with xfdf_data mapping field names to values.
output_pdf → base64.

The result reports fields_filled, fields_skipped, and the matched field names.

Code sample — Production

Use a template with AcroForm field names you control. Validate the XFDF against the XFDF schema before you send it. Check fields_skipped and the returned name list to catch a name mismatch (names are case-sensitive). For large fills, stay under the XFDF size limit, and split the data if needed.

Edge cases & gotchas

Malformed XFDF. A parse error identifies the offending location. Escape XML entities and include the xmlns.
Name mismatch. A non-matching field is silently skipped, and fields_skipped increments. Names are case-sensitive.
No form fields. A document with no AcroForm yields zero filled fields.
XFDF too large. The server rejects data over the size limit. Split it or trim the whitespace.
Pro absent. With Core only, fill_form is not registered, and calling it returns an unknown-tool error. Check with diagnostic.capabilities first.

Performance

Filling is fast compared with rendering. Output ranges from a few KB to tens of KB, depending on field count and font embedding. The profile is structural.

Security notes

Field values become document content. Do not place secrets in form fields if you then return the PDF over an untrusted channel. The base64 path has no filesystem side effect. File output is gated.

Conformance

Statement	Spec	Clause	reference_id
A form field is held in the interactive-form field dictionary.	ISO 32000-2	§12.7
The supplied data becomes the field’s value.	ISO 32000-2	§12.7

Commercial context

fill_form is a Pro-tier tool. The server registers it only when the Pro package resolves at boot (the class_exists() probe). Core deployments do not expose it.

Transport availability

Transport	Available	Notes
MCP (stdio)	Yes (Pro)	Present only when Pro is installed.
REST	Yes (Pro)	Same.
gRPC	Yes (Pro)	Same.

HITL risk tier

fill_form is Caution because it is a reversible content mutation. output_pdf is Approval Required, downgraded to Review in base64 mode (HITL risk tiers).

Confirmation gate JSON envelope

Base64 output:

{ "allowed": true }

File output returns the challenge envelope described in output-approval.