DEV Community: PDFops

A customer's name fills a PDF form field as ????, and the response is still 200

PDFops — Thu, 29 Oct 2026 13:09:47 +0000

A W-9 request form has a text field called full_legal_name. A customer named Tanaka Taro signs up, the field gets filled with his name, and the PDF that comes back is a 200 with a valid application/pdf body. Open it, and the name field reads ????. Nothing in the response says that happened.

Why Helvetica cannot draw the name you just filled

Most PDF form fields reference a font through a /DA default-appearance string, usually /Helvetica, one of fourteen standard fonts every PDF reader ships without the PDF embedding it. Helvetica as a standard font encodes WinAnsi, which is Latin-1: the Latin alphabet plus the accented letters Western European languages need. It has no glyphs for Japanese, Cyrillic, Arabic, Hebrew, Thai, or Han characters, and none for most emoji either. A filler that draws the field's text with that font can only draw what WinAnsi covers, no matter what string the caller sent.

What a tool does when it meets a character it cannot draw

A PDF library filling thousands of forms a day cannot stop and ask a human what to do with a character outside the font, so most pick a fallback and move on rather than throwing on every unsupported codepoint. The common choice, and the one the fill path in PDFops' own stack takes by default, is to encode the text one codepoint at a time and substitute a literal ? for anything WinAnsi cannot represent. That substitution happens inside the font embedder, with no exception raised and no flag set on the result. Four Japanese characters go in; four question marks come out, baked straight into the field's appearance stream.

Why the field value looks fine and the PDF still doesn't

The field's underlying value, the actual string a PDF stores in its /V entry, is untouched by any of this. Reading it back with a library like pypdf or pdf-lib returns "Tanaka Taro" exactly as sent. Only the rendered appearance, the glyphs drawn for a human to look at, carry the question marks. That split is what makes the bug easy to ship: a test that fills a field and reads the value straight back passes every time, because the value was never touched. The only way to catch the problem is to open the file and look, or to inspect the raw content stream the appearance was drawn into, and a CI pipeline does neither by default.

Checking before you fill, not after

The fix that actually works is checking the string against the font's character set before it ever reaches the fill call, the same way a form validates an email address before it hits the database. WinAnsi is a fixed, small set, so the check is cheap: build it once from the embedded font, then test every character of every value against it.

// Build once per process; WinAnsi never changes at runtime.
const WINANSI = new Set(
  Array.from({ length: 256 }, (_, i) => i)
    .filter((code) => isWinAnsiRenderable(code)), // see your PDF library's font metrics
);

function findUnrenderable(value) {
  const bad = [];
  for (const ch of value) {
    const cp = ch.codePointAt(0);
    if (!WINANSI.has(cp)) bad.push(ch);
  }
  return bad;
}

function assertRenderable(fieldName, value) {
  const bad = findUnrenderable(value);
  if (bad.length > 0) {
    throw new Error(
      `field "${fieldName}": "${value}" contains characters a WinAnsi ` +
      `font cannot draw (${bad.join(", ")}). Embed a Unicode font ` +
      `(e.g. a Noto variant) instead of the standard Helvetica, or ` +
      `transliterate the value before filling.`,
    );
  }
}

This is the same shape of check PDFops' own /api/invoice endpoint already runs before it draws a single character, precisely because that endpoint builds its own pages with the same standard Helvetica. Running the identical check in application code ahead of any form-fill call, whatever library sits underneath it, turns a silently wrong PDF into a loud error that names the exact field and the exact characters it couldn't draw.

What a WinAnsi font actually covers

Latin-1 covers more than it looks like at a glance: café, Müller, and García all render correctly, since é, ü, and í sit inside WinAnsi's extended range. What breaks is anything outside the Latin script entirely, plus a handful of typographic characters some editors insert automatically, like curly quotes or an em dash pasted from a word processor, if the specific font's character table happens to omit them. The only real fix for names and text in another script is embedding a font that actually has the glyphs, a Noto variant covers most scripts, and re-running the appearance generation with that font instead of Helvetica. Where that is not practical, transliterating to the closest Latin representation is the honest fallback, with the original value still stored in whatever system of record sits behind the PDF.

Try it

A free key from /docs/signup includes 250 calls a month, enough to fill a test AcroForm with a few non-Latin names and confirm for yourself which ones come back readable and which come back as question marks before any real customer data goes through the same path.

A 429 from /api/fill-form, and what your retry loop should actually do

PDFops — Thu, 22 Oct 2026 13:06:19 +0000

A batch job fills two hundred PDFs overnight, call forty hits a 429, and the generic retry wrapper you copied from another project kicks in: wait a second, retry, wait two seconds, retry, wait four. PDFops caps are monthly, not per-minute, so that loop is backing off toward a wall it cannot back off past, and it will spend the rest of the night finding that out one doubling at a time.

What the cap actually tracks

Every PDFops endpoint meters against a monthly quota, not a request rate: 100 requests a month per IP with no key, 250 a month on a free key, more on indie and pro. There is no per-second or per-minute throttle to wait out. When the count for the current UTC month is spent, every call fails with 429 rate_limited until the first of next month, no matter how far apart the calls are spaced.

Retry-After tells you the truth, if you read it

The 429 response carries a Retry-After header, and on this API it is not a short number. It is seconds until the next UTC month starts, which can be anywhere from one second to beyond a million. A retry wrapper tuned for typical API throttling treats any Retry-After under some sane ceiling as obey-and-retry and anything past it as give-up-now, and a monthly cap blows past that ceiling on the first day of the month. Reading the header before choosing to retry turns a silent all-night retry storm into one log line: quota resets in 1,180,000s, bailing.

Validation failures do not cost you anything

The flip side is worth knowing before you build defensive retry logic you do not need: a 400 for a malformed field list or an unknown field name never touches the quota, and neither does a 500 on PDFops' side. Only a 2xx response counts against the monthly budget. That means a batch job can fail fast and loud on a bad template without worrying it is burning through the same number that gates working calls, and it means the only response code worth backing off for is 429, because every other failure is either yours to fix in the request or ours to fix on our side.

Check /api/usage before the batch starts, not after it 429s

A key's current count, limit, and reset time are all sitting behind one GET call: /api/usage with the same X-API-Key header, returning tier, limit, used, remaining, and resets_at. A batch job that reads remaining before it starts and compares it against the number of calls the batch is about to make can stop itself at item one hundred and ninety instead of discovering the wall at item two hundred with ten PDFs half-written to a destination that now has a gap in it.

The script

The pattern below checks the budget up front, aborts the batch cleanly if it will not fit, and treats a mid-run 429 as a stop signal rather than something to wait out.

const API_KEY = process.env.PDFOPS_API_KEY;
const BASE = "https://pdfops.dev";

async function checkBudget(pendingCalls) {
  const res = await fetch(`${BASE}/api/usage`, {
    headers: { "X-API-Key": API_KEY },
  });
  if (!res.ok) throw new Error(`usage check failed: ${res.status}`);
  const { remaining, resets_at } = await res.json();
  if (remaining < pendingCalls) {
    throw new Error(
      `only ${remaining} calls left this period (resets ${resets_at}), ` +
      `batch needs ${pendingCalls} — aborting before it starts`,
    );
  }
  return remaining;
}

async function fillOne(templateBuf, fields) {
  const form = new FormData();
  form.append("pdf", new Blob([templateBuf]), "template.pdf");
  form.append("fields", JSON.stringify(fields));
  form.append("flatten", "true");
  const res = await fetch(`${BASE}/api/fill-form`, {
    method: "POST",
    headers: { "X-API-Key": API_KEY },
    body: form,
  });
  if (res.status === 429) {
    const retryAfter = res.headers.get("retry-after");
    const body = await res.json();
    throw new Error(
      `quota hit mid-batch (${body.details}); retry-after=${retryAfter}s — ` +
      `stopping the run rather than sleeping through it`,
    );
  }
  if (res.status >= 500) {
    // transient on our side — worth one short retry, not a long backoff
    await new Promise((r) => setTimeout(r, 1000 + Math.random() * 500));
    const retry = await fetch(`${BASE}/api/fill-form`, {
      method: "POST",
      headers: { "X-API-Key": API_KEY },
      body: form,
    });
    if (!retry.ok) throw new Error(`fill-form failed twice: ${retry.status}`);
    return Buffer.from(await retry.arrayBuffer());
  }
  if (!res.ok) {
    const body = await res.json();
    throw new Error(`fill-form rejected the request: ${body.error} — ${body.details}`);
  }
  return Buffer.from(await res.arrayBuffer());
}

async function runBatch(jobs) {
  await checkBudget(jobs.length);
  const results = [];
  for (const job of jobs) {
    results.push(await fillOne(job.template, job.fields));
  }
  return results;
}

checkBudget only has to run once, before the loop starts. Inside the loop, a 429 is treated as fatal rather than something to sleep through, because the quota that just ran out will not come back until next month no matter how long the loop waits. A 500 gets exactly one short, jittered retry, since that failure mode is a transient server issue rather than a budget problem.

Try it

A free key from /docs/signup includes 250 calls a month, enough to run this batch pattern against a real template and watch remaining count down in /api/usage before wiring the budget check into a production job.

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.