DEV Community: PDFops

A fixed-row invoice template, and the line item that doesn't fit

PDFops — Thu, 15 Oct 2026 13:09:03 +0000

An invoice template with an AcroForm has a fixed number of line-item rows baked in at authoring time: ten fields named item_1 through item_10, say, each paired with a qty_N and price_N. That works until an order has eleven items, and then the eleventh one has nowhere to go. The API will fill the ten fields you send it without complaint; it just has no field named item_11 to put the eleventh row into.

Why a template can't grow a row on request

The AcroForm spec doesn't have a concept of a repeating row. A field is a fixed object at a fixed position on a fixed page, placed there when the PDF was authored in Acrobat or LibreOffice Draw. Adding a field at request time isn't on the table either: /api/fill-form only fills fields that already exist in the uploaded PDF, and a field name it doesn't recognize comes back as a 400 unknown_field rather than a new row appearing on the page. So an invoice with a variable number of items needs a different shape of template, not a bigger one.

Split into pages, not rows

The fix is a one-page continuation template with the same ten row fields as the main page, minus the header and the totals block, and a running count instead of a hard limit. Eleven items becomes two filled pages: the main template holds items one through ten, the continuation template holds item eleven alone, and the two get merged in page order. Thirty items becomes a main page plus two full continuation pages. The row count per page stays fixed; what varies is how many pages get generated and merged.

Totals only go on the last page

If every continuation page repeats a running subtotal, a customer glancing at page two of three sees a number that looks like the invoice total but isn't, and that's a worse failure than a plain unlabeled row. Compute the grand total once, from the full line-item list, and only pass it into the fields payload for whichever page turns out to be last; every other continuation page gets its ten row fields and nothing else.

The script

Chunking the items into pages of ten, building a fields payload per chunk, and calling fill-form once per chunk is the whole algorithm. The main template and the continuation template are two different PDF files on disk, so the loop picks whichever one matches the current chunk's position, fills it, and collects the resulting buffer. Once every chunk has been filled, one call to /api/merge with the buffers in order produces the finished invoice, main page first, continuation pages after it in the same order the items appeared in.

import { readFile } from "node:fs/promises";

const API_KEY = process.env.PDFOPS_API_KEY;
const ROWS_PER_PAGE = 10;

function chunk(items, size) {
  const out = [];
  for (let i = 0; i < items.length; i += size) out.push(items.slice(i, i + size));
  return out;
}

function rowFields(items) {
  const fields = {};
  items.forEach((item, i) => {
    fields[`item_${i + 1}`] = item.name;
    fields[`qty_${i + 1}`] = String(item.qty);
    fields[`price_${i + 1}`] = item.price.toFixed(2);
  });
  return fields;
}

async function fillPage(templatePath, fields) {
  const template = await readFile(templatePath);
  const form = new FormData();
  form.append("pdf", new Blob([template]), "template.pdf");
  form.append("fields", JSON.stringify(fields));
  form.append("flatten", "true");
  const res = await fetch("https://pdfops.dev/api/fill-form", {
    method: "POST",
    headers: { "X-API-Key": API_KEY },
    body: form,
  });
  if (!res.ok) throw new Error(`fill-form failed: ${res.status}`);
  return Buffer.from(await res.arrayBuffer());
}

async function buildInvoice(customer, items) {
  const pages = chunk(items, ROWS_PER_PAGE);
  const total = items.reduce((sum, i) => sum + i.qty * i.price, 0);
  const buffers = [];

  for (let i = 0; i < pages.length; i++) {
    const isFirst = i === 0;
    const isLast = i === pages.length - 1;
    const fields = {
      ...(isFirst ? { customer_name: customer } : {}),
      ...rowFields(pages[i]),
      ...(isLast ? { grand_total: total.toFixed(2) } : {}),
    };
    const templatePath = isFirst ? "./invoice-main.pdf" : "./invoice-continuation.pdf";
    buffers.push(await fillPage(templatePath, fields));
  }

  if (buffers.length === 1) return buffers[0];

  const form = new FormData();
  for (const buf of buffers) form.append("pdf", new Blob([buf]), "page.pdf");
  const res = await fetch("https://pdfops.dev/api/merge", {
    method: "POST",
    headers: { "X-API-Key": API_KEY },
    body: form,
  });
  if (!res.ok) throw new Error(`merge failed: ${res.status}`);
  return Buffer.from(await res.arrayBuffer());
}

A thirty-item order costs four API calls here: three fill-form calls, one per page, and one merge call to stitch the pages together. A ten-item order that fits on the main page alone costs one fill-form call and no merge call, since buffers.length === 1 skips straight to returning the single filled page.

Try it

A free key from /docs/signup covers this comfortably: a ten-row template split across a couple of continuation pages per invoice is two or three calls, well inside the 250 a month a free key includes, enough to test the chunking logic against a real template before wiring it into an order pipeline.

The 4.5 MB request limit that breaks a working PDF merge on Vercel

PDFops — Thu, 08 Oct 2026 13:09:22 +0000

A PDF merge endpoint that works every time on a laptop can start returning 413 the moment it moves onto Vercel, with no body in the response to explain why. The input files look reasonable, the handler code hasn't changed, and the identical request against a local dev server still succeeds. The cause is a cap on the whole request body that Vercel enforces before a serverless function's own code runs at all, so no amount of debugging inside the handler will find it. The handler never gets invoked.

What actually happens at 4.5 MB

Vercel's Serverless Functions reject any request body over 4.5 MB (4,718,592 bytes) with a 413 and the status FUNCTION_PAYLOAD_TOO_LARGE, confirmed against a live production deployment. That rejection happens at the platform layer, ahead of the function's own code, so a try/catch wrapped around the handler's body-parsing logic has nothing to catch; the request never reaches it. The limit applies to the whole body regardless of how it's packaged, so a multipart upload with three PDFs attached counts all three files together against one shared 4.5 MB ceiling, not against three separate per-file limits.

Why local testing never catches it

A local dev server rarely enforces any size limit on its own. Express and Node's built-in http server will accept a multipart body of pretty much any size by default, so a handler tested with curl against localhost:3000 swallows a 10 MB upload without complaint. Deploy the same code to Vercel and the identical curl command against the production URL comes back 413 before the handler's first line runs. The gap between working in dev and failing in prod comes from a platform behavior that only exists once the request leaves localhost, so a local test suite built around the dev server will pass cleanly right up until the first real deploy with a big enough file.

Size the request before you send it

Since the rejection carries no detail about which file or how far over the limit the request was, the cheaper fix is a client-side check that runs before the request goes out at all, so a caller gets a specific error instead of an opaque 413:

const MAX_REQUEST_BYTES = 4.5 * 1024 * 1024;

function assertFitsRequestLimit(files) {
  const total = files.reduce((sum, f) => sum + f.size, 0);
  if (total >= MAX_REQUEST_BYTES) {
    throw new Error(
      `request would be ${(total / 1024 / 1024).toFixed(1)} MB; ` +
      `the platform rejects anything at or above 4.5 MB`,
    );
  }
}

That check needs to run against the exact bytes going over the wire, including multipart boundaries and any other form fields riding along with the files, since those count toward the same 4.5 MB ceiling too.

Chaining calls instead of raising the limit

There's no project setting on Vercel that raises this particular cap; it's fixed at the platform level for Serverless Functions on every plan. For a merge of more than a handful of PDFs, the practical fix is to stop trying to fit the whole job into one request and chain calls instead: merge the first batch that fits under the limit, feed that single merged result back in as one more input alongside the next batch, and keep going until every file has been folded in.

async function mergeAll(apiKey, pdfBuffers, maxBytes = 4 * 1024 * 1024) {
  let merged = null;
  let batch = [];
  let batchBytes = 0;

  for (const buf of pdfBuffers) {
    if (batch.length && batchBytes + buf.length > maxBytes) {
      merged = await mergeBatch(apiKey, merged ? [merged, ...batch] : batch);
      batch = [];
      batchBytes = 0;
    }
    batch.push(buf);
    batchBytes += buf.length;
  }

  return mergeBatch(apiKey, merged ? [merged, ...batch] : batch);
}

async function mergeBatch(apiKey, buffers) {
  const form = new FormData();
  for (const buf of buffers) {
    form.append("pdf", new Blob([buf]), "input.pdf");
  }
  const res = await fetch("https://pdfops.dev/api/merge", {
    method: "POST",
    headers: { "X-API-Key": apiKey },
    body: form,
  });
  if (!res.ok) throw new Error(`merge batch failed: ${res.status}`);
  return Buffer.from(await res.arrayBuffer());
}

Each call stays well under the per-request ceiling because the batch size is capped before it's sent, and the running merged result only ever travels as one file per step instead of growing the whole input set into a single oversized request.

How PDFops surfaces this instead of a bare 413

PDFops' own /api/merge and /api/fill-form sit on the same 4.5 MB line Vercel enforces, but reject early with a JSON body instead of an empty platform 413:

{
  "error": "request_too_large",
  "details": "request body exceeds 4.5 MB"
}

That check runs as middleware before the body is buffered, so a caller gets request_too_large with a clear reason instead of a bare 413 with nothing in the body to act on. The per-PDF cap sits at 4 MB and the merge endpoint takes up to 20 files, so the same batching approach above applies directly: chain /api/merge calls for anything that won't fit in one request.

Try it

A free key from /docs/signup includes 250 calls a month with no card, enough to try a batch of real PDFs against /api/merge and see the 4.5 MB boundary and the request_too_large response firsthand.

Flattening a filled PDF form with pypdf, and the method that doesn't exist

PDFops — Thu, 01 Oct 2026 13:11:27 +0000

pypdf fills AcroForm fields without complaint: set a value, call write(), and a compliant viewer shows the string in the field. What ships in that output PDF is still a form. Every field a script just filled stays interactive, so a person can click into it and change what was just set, and a lot of downstream systems that scan a PDF for stray AcroForm fields will flag it as unfinished. Flattening is the step that removes that: bake each field's current value into the page content, delete the field and its widget, and the document behaves like a printed page instead of a form someone forgot to lock.

What pypdf calls flatten() is a different operation

Reach for the obvious name and pypdf's PdfWriter has no public flatten() method at all. It does carry a private _flatten(), and its own docstring warns against assuming what it does:

>>> from pypdf import PdfWriter
>>> [m for m in dir(PdfWriter()) if "flat" in m.lower()]
['_flatten', '_flatten_leaf_page', '_flatten_page_tree_node', 'flattened_pages']

"Flattening a PDF also means combining all the contents into one single layer and making the file less editable" is the exact note pypdf's maintainers left to distinguish their _flatten() from that other meaning. Their version flattens the page tree. It copies inherited attributes like /Resources and /MediaBox down from parent nodes onto each page object, which speeds up page lookups and has nothing to do with form fields.

Filling still works, baking doesn't

from pypdf import PdfReader, PdfWriter

reader = PdfReader("w9.pdf")
writer = PdfWriter()
writer.append(reader)

writer.update_page_form_field_values(
    writer.pages[0],
    {"full_name": "Jordan Rivera"},
    auto_regenerate=False,
)

with open("filled.pdf", "wb") as f:
    writer.write(f)

That output has the right text sitting in the right box in every viewer tested. It also still carries an /AcroForm dictionary and an /Annots entry pointing at a live text field widget, both readable straight back out through PdfReader(...).get_fields(). pypdf has no further method to call that removes them.

pdftk's flatten does the job, when you can run it

pdftk has shipped a flatten operation since its earliest releases, and running it against the file above closes that gap:

pdftk filled.pdf output flattened.pdf flatten

Run that and PdfReader("flattened.pdf").get_fields() comes back empty, /Annots comes back None, and the name renders as plain page content in every viewer tested. For a script running on a machine where pdftk is already installed, that one line is the rest of the job pypdf leaves undone.

The part that breaks on Lambda, Vercel, or a Worker

pdftk is a Java program wrapped in a shell script, so using it means shipping a JRE alongside the code, not a small binary vendored into a zip. AWS Lambda carries no system Java by default and needs a custom layer with both the JRE and the pdftk jar; Vercel's serverless functions run into the same shape of problem, and Cloudflare Workers can't run it at all, because a V8 isolate has no subprocess to shell out to in the first place. The same constraint that forced the wkhtmltopdf-on-Lambda migration applies here: a tool that works fine on a laptop can be unusable on the runtime a PDF actually needs to run on.

One call instead

PDFops' /api/fill-form takes a flatten parameter directly, so the fill-and-bake step that needs pdftk locally becomes one HTTP call instead, with no JRE to package and no subprocess to shell out to:

curl -X POST https://pdfops.dev/api/fill-form \
  -H "X-API-Key: $PDFOPS_KEY" \
  -F "pdfFile=@w9.pdf" \
  -F 'fields={"full_name":"Jordan Rivera"}' \
  -F "flatten=true" \
  -o filled.pdf

The response is the flattened PDF itself, with no AcroForm or Annots left to query, built on a Helvetica appearance pass that runs the same way whether flatten is set or not. Flattening here is cosmetic: it stops casual re-editing in a viewer, not tamper evidence or a digital signature, so pair it with an actual signing step if a filled PDF needs to prove it wasn't altered afterward.

Try it

A free key from /docs/signup includes 250 fills a month with no card, enough to try flatten=true against a real template before wiring it into anything bigger.

Merging a Letter invoice with an A4 attachment in pypdf, and the page size nobody normalizes

PDFops — Thu, 24 Sep 2026 13:07:36 +0000

pypdf's writer.append() concatenates PDFs page by page and copies each page's own /MediaBox along with it. Merge a US Letter invoice (612x792pt) with an A4 attachment (595x842pt) and the output has two page sizes, not one. Most viewers render that fine, each page at its own size. A print queue set to "same size as first page," a thumbnail generator, or a batch rasterizer that assumes one page size for the whole document can scale or crop the second page as if it were the first.

What /MediaBox actually is

/MediaBox is a rectangle stored per page inside a PDF's page tree, not once for the whole document. A PDF has no page-size property to read off the file as a whole; every page carries its own, and two pages in the same file are free to disagree. pypdf mirrors that structure. page.mediabox reads the page's own rectangle, and nothing in the library reconciles it against any other page already sitting in the writer.

Reproducing the mismatch

Build two single-page PDFs at different sizes and merge them with append(). Reading page.mediabox back off each page in the result shows exactly what went in: page 0 at 612x792, page 1 at 595.32x841.92. Nothing warns about the mismatch and nothing normalizes it, because normalizing was never part of the job append() does.

from pypdf import PdfReader, PdfWriter

invoice = PdfWriter()
invoice.add_blank_page(width=612, height=792)       # US Letter
invoice.write("invoice.pdf")

attachment = PdfWriter()
attachment.add_blank_page(width=595.32, height=841.92)  # A4
attachment.write("attachment.pdf")

merged = PdfWriter()
for path in ("invoice.pdf", "attachment.pdf"):
    merged.append(PdfReader(path))
merged.write("merged.pdf")

check = PdfReader("merged.pdf")
for i, page in enumerate(check.pages):
    print(i, page.mediabox.width, page.mediabox.height)
# 0 612.0 792.0
# 1 595.32 841.92

Why a viewer hides it and a rasterizer doesn't

A human scrolling through the merged file in Preview or Acrobat will not notice anything wrong. Each page renders at its own size, the way a PDF is supposed to. The trouble shows up one step downstream, in anything built around the assumption that a document has a single page size: a print dialog's "fit to same size as first page" option, a thumbnail grid sized off page one, a rasterizer that renders every page at one fixed DPI-and-dimension pair for a PNG export. Those tools scale or crop the second page to match the first, and an A4 attachment merged after a Letter invoice comes out stretched or clipped in exactly the places that matter.

Normalizing to one page size before merging

The fix is to normalize page size before merging, not after. Create a blank page at the target size, then merge the mismatched page's content onto it through a scale-and-center transform. pypdf's Transformation and PageObject.merge_transformed_page do the actual work; the function below just computes the scale factor that fits the source page inside the target rectangle without distorting its aspect ratio, and the translation that centers it.

from pypdf import PageObject, PdfReader, PdfWriter, Transformation

LETTER = (612, 792)

def fit_to_letter(page):
    src_w = float(page.mediabox.width)
    src_h = float(page.mediabox.height)
    scale = min(LETTER[0] / src_w, LETTER[1] / src_h)
    tx = (LETTER[0] - src_w * scale) / 2
    ty = (LETTER[1] - src_h * scale) / 2

    blank = PageObject.create_blank_page(width=LETTER[0], height=LETTER[1])
    transform = Transformation().scale(scale, scale).translate(tx, ty)
    blank.merge_transformed_page(page, transform)
    return blank

reader = PdfReader("attachment.pdf")
fixed_attachment = fit_to_letter(reader.pages[0])

writer = PdfWriter()
writer.add_page(PdfReader("invoice.pdf").pages[0])
writer.add_page(fixed_attachment)
writer.write("merged.pdf")

Run fit_to_letter on the A4 page before appending it and both pages in the merged output report 612x792. The attachment's content is scaled down slightly and letterboxed rather than stretched to fill a rectangle it was never drawn for, which is the difference between "smaller but legible" and "the wrong aspect ratio."

Try it

/api/merge concatenates pages the same way pypdf's append() does: each input page keeps whatever size it already had, and the endpoint does not resize anything for you. That is the correct default for most callers, since resizing without being asked would silently alter content nobody meant to touch. If you need one uniform page size in the output, normalize each page first with the transform above, then send the normalized files to /api/merge. A free key from /docs/signup covers 250 calls a month, and /api/inspect reads back page dimensions along with field names if you want to check sizes before merging rather than after.

Giving an AI agent PDF tools over MCP, and why it has to inspect before it fills

PDFops — Thu, 17 Sep 2026 13:05:32 +0000

MCP (Model Context Protocol) lets an agent call a tool directly instead of you writing the client code that calls an API on the agent's behalf. For PDF forms that convenience runs into the same problem pypdf developers hit by hand: a fill call needs the form's exact field names, and an agent guessing at them from a filename or a user's request gets it wrong in the same silent way a person does. pdfops-mcp handles this by shipping a tool whose entire job is answering "what fields does this PDF actually have," and documenting, in the tool description itself, that it has to be called before pdf_fill. An agent reads tool descriptions as instructions, not just documentation, so that ordering is enforced in the one place the agent actually reads.

What pdf_inspect gives the agent

pdf_inspect takes a PDF source and returns its AcroForm fields: name, type, options for a dropdown or radio group, current value, and a per-field maxLength where the PDF declares one. It also returns a fillTemplate object shaped exactly like what pdf_fill expects, so the agent has a paste-ready starting point instead of assembling one from the field list by hand. Run against a W-9 template, the response for one field looks like this:

{
  "name": "name",
  "type": "text",
  "maxLength": 60,
  "value": ""
},
{
  "name": "tax_classification",
  "type": "radio",
  "options": ["individual", "c_corp", "s_corp", "partnership", "llc", "other"],
  "value": ""
}

Neither of those names is guessable from "the W-9 form." A model filling this blind would reach for something like full_name or entity_type, both of which are wrong for this specific template and would fail the same way a hand-written script fails on a field name that doesn't exist. The tool description on pdf_fill spells this out directly: field names must exist in the PDF, values over a field's maxLength are rejected, and checkboxes take a plain "true" or "false" string rather than whatever on-state name the PDF happens to use internally.

Wiring it in

For Claude Code, adding the server is one command:

claude mcp add pdfops -- npx -y pdfops-mcp

Claude Desktop and Cursor take the same package through a config file instead:

{
  "mcpServers": {
    "pdfops": {
      "command": "npx",
      "args": ["-y", "pdfops-mcp"],
      "env": { "PDFOPS_API_KEY": "pdfops_live_…" }
    }
  }
}

The API key is optional. Without one the server runs on the keyless trial (100 requests per IP per month); a free key from /docs/signup raises that to 250 a month with no card. Either way the agent now has five tools: pdf_inspect, pdf_fill, pdf_merge, pdf_invoice, and pdfops_usage for checking remaining quota mid-session.

A two-step request, three tool calls

Ask the agent to "fill the W-9 at ~/docs/w9.pdf for the contractor and merge it with the signed cover sheet," and the tool sequence is pdf_inspect to read back the real field names, pdf_fill with those names to write the filled copy, then pdf_merge to combine it with the cover sheet in order. All three take plain file paths when the server runs next to the agent. npx pdfops-mcp under Claude Code or Claude Desktop starts as a local process over stdio, so it reads and writes the same filesystem the agent does, and the PDF bytes themselves never pass through the model's context window at all. The agent only ever sees field names, a confirmation string, and a path.

The part that breaks on a hosted server

That local-path convenience assumes the MCP server and the agent share a filesystem. Run the same server on a hosted gateway, such as Smithery, Glama's hosted mode, or a cloud IDE's remote MCP client, and ~/docs/w9.pdf stops meaning anything, because it names a path on the machine the agent is running on, not the machine the server is running on. A file path handed to a remote server just fails to open. pdfops-mcp's pdf_path and pdf_paths arguments accept an https:// URL or a data:application/pdf;base64,… URI as well as a local path, and every tool that produces a PDF returns it inline as an embedded resource whenever output_path is omitted, rather than assuming there's somewhere on that machine worth writing it. Nothing in the config changes between local and hosted mode: the server just checks what kind of string it got handed and resolves it accordingly.

Try it

The same pdf_inspect → pdf_fill → pdf_merge sequence is also three plain HTTP calls if you'd rather wire an agent up yourself: /api/inspect, /api/fill-form, and /api/merge, all under one X-API-Key header from a free key at /docs/signup. But for anything already running inside Claude Code, Claude Desktop, or Cursor, npx -y pdfops-mcp skips writing that client entirely: the agent just gets the tools.

Filling a checkbox with pypdf, and the on-state string it never validates

PDFops — Thu, 10 Sep 2026 13:13:17 +0000

pypdf's update_page_form_field_values() will set a checkbox's value without checking whether the value you passed means anything. Pass the wrong on-state string, one that doesn't exist anywhere in that field's appearance dictionary, and the call returns normally, the field looks filled if you read it back with get_fields(), and the box still renders unchecked in every viewer. No exception, no log line, not even at DEBUG level. Four common inputs trigger it: "Yes" without the leading slash, "true", "1", and the Python boolean True. Only the exact string the field's own appearance dictionary defines actually checks the box.

What actually decides whether a box looks checked

An AcroForm checkbox carries two things that have to agree: the field's value (/V) and the widget's appearance state (/AS). A viewer renders whichever appearance stream /AS points to, out of the ones listed in the widget's /AP /N dictionary. The PDF spec never mandates a name for the checked state. /Yes is the common convention because Acrobat's own form wizard writes it, but a PDF built in a different tool can use /On, /1, or a name its author chose. There is no universal on value for a checkbox, only whatever key sits in that specific field's own appearance dictionary next to /Off.

Reproducing the silent no-op

Take a one-field test PDF whose checkbox agree_to_terms really uses /Yes as its on-state, confirmed by reading _States_ off the field: ['/Off', '/Yes']. Running update_page_form_field_values() with auto_regenerate=False for the values "Yes", "true", "1", and True leaves /V and /AS at /Off every time, on pypdf 6.18.0. Only {"agree_to_terms": "/Yes"}, matching the field's real on-state string exactly, sets both to /Yes. The function returns None, so there is nothing in the call to check for success, and nothing gets logged either way.

from pypdf import PdfReader, PdfWriter

reader = PdfReader("consent-form.pdf")
writer = PdfWriter()
writer.append(reader)

# Every one of these looks reasonable. None of them checks the box.
for value in ["Yes", "true", "1", True]:
    writer.update_page_form_field_values(
        writer.pages[0], {"agree_to_terms": value}, auto_regenerate=False,
    )
    print(value, "->", writer.get_fields()["agree_to_terms"].get("/V"))
    # /Off, every single time. No exception, no warning.

# Only the field's own on-state string checks it.
writer.update_page_form_field_values(
    writer.pages[0], {"agree_to_terms": "/Yes"}, auto_regenerate=False,
)
print(writer.get_fields()["agree_to_terms"].get("/V"))  # /Yes

Reading the real on-state before you fill

The fix is to stop guessing at the on-state name and read it off the field instead. reader.get_fields() exposes it as _States_, a list where one entry is always /Off and the other is the string that actually checks the box; the widget annotation's own /AP /N keys carry the same string for anyone working at that lower level. Either way, the value passed to update_page_form_field_values has to come from the PDF itself, never from a hardcoded /Yes or a stringified boolean, because the on-state name belongs to that specific template, not to the file format in general.

reader = PdfReader("consent-form.pdf")
fields = reader.get_fields()

on_state = next(
    s for s in fields["agree_to_terms"]["/_States_"] if s != "/Off"
)

writer = PdfWriter()
writer.append(reader)
writer.update_page_form_field_values(
    writer.pages[0], {"agree_to_terms": on_state}, auto_regenerate=False,
)

The default that trades one bug for a viewer-dependent one

update_page_form_field_values defaults auto_regenerate to True, and that default sets NeedAppearances on the whole document's AcroForm dictionary rather than baking the checkbox's new appearance into the file at write time. NeedAppearances tells a conforming viewer to regenerate every field's appearance itself when the document opens, so rendering moves from decided once, at fill time, to decided per viewer, on every open. Acrobat honors the flag. A number of other renderers, including some used in headless pipelines, do not regenerate anything and just show whatever appearance stream was already baked in, which for a field filled this way can mean no visible change at all.

What that breaks beyond checkboxes

That reaches past checkboxes for anyone testing generated PDFs by hashing them. A document with NeedAppearances set can render two different ways depending on which engine opens it, and that undercuts the premise behind hashing a PDF and diffing it in CI: the bytes match, but a screenshot or a downstream re-render is not guaranteed to. auto_regenerate=False avoids planting that flag, at the cost of handling any appearance-stream work pypdf does not bake in on its own.

Try it

None of this is specific to a checkbox filled by hand. It is why /api/fill-form takes a plain "true" or "false" string for any checkbox field, resolves the real on-state name internally, and bakes a fresh appearance stream into the response PDF instead of setting NeedAppearances and leaving the outcome to whichever viewer opens the file next. A free key from /docs/signup covers 250 calls a month, and /docs/inspect reads back a template's real field names and types first, checkboxes included, so there is no need to go spelunging through _States_ by hand at all.

Packing-slip PDFs from a fulfillment webhook, and the redelivery that duplicates them

PDFops — Thu, 03 Sep 2026 13:08:55 +0000

A fulfillment webhook that fires when an order ships doesn't promise to fire exactly once. Most providers document at-least-once delivery, so a timeout on your side, a 5xx from a cold start, or a stray network blip triggers a retry with the same payload, sometimes seconds later, sometimes minutes. A packing-slip handler that calls PDFops fill-form on every delivery fills the same slip twice, burns quota twice, and sometimes emails a customer the same document twice. Fixing it takes one atomic claim on the event id, checked and set in a single round trip, so the second delivery learns someone already has it before doing any of that work again.

The shape of the job

Say a small 3PL runs packing slips off its warehouse system's order-shipped webhook: an order ships, the webhook fires with the order number, the shipping address, and the line items, and a Vercel Function fills a packing-slip template through PDFops, uploads the result to Vercel Blob, and returns the URL so the warehouse UI can show a print button. One order should produce one slip, no matter how many times the webhook decides to tell you about it.

At-least-once means sometimes-twice

Webhook providers rarely guarantee exactly-once delivery, because guaranteeing it would mean holding a distributed lock across every subscriber before confirming an event even landed. What they promise instead is at-least-once: if your endpoint doesn't answer with a fast 2xx, the event goes back into a retry queue and fires again, carrying the same event id and the same body. A five-second cold start on a rarely-hit Function, a transient 502 from your own upstream, or a provider retry policy that fires on any non-2xx response are each enough to trigger a second delivery of an event your handler already finished.

A single atomic claim, not two separate steps

The obvious first attempt reads: check a table for this event id, and if it's missing, do the work and insert a row. Under a single delivery that's correct. Under two deliveries that arrive close together, both requests can pass the check before either one finishes the insert, and both go on to call fill-form. The fix is to make the check and the reservation the same operation. A SET with NX (set only if the key doesn't already exist) is atomic in Redis, so exactly one of two concurrent requests gets back confirmation that it won the claim.

The handler

Everything above collapses into a route handler and a small helper, reachable from a Vercel Function over Upstash's REST API without pinning a TCP connection to a serverless invocation.

// app/api/webhooks/fulfillment/route.ts
import { Redis } from '@upstash/redis';
import { put } from '@vercel/blob';

const redis = Redis.fromEnv();
const PDFOPS_KEY = process.env.PDFOPS_API_KEY!;

export async function POST(req: Request) {
  const event = await req.json();
  // Field name varies by provider; use whatever id it signs on the event.
  const claimKey = `packing-slip:${event.id}`;

  const claimed = await redis.set(claimKey, 'in_progress', {
    nx: true,
    ex: 60, // clears itself if the handler crashes before finishing
  });

  if (claimed !== 'OK') {
    const state = await redis.get<string>(claimKey);
    if (state === 'in_progress') {
      // A concurrent delivery already owns this event; let the
      // provider's own retry backoff handle the wait.
      return new Response(null, { status: 409 });
    }
    // state holds the URL from a run that already finished.
    return Response.json({ url: state });
  }

  try {
    const url = await generatePackingSlip(event.order);
    await redis.set(claimKey, url, { ex: 60 * 60 * 24 * 30 }); // keep 30 days
    return Response.json({ url });
  } catch (e) {
    await redis.del(claimKey); // let the next redelivery try again
    throw e;
  }
}

async function generatePackingSlip(order: {
  number: string;
  shipTo: string;
  items: { qty: number; sku: string }[];
}): Promise<string> {
  const template = await fetch(process.env.PACKING_SLIP_TEMPLATE_URL!).then(
    (r) => r.arrayBuffer(),
  );
  const form = new FormData();
  form.set('pdf', new Blob([template], { type: 'application/pdf' }), 'template.pdf');
  form.set(
    'fields',
    JSON.stringify({
      order_number: order.number,
      ship_to: order.shipTo,
      items: order.items.map((i) => `${i.qty}x ${i.sku}`).join('\n'),
    }),
  );
  form.set('flatten', 'true');

  const res = await fetch('https://pdfops.dev/api/fill-form', {
    method: 'POST',
    headers: { 'X-API-Key': PDFOPS_KEY },
    body: form,
  });
  if (!res.ok) {
    const err = await res.json();
    throw new Error(`fill-form failed: ${err.error} (${err.details})`);
  }
  const pdf = await res.arrayBuffer();
  const blob = await put(`packing-slips/${order.number}.pdf`, pdf, {
    access: 'public',
    contentType: 'application/pdf',
  });
  return blob.url;
}

The claim key carries three possible states over its life: absent (no delivery has touched this event yet), in_progress (a delivery is mid-flight, held under a short expiry so a crash doesn't wedge it forever), and a stored URL (the run that finished, kept for a month so a very late redelivery gets the same answer instead of a second document). A redelivery that lands while the first is still working gets a 409 back; a redelivery that lands after success gets the URL straight back, with no call to fill-form made at all.

Releasing a claim that never finished

A handler that crashes mid-fill, say because the template fetch times out, leaves its claim in the in_progress state until the expiry clears it. That's why the TTL matters: pick it to comfortably exceed the slowest real run, short enough that a genuine crash doesn't block a legitimate retry for long. The catch block also deletes the claim directly on a known failure, so a clean error doesn't have to wait out the timer at all before the next delivery can try again.

Try it

The same claim pattern covers any webhook-triggered document: an invoice on payment succeeded, a contract on signature completed, a statement on billing cycle closed, anywhere a provider might redeliver an event your handler already finished. A free key from /docs/signup covers 250 calls a month, worth protecting from accidental doubles for exactly the reason above: a duplicate fill on a retried webhook is quota spent on a document nobody asked for twice. Check usage anytime at /docs/usage or the dashboard, and confirm a template's field names at /docs/inspect before wiring the fields object above to your own PDF.

Filling a PDF from a Python Lambda with no dependencies to package

PDFops — Thu, 27 Aug 2026 13:08:59 +0000

A Python Lambda that fills a PDF usually reaches for one of two things: a native library like pypdf, or the requests package wrapping an HTTP call. Both work, and both come with something to package: pypdf means owning appearance streams and checkbox on-state names yourself, and requests means installing a wheel into the deployment zip or a Lambda layer before the first invocation ever runs. Here's a fill that skips both, using only urllib.request and json from the standard library, plus a multipart body built by hand. Nothing to pip install, nothing to vendor, nothing to test against Amazon Linux's binary compatibility before it works in Lambda.

The shape of the job

Say a small insurance brokerage wants certificates of insurance generated on demand. A client hits an API Gateway endpoint with a policy number, the holder's name, and a coverage date; a Lambda function pulls a fixed COI template from S3, fills three AcroForm fields, and writes the result back to S3 for the client to download. The template stays the same from request to request. Only the values change.

Why the standard library is enough here

The friction with PDF work on Lambda tends to be the same friction twice, once for the PDF library and once for the HTTP client. A local fill library that flattens forms typically shells out to pdftk or poppler, and neither one ships in the Lambda runtime, so flattening turns into a container image or a custom layer just to run one binary. An HTTP client like requests isn't in the runtime either; it needs a pip install into the deployment package, and its compiled dependencies carry version quirks against Amazon Linux worth avoiding when a bare urllib.request call does the same job.

A single multipart POST to a hosted fill endpoint moves the PDF work off the Lambda entirely: the appearance streams, the checkbox states, and the flattening all run server-side, and the only local code is one HTTP request assembled from modules already sitting in every Python 3 Lambda runtime.

Building the multipart body by hand

multipart/form-data is a plain wire format: a boundary string repeated between parts, a Content-Disposition header naming each field, and the raw file bytes with no transfer encoding applied. Reproducing it without a library is short.

import uuid

def build_multipart(fields, file_bytes, filename):
    boundary = uuid.uuid4().hex
    parts = []
    for name, value in fields.items():
        parts.append(
            f"--{boundary}\r\n"
            f'Content-Disposition: form-data; name="{name}"\r\n\r\n'
            f"{value}\r\n"
        )
    parts.append(
        f"--{boundary}\r\n"
        f'Content-Disposition: form-data; name="pdf"; filename="{filename}"\r\n'
        f"Content-Type: application/pdf\r\n\r\n"
    )
    header = "".join(parts).encode("utf-8")
    footer = f"\r\n--{boundary}--\r\n".encode("utf-8")
    return header + file_bytes + footer, boundary

Three things worth pointing at. The field carrying the template is named pdf, matching the API's multipart schema exactly, a detail that's easy to get wrong copying from an example that used a different name. fields is a JSON string, not a nested multipart structure, so the whole dict gets json.dumps'd into one text part. And flatten travels as the literal string "true", since the endpoint reads it off a multipart field where there's no such thing as a JSON boolean.

The Lambda handler

The handler pulls the template from S3 once per invocation, fills it, and writes the result back under a fresh key.

import json
import os
import urllib.error
import urllib.request
import uuid

import boto3

BUCKET = os.environ["COI_BUCKET"]
TEMPLATE_KEY = "templates/coi-template.pdf"
API_KEY = os.environ["PDFOPS_API_KEY"]

s3 = boto3.client("s3")

def fill_certificate(holder_name, policy_number, effective_date):
    template = s3.get_object(Bucket=BUCKET, Key=TEMPLATE_KEY)["Body"].read()
    fields = {
        "fields": json.dumps({
            "holder_name": holder_name,
            "policy_number": policy_number,
            "effective_date": effective_date,
        }),
        "flatten": "true",
    }
    body, boundary = build_multipart(fields, template, "coi-template.pdf")

    req = urllib.request.Request(
        "https://pdfops.dev/api/fill-form",
        data=body,
        method="POST",
        headers={
            "X-API-Key": API_KEY,
            "Content-Type": f"multipart/form-data; boundary={boundary}",
        },
    )
    try:
        with urllib.request.urlopen(req, timeout=25) as res:
            return res.read()
    except urllib.error.HTTPError as e:
        err = json.loads(e.read())
        raise RuntimeError(
            f"PDFops fill-form failed: {err['error']} ({err['details']})"
        ) from e

def handler(event, context):
    payload = json.loads(event["body"])
    pdf_bytes = fill_certificate(
        payload["holder_name"],
        payload["policy_number"],
        payload["effective_date"],
    )

    key = f"certificates/{uuid.uuid4().hex}.pdf"
    s3.put_object(Bucket=BUCKET, Key=key, Body=pdf_bytes, ContentType="application/pdf")
    url = s3.generate_presigned_url(
        "get_object", Params={"Bucket": BUCKET, "Key": key}, ExpiresIn=3600
    )
    return {"statusCode": 200, "body": json.dumps({"url": url})}

The error handling matters as much as the happy path. A non-2xx response raises urllib.error.HTTPError, and PDFops returns { "error": "", "details": "" } on failure, so parsing e.read() into JSON gets you the same error codes the docs list: invalid_api_key if the key in the environment variable got rotated by a later signup, rate_limited with a Retry-After header if the month's quota ran out, or unsupported_field_type if the template's field types changed under you. Surfacing err['error'] in the raised exception means CloudWatch shows which of those happened instead of a bare stack trace from inside urlopen.

Quota, and the shared-IP problem

PDFops allows 100 anonymous requests per IP per month before it needs a key. Lambda functions attached to a VPC often route outbound traffic through a shared NAT gateway, so that IP quota belongs to every function behind the same gateway, not just this one. A key sidesteps the sharing, since usage is tracked per key rather than per IP. POST /api/signup with an email address gets one; the key arrives by email rather than in the response body, so a debug print of the signup response can't leak it into a log. Store it as a Lambda environment variable and pass it as X-API-Key on every request; the free tier covers 250 requests a month, plenty for a brokerage that isn't yet issuing certificates by the hundred.

Try it

The pattern here works for any fixed-template, variable-value PDF: a permit, a receipt, a boarding pass. Sign up for a free key at /docs/signup, check what a template's AcroForm fields are named at /docs/inspect before assuming pdf matches your keys, and watch a key's monthly usage at /docs/usage or the dashboard.

Bulk-filling PDFs from a CSV, and the 429 you shouldn't retry

PDFops — Thu, 20 Aug 2026 13:09:00 +0000

Filling one PDF from a webhook is a solved problem already. Filling three hundred of them from a CSV export is a different job. The API call is identical to the single-fill case. What breaks is everything around it: running out of quota at row 340, or writing a retry loop for a rate limit that resets once a month instead of once a minute.

The shape of the job

Say a workshop cohort of 180 people just wrapped, and everyone gets a completion certificate with their name, the course title, and the date baked into a fixed PDF template. The roster is a CSV export from a registration tool, and the template has three AcroForm fields: attendee_name, course_name, completion_date. The goal is a folder of 180 filled PDFs, a log of which rows failed if any did, and a script that runs the same way next cohort.

Check the quota before you start

GET /api/usage returns tier, limit, used, remaining, and the UTC period it's counting. A free key gets 250 requests a month. Run 180 fills against a key that already used 150 this period, and the result isn't 180 clean failures, it's 100 finished certificates and 80 rows that died partway through a loop with no idea it was about to run dry.

The fix is one request before the loop starts: compare the row count to usage.remaining, and stop before a single file gets written if the batch doesn't fit. A partial run of certificates is worse than no run, because now someone has to work out by hand which 100 of 180 people already have one.

The script

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

const API_KEY = process.env.PDFOPS_API_KEY;
const TEMPLATE_PATH = "./certificate-template.pdf";
const CSV_PATH = "./attendees.csv";
const OUT_DIR = "./out";
const CONCURRENCY = 5;

function parseCsv(text) {
  const [header, ...lines] = text.trim().split("\n");
  const cols = header.split(",").map((c) => c.trim());
  return lines.map((line) => {
    const values = line.split(",");
    return Object.fromEntries(cols.map((c, i) => [c, values[i]?.trim()]));
  });
}

async function checkQuota(rowCount) {
  const res = await fetch("https://pdfops.dev/api/usage", {
    headers: { "X-API-Key": API_KEY },
  });
  const usage = await res.json();
  if (usage.remaining < rowCount) {
    throw new Error(
      `Need ${rowCount} calls, only ${usage.remaining} left ` +
      `(resets ${usage.resets_at}). Not starting a run I can't finish.`
    );
  }
  console.log(`Quota OK: ${usage.remaining}/${usage.limit} left, ${rowCount} rows queued.`);
}

async function fillOne(template, row) {
  const form = new FormData();
  form.append("pdf", new Blob([template]), "template.pdf");
  form.append("fields", JSON.stringify({
    attendee_name: row.name,
    course_name: row.course,
    completion_date: row.date,
  }));
  form.append("flatten", "true");

  const res = await fetch("https://pdfops.dev/api/fill-form", {
    method: "POST",
    headers: { "X-API-Key": API_KEY },
    body: form,
  });

  if (res.status === 429) {
    const err = new Error("rate_limited");
    err.retryAfter = res.headers.get("retry-after");
    err.fatal = true;
    throw err;
  }
  if (!res.ok) {
    return { row, ok: false, error: `${res.status} ${await res.text()}` };
  }

  const bytes = Buffer.from(await res.arrayBuffer());
  const filename = `${row.name.replace(/\s+/g, "_")}.pdf`;
  await writeFile(`${OUT_DIR}/${filename}`, bytes);
  return { row, ok: true };
}

async function run() {
  const [template, csv] = await Promise.all([
    readFile(TEMPLATE_PATH),
    readFile(CSV_PATH, "utf8"),
  ]);
  const rows = parseCsv(csv);
  await checkQuota(rows.length);
  await mkdir(OUT_DIR, { recursive: true });

  const queue = [...rows];
  const results = [];

  async function worker() {
    while (queue.length) {
      const row = queue.shift();
      try {
        results.push(await fillOne(template, row));
      } catch (e) {
        if (e.fatal) {
          console.error(
            `Rate limited mid-run. Retry-After is ${e.retryAfter}s ` +
            `(next calendar month), not worth waiting out. ` +
            `${queue.length + 1} rows unprocessed.`
          );
          const rest = [row, ...queue];
          await writeFile(
            "./unprocessed.csv",
            rest.map((r) => `${r.name},${r.course},${r.date}`).join("\n")
          );
          process.exit(1);
        }
        results.push({ row, ok: false, error: String(e) });
      }
    }
  }

  await Promise.all(Array.from({ length: CONCURRENCY }, worker));

  const failed = results.filter((r) => !r.ok);
  console.log(`${results.length - failed.length}/${results.length} filled.`);
  if (failed.length) {
    console.log("Failed rows:", failed.map((f) => f.row.name).join(", "));
  }
}

run();

Five things worth pointing at. The template PDF is read from disk once and reused for every request. fields is a JSON string inside the multipart body, matching what the endpoint expects, and flatten is literally the string "true": the API reads it off a multipart field, so a JSON boolean fails the type check silently. Five workers pull from a shared queue instead of firing 180 requests at once, which keeps the concurrency under your own control rather than whatever the server or your terminal can absorb. And a failed row lands in the results array instead of throwing, so one malformed CSV line doesn't take down 179 good ones with it.

The 429 that isn't worth retrying

Every PDFops rate-limit response carries a Retry-After header, and the instinct on seeing a 429 is to write a backoff loop: wait, retry, wait longer. That instinct is right for most APIs and wrong for this one. Retry-After here is seconds until the next calendar month, because quota resets on a monthly period rather than a sliding window. Hit the limit on the 3rd and the header can read past two million seconds. A batch script that dutifully awaits that value looks like it's still working for three and a half weeks.

The right move on a 429 mid-run is to stop, log which rows didn't get processed, and exit. The pre-flight quota check above should make this unreachable in normal operation, but it's a real failure mode if two scripts share a key, or a teammate's run eats quota between your check and your last request landing.

Try it

The free tier covers a cohort of 250 through this exact script. Sign up for a key, drop a CSV and a PDF template next to it, and swap the three field names for whatever the template uses. Field-type mapping for checkboxes, dropdowns, and radio groups is at /docs/fill-form; quota semantics are at /docs/usage.

Automating PDF fills, merges, and invoices in n8n without a Function node

PDFops — Thu, 13 Aug 2026 13:06:51 +0000

Most n8n workflows that touch PDFs end up in the same place: an HTTP Request node with a hand-built multipart body, or a Code node calling pdf-lib and hoping the binary handling survives the next n8n upgrade. n8n-nodes-pdfops is a verified community node that turns PDF inspect, fill, merge, and invoice generation into typed n8n operations, with binary PDFs flowing in and out like any other node.

Installing it

On n8n Cloud, open the nodes panel and search "PDFops"; it installs in one click because it carries n8n's verified badge. Self-hosted, it's Settings → Community Nodes → Install, or from the CLI:

n8n community-node install n8n-nodes-pdfops

The node works with no credential at all, against the same 100-requests-per-IP-per-month anonymous tier the playground uses. Add a PDFops API credential (an API key in the X-API-Key header) once you want a higher quota or the usage operation described below.

The five operations

One node, five operations, picked from a dropdown: Inspect Fields lists a PDF's AcroForm field names, types, and current values, plus a fill template you can paste straight into the next node. Fill Form writes values into those fields and can flatten the result so it stops being editable. Merge concatenates every PDF on the incoming items, in item order, into one file. Generate Invoice renders a complete invoice PDF from a JSON object, no template required. Get Usage returns tier, quota, used, and reset date for a key. Fill, merge, and invoice are deterministic: run the same workflow twice on the same input and the output PDF is byte-identical, so a re-run never shows up as a spurious diff in whatever you archive it to.

A worked example: fill from a webhook, catch the typo first

The node ships with three ready-to-import workflow templates. The one worth walking through end to end is fill and flatten PDF forms from webhook data, because it solves the failure mode that makes "just fill the PDF" workflows unreliable: a field name typed wrong in the JSON payload doesn't error, it just fills nothing, and the caller gets back a document that looks correct until someone opens it.

The workflow receives a webhook carrying a PDF URL, an email address, and a fields object, validates the payload, then runs Inspect Fields on the blank PDF before it fills anything. A Code node diffs the requested field names against the real ones the inspect call returned. Any name that doesn't match routes straight to an error response, naming the bad field, instead of silently producing a blank form. Only a payload that passes the diff reaches Fill Form with flatten on, so the result can't be edited after it ships. From there it fans out: Gmail sends the filled PDF, Google Drive archives a copy, and the caller gets a JSON receipt.

Swap Gmail for SMTP or Slack and Drive for S3 without touching the PDF steps; none of them know or care where the file ends up.

Two more recipes, already built

Merge two forms into one packet. A workflow named onboarding packet from two PDF forms takes two blank PDF URLs and two field objects (a new-hire packet, a new-tenant packet, whatever your business fills in pairs), fills each with its own Fill Form node, waits for both branches, and joins them with Merge so the first form always lands as page one. It refuses to upload a packet unless both branches actually filled, so a partial run never produces a half-finished file that looks whole.

An invoice on every Stripe payment. A Stripe trigger on payment_intent.succeeded feeds a Code node that shapes the charge into invoice JSON, and this is the step where most hand-rolled invoice code breaks quietly: Stripe reports amounts in the smallest currency unit, but JPY, KRW, and thirteen other currencies don't have 100 of those units, so a reflexive amount / 100 issues an invoice a hundred times too small. The template checks the currency against a zero-decimal list before it divides. Generate Invoice renders the deterministic PDF, then it archives to S3, emails the customer when an address is on file, and logs a row to a spreadsheet ledger. A failed render posts to Slack with the payment ID, so a missing invoice gets noticed instead of just not existing.

Keyless works; a key gets you further

Every operation runs without a credential at the shared 100/IP/mo anonymous rate, the same limit the API enforces everywhere else. A free API key (250 requests/month, email in, key out, no card) raises that ceiling and is required for the Get Usage operation, which returns your remaining quota so a workflow can check headroom before it burns the month's last call. Paid tiers exist once a workflow outgrows 250 a month, but the free key runs a real production automation, not just a demo.

Try it

Search "PDFops" in the n8n nodes panel, or install n8n-nodes-pdfops self-hosted. The three templates above are importable as-is from the node's npm page; swap in your own PDF, Stripe account, or storage provider and the PDF steps don't change. Building on the raw API instead? Start at /docs or the OpenAPI spec.

Filling encrypted government PDFs: what actually works, measured

PDFops — Fri, 07 Aug 2026 13:46:06 +0000

You download an official blank from a court or tax site, it opens in every viewer without asking for anything, and then your code throws: Input document to PDFDocument.load is encrypted. There is no password to supply, because the file was published for the public. We ran two real forms in this class, California's FL-100 divorce petition and Canada's TD1 tax credits return, through seven independent fill tools and recorded exactly which ones cope.

Why a public form rejects your library

These blanks are AES-encrypted with an empty user password. The PDF spec allows a document to carry two passwords: a user password that gates opening, and an owner password that gates modification. Publishers set the user password to the empty string, so any viewer decrypts the file silently, and set a real owner password to discourage edits. Strict parsers see the encryption dictionary, notice they were given no credentials, and refuse the whole file. That is the correct reading of the spec and a useless outcome for you.

pdf-lib and its maintained fork @cantoo/pdf-lib both reject FL-100 and TD1 at load. The PDFops fill API is built on the same family and refuses too, with a 400 encrypted_pdf that tells you the workaround instead of leaving you to guess. pypdf opens both files directly when installed as pypdf[crypto], but writes text fields only. The full per-tool results live on the registry pages for ca-fl-100 and cra-td1.

The shell answer: pdftk fills them natively

The one mainstream tool that treats an empty user password like a viewer does is pdftk-java. It enumerated all 158 fields of FL-100, filled 148 of them (every text field, checkbox and radio group; the rest take no value by design), and re-reading its output confirmed all 148 values landed. Same story on TD1: 27 of 27. No decrypt step, and the output file comes out unencrypted.

# enumerate fields (works despite the encryption)
pdftk fl100.pdf dump_data_fields > fields.txt

# fill from an FDF file
cat > values.fdf <<'EOF'
%FDF-1.2
1 0 obj
<< /FDF << /Fields [
<< /T (FL-100[0].Page1[0].CaptionP1_sf[0].AttyInfo[0].AttyFor_ft[0]) /V (Jane Doe) >>
] >> >>
endobj
trailer
<< /Root 1 0 R >>
%%EOF
EOF
pdftk fl100.pdf fill_form values.fdf output filled.pdf

pdftk prints a warning about the owner password and carries on. The owner password restricts editing as a matter of policy, and pdftk takes the position that a file the public can open is a file the public can fill. Adobe's own tools take the stricter position. Know which side your compliance story needs before you rely on this.

The dump_data_fields trap

One gotcha cost us an hour and produces a convincing false negative. On forms that carry an XFA layer alongside the normal field tree, dump_data_fields prints two FieldValue lines per field: an empty one first, then the real value.

FieldName: FL-100[0].Page1[0].CaptionP1_sf[0].AttyInfo[0].AttyFor_ft[0]
FieldNameAlt: ATTORNEY FOR (name):
FieldFlags: 8388608
FieldValue:
FieldValue: Jane Doe

A verification script that greps the first FieldValue line reads an empty string, concludes the fill silently failed, and sends you debugging a problem that does not exist. Collect every FieldValue line for a field and check whether any of them matches what you wrote.

The in-process answer: decrypt first

If your fill runs inside a JS or Python service rather than a shell pipeline, remove the restriction up front with qpdf. The transformation is lossless: same pages, same fields, same appearance.

qpdf --decrypt fl100.pdf fl100-open.pdf

curl -X POST https://pdfops.dev/api/fill-form \
  -F "pdf=@fl100-open.pdf" \
  -F 'fields={"FL-100[0].Page1[0].CaptionP1_sf[0].AttyInfo[0].AttyFor_ft[0]":"Jane Doe"}' \
  -F "flatten=true" \
  -o filled.pdf

After the decrypt, the file behaves like any other AcroForm: pdf-lib loads it, the API fills and flattens it, and field values verify on re-inspection. In our runs this path landed every supported field on both forms.

How common is this class?

More common than two unlucky picks. After this post was drafted we extended the corpus to 22 forms, and five of them ship empty-password AES: FL-100 and FL-150 (so it is the California Judicial Council's house style, on 2 of 2 sampled), TD1 and T2200 (same for the CRA, 2 of 2), and SSA-89, the SSN verification consent signed in most US mortgage closings. pdftk filled all five natively; every pdf-lib-family tool refused all five. If your product touches court filings, Canadian tax paperwork or lending, you will meet this class.

The forms this does not save

Encryption is sometimes the smaller half of the problem. Every current USCIS form we sampled except the I-9 combines this same empty-password AES with a dynamic XFA body, which means the visible form is rendered from an embedded XML template rather than from the AcroForm field tree. qpdf gets you through the encryption, but fillers in the pdf-lib family then write the AcroForm layer and drop XFA on save, and pdftk inherits the same limits. For that class, plan on the AcroForm output being correct in mainstream viewers and blank in old XFA-first Adobe products, or use the agency's own e-filing channel.

PDFops v0.10: fill a PDF by email, make any PDF fillable

PDFops — Thu, 06 Aug 2026 15:04:05 +0000

v0.10 is the no-code on-ramps release. The API is unchanged — same two primitives, fill and merge — but there are now two ways to use PDFops before you've written a line of code, and one of the oldest dead-ends in PDF automation ("this PDF has no form fields") finally has a fix that doesn't involve Acrobat.

Fill a PDF by email — fill@pdfops.dev

Attach a blank fillable PDF and your field values to an email, send it to fill@pdfops.dev, and the reply comes back with the filled PDF — plus the exact curl command that produced it, so the jump from "it works" to "it's in my codebase" is copy-paste. Values go in the body as plain key: value lines, as raw JSON, or as a values.json attachment. Add flatten: true to bake the result flat.

Limits are deliberate: blank templates only (a PDF that already contains data is refused — attachment contents are never stored or logged, and refusing filled-in forms means this address can't become the thing that forwards someone's data around), 5 MB per PDF, evaluation volume rather than production volume. The full contract is on /fill-by-email.

Make any flat PDF fillable — in the browser

Most PDFs that should be forms aren't — they're flat: text and layout baked into the page, no interactive field layer. Until now, every PDFops surface answered that with "sorry, no AcroForm fields." The new make-fillable tool closes that gap: drop the flat PDF, draw text and checkbox fields where they belong, rename them to something your code will recognize, and download a standard AcroForm PDF that works in Acrobat, Preview, browsers, and every PDF library.

It runs entirely in your browser — rendering (pdf.js) and field creation (pdf-lib) both happen client-side, so the PDF never leaves your machine. On export you also get the ready-to-POST /api/fill-form call with your own field names already in it.

The chain, end to end

Those two pieces compose. Starting from a PDF with no fields at all:

Deterministic fills, and `flatten=true`

Since late July, /api/fill-form and /api/merge are byte-deterministic: the same template and the same values return a byte-identical PDF, every time, across deployments. If you snapshot-test documents in CI or need audit-grade reproducibility, you can now assert on a hash — the how and why is in snapshot-testing PDFs in CI. fill-form also accepts flatten=true, which bakes the filled fields into the page content so the output is no longer editable — re-inspecting a flattened fill reports zero fields.

Also since the last release notes

Try it

The 30-second version, no signup:

curl -X POST https://pdfops.dev/api/fill-form \
  -F "pdf=@your-template.pdf" \
  -F 'fields={"customer_name":"Acme Co","total":"$1,250.00"}' \
  -o filled.pdf

Or skip the terminal entirely: make a PDF fillable, fill it by email, or use the playground. Questions, bugs, or a workflow these primitives don't cover? Tell us — the roadmap is driven by what people actually hit.

DEV Community: PDFops

A fixed-row invoice template, and the line item that doesn't fit

Why a template can't grow a row on request

Split into pages, not rows

Totals only go on the last page

The script

Try it

The 4.5 MB request limit that breaks a working PDF merge on Vercel

What actually happens at 4.5 MB

Why local testing never catches it

Size the request before you send it

Chaining calls instead of raising the limit

How PDFops surfaces this instead of a bare 413

Try it

Flattening a filled PDF form with pypdf, and the method that doesn't exist

What pypdf calls flatten() is a different operation

Filling still works, baking doesn't

pdftk's flatten does the job, when you can run it

The part that breaks on Lambda, Vercel, or a Worker

One call instead

Try it

Merging a Letter invoice with an A4 attachment in pypdf, and the page size nobody normalizes

What /MediaBox actually is

Reproducing the mismatch

Why a viewer hides it and a rasterizer doesn't

Normalizing to one page size before merging

Try it

Giving an AI agent PDF tools over MCP, and why it has to inspect before it fills

What pdf_inspect gives the agent

Wiring it in

A two-step request, three tool calls

The part that breaks on a hosted server

Try it

Filling a checkbox with pypdf, and the on-state string it never validates

What actually decides whether a box looks checked

Reproducing the silent no-op

Reading the real on-state before you fill

The default that trades one bug for a viewer-dependent one

What that breaks beyond checkboxes

Try it

Packing-slip PDFs from a fulfillment webhook, and the redelivery that duplicates them

The shape of the job

At-least-once means sometimes-twice

A single atomic claim, not two separate steps

The handler

Releasing a claim that never finished

Try it

Filling a PDF from a Python Lambda with no dependencies to package

The shape of the job

Why the standard library is enough here

Building the multipart body by hand

The Lambda handler

Quota, and the shared-IP problem

Try it

Bulk-filling PDFs from a CSV, and the 429 you shouldn't retry

The shape of the job

Check the quota before you start

The script

The 429 that isn't worth retrying

Try it

Automating PDF fills, merges, and invoices in n8n without a Function node

Installing it

The five operations

A worked example: fill from a webhook, catch the typo first

Two more recipes, already built

Keyless works; a key gets you further

Try it

Filling encrypted government PDFs: what actually works, measured

Why a public form rejects your library

The shell answer: pdftk fills them natively

The dump_data_fields trap

The in-process answer: decrypt first

How common is this class?

The forms this does not save

Related

PDFops v0.10: fill a PDF by email, make any PDF fillable

Fill a PDF by email — fill@pdfops.dev

Make any flat PDF fillable — in the browser

The chain, end to end

Deterministic fills, and flatten=true

Deterministic fills, and `flatten=true`