PDF Form Filler — describe, fill and flatten AcroForm PDFs

Turn any fillable PDF into an API. This Actor does two things, designed to be called by automations (n8n, Make, Zapier) and AI agents (MCP):

1. describe — point it at a fillable PDF and get back the complete field schema as JSON: every field's name, type, page, position, options and the exact value that ticks each checkbox.
2. fill — send data records and get back filled, flattened, ready-to-send PDFs, one per record.

No OCR, no external services, no accounts to connect. The PDF and the data are yours; the Actor is pure processing.

Why describe matters

Real-world forms have field names no human would guess. The IRS W-9 calls its name line topmostSubform[0].Page1[0].f1_01[0], and its federal-classification checkboxes turn on with the values "1" through "7" — not true, not "Yes". One describe call gives you (or your agent) the exact map:

{
  "name": "topmostSubform[0].Page1[0].Boxes3a-b_ReadOrder[0].c1_1[0]",
  "type": "checkbox",
  "page": 0,
  "rect": [36.2, 594.9, 47.5, 606.2],
  "required": false,
  "on_value": "1"
}

Filling and flattening done properly

Setting a form field's value is the easy part. Making the value actually render is the part most tools skip: a PDF field whose appearance stream was not regenerated shows up blank in Chrome, Preview and most non-Adobe viewers, even though the data is technically there.

This Actor regenerates appearance streams with qpdf and then (by default) flattens the document: the values become permanent page content that renders identically everywhere, and the form can no longer be edited or tampered with. Set "flatten": false if you want the fields to stay editable instead.

Hybrid XFA forms — the US government kind, W-9 included — are handled: the AcroForm layer is filled and the stale XFA layer is removed, so Adobe Acrobat shows your values too. Dynamic XFA forms (no AcroForm fields at all) are reported as unsupported rather than silently mangled.

Input

Describe a form:

{
  "mode": "describe",
  "pdfUrl": "https://www.irs.gov/pub/irs-pdf/fw9.pdf"
}

Fill it (one object per document to produce):

{
  "mode": "fill",
  "pdfUrl": "https://www.irs.gov/pub/irs-pdf/fw9.pdf",
  "records": [
    {
      "topmostSubform[0].Page1[0].f1_01[0]": "Marie Dupont",
      "topmostSubform[0].Page1[0].Boxes3a-b_ReadOrder[0].c1_1[0]": true
    }
  ],
  "flatten": true
}

Checkboxes accept true/false or the export value. Radio groups and dropdowns accept one of the options listed by describe. Text fields accept strings or numbers. Values that match no option are reported as warnings, never as crashes — the rest of the record is still applied.

Output

• Dataset: one row per described form or per filled record, with a machine-readable status, the list of appliedFields, any warnings, and the download link of the produced file.
• Key-value store: the filled PDFs themselves, filled-0001.pdf onwards.

A record that references a wrong field name, a password-protected template, an unreachable URL — every failure mode is a dataset row with a status your automation can branch on (download_failed, password_protected, xfa_not_supported, fill_failed, …). The run itself succeeds.

Typical uses

• Generate tax, onboarding, insurance or consent forms from CRM rows or spreadsheet data — hundreds per run.
• Let an AI agent fill government forms deterministically: describe gives it the schema, fill executes without hallucinated field names.
• Turn scraped or collected data into signed-ready documents at the end of an Apify pipeline.

Limitations

• Dynamic XFA forms (Adobe LiveCycle, no AcroForm layer) are not supported; they are detected and reported as xfa_not_supported.
• Signature fields are listed by describe but cannot be filled — this Actor does not fake signatures.
• Password-protected PDFs are reported as password_protected; send the unlocked version.
• Values outside Latin-1 (CJK, Cyrillic, Arabic…) cannot be rendered by the standard PDF fonts, so such documents are returned unflattened with the correct values stored and NeedAppearances set: any capable viewer renders them properly. The row carries a warning. Flattening them would stamp ? into the page forever — we refuse to do that.
• fill mode requires a real pdfUrl; the bundled sample form is only used by describe, so a broken pipeline variable can never bill you for filled demo forms (missing_pdf_url).
• Very large forms: the field schema row is truncated past 2 000 fields (the full schema is delivered in the key-value store, see schemaUrl), and forms beyond 5 000 fields are rejected as form_too_large.

Pricing

Pay per event: a small fee per successfully described form (a PDF with no form at all costs you nothing), and a per-document fee for each filled PDF — charged only after the file is actually stored. Records skipped over your run's spending cap are never billed, and invalid records never consume your cap: every budget cent maps to a delivered document.