AcroForm forms

An AcroForm is a PDF with real interactive fields — the kind Acrobat creates. pdfforge detects and fills them natively through the pdfium form API: instant, pixel-perfect, no overlay tricks.

Detect the fields

POST /v1/pdf/form/inspect lists the interactive fields:

PDF=$(base64 -w0 form.pdf)     # macOS: base64 -i form.pdf

curl -X POST https://api.pdf-forge.dev/v1/pdf/form/inspect \
  -H "Authorization: Bearer $PDFFORGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"pdf\": \"$PDF\"}"

{
  "form_type": "acroform",
  "fields": [
    {
      "name": "client_name",
      "type": "text",
      "value": null,
      "page": 1,
      "rect": { "x": 120.5, "y": 208.2, "w": 220.0, "h": 18.0,
                "page_w": 595.0, "page_h": 842.0 }
    },
    { "name": "subscribed", "type": "checkbox", "value": "Off", "page": 1,
      "rect": { ... } }
  ]
}

form_type — acroform, xfa, none (or virtual, see Flat forms).
type — text, checkbox, radio, combo, list or signature; combo/list/radio fields also list their options.
rect — the field's box in PDF points, top-left origin, with the page dimensions (page_w, page_h) so a UI can overlay it.

Fill the fields

POST /v1/pdf/form/fill sets values by field name and returns the filled PDF:

curl -X POST https://api.pdf-forge.dev/v1/pdf/form/fill \
  -H "Authorization: Bearer $PDFFORGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"pdf\": \"$PDF\",
    \"values\": { \"client_name\": \"SAM SARL\", \"subscribed\": true },
    \"flatten\": false
  }" \
  --output filled.pdf

Field	Type	Description
`pdf`	string	Required. Base64 PDF.
`values`	object	Required. `{ field_name: value }` — strings for text fields, booleans for checkboxes.
`flatten`	boolean	Bake the widgets into the page content: final, non-editable output.

Two response headers report the outcome:

X-Fields-Filled: 2
X-Fields-Skipped: [{"name":"country","type":"combo","reason":"..."}]

Fields that cannot be set natively (some radio/combo/list cases) are listed in X-Fields-Skipped with a reason, so you can fall back to a text edit for them.

Flatten for final documents

Without flatten, the output still contains live form fields — anyone can change the values. Pass flatten: true for contracts, certificates and anything you archive or send out.

Next steps

Flat forms — the same flow on PDFs with no fields at all.
Fill via API — the complete inspect → fill script.
PDF templates — for mass generation, prefer a template.

Detect the fields

Fill the fields

Next steps

On this page