POST /api/fill-form

import { readFile, writeFile } from 'node:fs/promises';

const pdf = await readFile('invoice-template.pdf');
const fd = new FormData();
fd.append('pdf', new Blob([pdf], { type: 'application/pdf' }), 'invoice-template.pdf');
fd.append('fields', JSON.stringify({
  customer_name: 'Acme Co',
  total: '$1,250.00',
}));

const res = await fetch('https://pdfops.dev/api/fill-form', {
  method: 'POST',
  body: fd,
});

if (!res.ok) {
  const err = await res.json();
  throw new Error(`PDFops fill-form failed: ${err.error} — ${err.details}`);
}

await writeFile('filled.pdf', Buffer.from(await res.arrayBuffer()));

import json
import httpx

with open('invoice-template.pdf', 'rb') as f:
    pdf_bytes = f.read()

files = {'pdf': ('invoice-template.pdf', pdf_bytes, 'application/pdf')}
data = {'fields': json.dumps({
    'customer_name': 'Acme Co',
    'total': '$1,250.00',
})}

r = httpx.post('https://pdfops.dev/api/fill-form', files=files, data=data, timeout=30)
if r.status_code != 200:
    err = r.json()
    raise RuntimeError(f"PDFops fill-form failed: {err['error']} — {err['details']}")

with open('filled.pdf', 'wb') as f:
    f.write(r.content)

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "mime/multipart"
    "net/http"
    "os"
)

func fillForm() error {
    pdfBytes, err := os.ReadFile("invoice-template.pdf")
    if err != nil {
        return err
    }

    var body bytes.Buffer
    w := multipart.NewWriter(&body)

    part, err := w.CreateFormFile("pdf", "invoice-template.pdf")
    if err != nil {
        return err
    }
    if _, err := part.Write(pdfBytes); err != nil {
        return err
    }

    fields, _ := json.Marshal(map[string]string{
        "customer_name": "Acme Co",
        "total":         "$1,250.00",
    })
    if err := w.WriteField("fields", string(fields)); err != nil {
        return err
    }
    w.Close()

    req, err := http.NewRequest("POST", "https://pdfops.dev/api/fill-form", &body)
    if err != nil {
        return err
    }
    req.Header.Set("Content-Type", w.FormDataContentType())

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        return err
    }
    defer resp.Body.Close()

    if resp.StatusCode != 200 {
        var apiErr struct {
            Error   string `json:"error"`
            Details string `json:"details"`
        }
        json.NewDecoder(resp.Body).Decode(&apiErr)
        return fmt.Errorf("fill-form failed: %s — %s", apiErr.Error, apiErr.Details)
    }

    out, err := os.Create("filled.pdf")
    if err != nil {
        return err
    }
    defer out.Close()
    _, err = io.Copy(out, resp.Body)
    return err
}

DocRaptor's API accepts document_content (HTML/XML) or document_url and renders the result via PrinceXML. PDFops accepts an existing AcroForm PDF and a JSON of field values. Migration: (1) Take the HTML template you were sending to DocRaptor. (2) Open it in any PDF editor (Acrobat, Mac Preview, LibreOffice Draw, or run it through weasyprint as a one-shot conversion), then save as PDF. (3) Add AcroForm fields at the positions where DocRaptor was substituting your data; name them after the keys you'll send. (4) Replace the DocRaptor SDK call with a multipart POST to /api/fill-form. The HTML template work is one-time; the request shape is now simpler (no per-request Prince render). Side-by-side at /vs/docraptor — includes the dead-changelog signal worth weighing.

PDFShift renders HTML to PDF via Chromium with credit-system pricing. PDFops takes an existing AcroForm PDF + data. Migration mirrors DocRaptor: take your HTML template, save as PDF, add AcroForm fields, swap the API call. PDFShift's strengths (custom fonts, full CSS, modern HTML, image embeds) all transfer to the template-authoring step — you bake them in once at the PDF level instead of paying for them on every render. Once the template is set, you don't need Chromium per request anymore. Side-by-side at /vs/pdfshift.

PDFMonkey uses HTML + Liquid templating with a dashboard editor. PDFops doesn't run a templating engine. Migration: (1) Rebuild each template as a PDF (Acrobat / Mac Preview / LibreOffice Draw) with AcroForm fields where Liquid variables were. (2) Move Liquid-side computed values — loops over line items, conditionals, date formatters, the barcode filter, Chart.js graphs — into your calling code's pre-processing. (3) Replace the PDFMonkey API call with the fill-form curl. If your templates lean heavily on Liquid features, PDFMonkey may still fit better — the honest framing on /vs/pdfmonkey spells out when to stay vs migrate.

Fastest: drop the PDF into the free form-field inspector — it lists every field name, type, and the ready-to-fill JSON. Otherwise, open the PDF in Acrobat (Tools → Prepare Form), Mac Preview, or LibreOffice Draw; field names appear when you hover or click each field. From the command line, pdftk dump_data_fields lists all AcroForm field names. PDF authoring tools name fields automatically (e.g. Text1, CheckBox2); rename them to something predictable in code (customer_name, total) before deploying.

Older versions of /api/fill-form returned PDFs with field values set in the data layer but no /AP (appearance stream), which some viewers render as empty boxes. As of 2026-05-18 the endpoint regenerates appearance streams using an embedded Helvetica, so any AcroForm whose fields reference /Helvetica in their DA renders correctly. If you still see empty fields, the PDF's DA may reference a font we don't have embedded — reply to your key email or write hello@pdfops.dev with the template attached.

No. Flattening bakes the filled values into the page content and removes the AcroForm, so the fields can no longer be clicked, edited, or enumerated in a viewer — the document behaves like a printed page. That prevents casual re-editing and is what most workflows mean by "locking" a filled form. It does not provide tamper evidence (a determined editor can still alter the page content), digital signatures, access control, retention policy, or regulatory compliance. If you need provable integrity, apply a digital signature to the flattened output with a signing tool. Flattened output keeps the byte-determinism contract: the same template and values produce the same bytes.

Five AcroForm field types: PDFTextField, PDFCheckBox, PDFDropdown, PDFRadioGroup, PDFOptionList. PDFButton and PDFSignature are intentionally unsupported (see error unsupported_field_type).

As a string: "true" to check, "false" to uncheck. Boolean JSON values aren't accepted.

No — /api/fill-form fills existing AcroForm fields only. Author your PDF template with the fields you need first.

The middleware returns 429 Too Many Requests with a Retry-After header. 429s don't consume quota. If you're hitting the anonymous 100/IP/month cap, get a free API key at /pricing — 250 requests/month, with paid Indie (4,000) and Pro (25,000) tiers above it.

You sent a fields key that doesn't exist as an AcroForm field name in the uploaded PDF. Field names are case-sensitive and must match exactly. To audit what's actually in your PDF: open it in Acrobat (Tools → Prepare Form), in Mac Preview (the fields panel on the right), or run pdftk yourfile.pdf dump_data_fields | grep ^FieldName from the command line. Typical causes: typos (customer_Name vs customer_name), emoji in PDF authoring-tool defaults ("First Name 🚀"), or sending fields from a different template version. The endpoint refuses to silently skip unknown fields because that hides real wiring bugs — safer to fail loudly than fill the wrong PDF.

pdf-lib couldn't generate the appearance stream for one of your filled fields, usually because the field's DA (default appearance) references a font that isn't embedded in the AcroForm's DR (default resources). PDFops auto-embeds Helvetica before regenerating appearances, so this should be rare; when it fires, it usually means the template was authored in a tool that wrote a non-standard font reference (e.g., a custom corporate font with no fallback). Workaround: re-author the template in Acrobat or LibreOffice Draw, which will set the DA to /Helvetica by default. Retryable as 500 if the cause is transient.

The uploaded PDF doesn't have an AcroForm dictionary — it's a PDF you can view + print but not fill. To add fillable fields: open in Acrobat (Tools → Prepare Form → Add fields manually), in LibreOffice Draw (Form Controls toolbar), or use pdftk to add a form layer. If you want a working sample to start from, grab the sample invoice-template.pdf — it has customer_name + total fields you can fill via the curl example above. If you're getting no_form on a PDF you authored with form fields, double-check the save format: "Save as PDF" in some tools drops the form layer; use "Save as PDF/A-2" or explicit "Preserve AcroForm" options.

One of your fields values isn't a string — the API requires every value to be a JSON string regardless of underlying type. Common offenders: numbers ("total": 1250.0 → should be "$1,250.00" after formatting), booleans ("agreed": true → should be "true" for checkboxes), and arrays/objects. Format server-side before serializing: String(amount.toFixed(2)) for currency, String(date.toISOString().slice(0,10)) for ISO dates, String(boolean) for booleans. The string-only constraint is intentional — AcroForm field values are themselves strings in the PDF spec, and accepting native JSON types would force the endpoint into stringify-with-locale-rules territory.