Inkspan › Guides › How to fill a PDF form in Node.js

How to fill a PDF form in Node.js

Q: Why am I getting a 422?

Almost always a missing or malformed fields parameter. It must be present and must be a JSON string.

Tax forms, applications, and government paperwork usually arrive as AcroForm PDFs with named fields. The /v1/pdf/fill-form endpoint takes the blank form plus a JSON object mapping field names to values and returns the completed document, so you can populate official paperwork from your own data without a human retyping it.

The fields parameter is required and must be a JSON string inside a multipart request, not a nested JSON object. That encoding detail causes most first-attempt failures.

Also in: cURL · Python

Node.js example

import fs from 'node:fs';

const fd = new FormData();
fd.append('file', new Blob([fs.readFileSync('input.pdf')]), 'input.pdf');
fd.append('fields', "{\"full_name\":\"Ada Lovelace\",\"date\":\"2026-10-01\"}");

const res = await fetch('https://api.inkspan.dev/v1/pdf/fill-form', {
  method: 'POST',
  headers: { 'X-API-Key': process.env.INKSPAN_KEY },
  body: fd,
});
if (!res.ok) throw new Error(await res.text());
fs.writeFileSync('filled.pdf', Buffer.from(await res.arrayBuffer()));

Request parameters

Name	Type	Required	Description
`file`	file	yes	The PDF containing AcroForm fields.
`fields`	string (JSON)	yes	A JSON object of field name to value, sent as a string in the multipart body.

Response

Returns a PDF as a binary stream with Content-Type: application/pdf and Content-Disposition: attachment; filename=filled.pdf. Write the response body straight to disk — do not parse it as JSON.

Things that catch people out

fields is required. Omitting it returns 422, which is the most common error on this endpoint.
It must be JSON-encoded as a string in a form field — not a nested object. In Python, json.dumps(...) it first.
Field names must match the form's internal names exactly, which are often not the visible labels. Inspect the form to discover them.
Only AcroForm fields are supported. XFA forms, used by some government PDFs, are a different format and will not fill.

Errors

Status	Meaning	Fix
`401`	Invalid or missing API key	Send your key in the `X-API-Key` header.
`402`	Monthly quota exceeded	The response reports used/quota. Upgrade at inkspan.dev/#pricing.
`422`	Missing or invalid parameter	Check required fields in the table above — the body names the offending field.

Failed requests do not count against your quota; only successful ones are metered.

Frequently asked questions

How do I find the field names?

Inspect the PDF with a library such as pypdf and read the AcroForm field dictionary. The internal names frequently differ from the printed labels.

Why am I getting a 422?

Almost always a missing or malformed fields parameter. It must be present and must be a JSON string.

Are checkboxes supported?

Yes, but they take the export value defined in the form — often Yes or On rather than true.

Get a free API key →

Related Manipulate guides: merge PDF files · split a PDF into pages · compress a PDF · add a watermark to a PDF · convert a PDF to images