Fill a PDF Form

Field names are the entire contract between your JSON and the PDF

An interactive PDF does not remember “the wide box near the top left”. It remembers a named field, and that name is whatever the person who built the form typed into their editor years ago. The same idea is called full_name on a rental application, applicant.name.first on an immigration form and topmostSubform[0].Page1[0].f1_01[0] on a US tax form, because the name a field reports includes every parent group it sits inside.

So there is no universal point-and-click layer that could work across every form in the world, and this tool does not pretend otherwise. You supply a small JSON file, the module reads the document’s real field list, and each of your keys is looked up in that list directly. The comparison is exact and case-sensitive. Nothing guesses at coordinates, nothing falls back to the closest similar name, and nothing quietly skips a key it cannot place.

That strictness is the whole point. If a key matches no field, the run stops there and no file comes out, rather than handing you a document that looks filled but has an empty signature date. Fields you simply never mention are a different case entirely, and are left exactly as the original had them.

Text, checkbox, dropdown and radio, and how each reads your value

Four field types are recognised. A text field takes whatever you give it, converted to a string, and JSON null or an empty string wipes the value instead of writing one. If that field declares a maximum length and your value is longer, pdf-lib refuses it and the run ends, so a 30 character address will not squeeze into a 25 character box.

A checkbox reads your value loosely on purpose, because hand written JSON is full of quoted booleans. Only false, null, the number 0 and the strings "false", "0" or "" leave a box clear, the strings being trimmed and lower cased before they are compared. Everything else ticks it, so "no" ticks the box.

A radio group is the strict one. The string you pass has to be one of the group’s own export values, which is frequently a terse code rather than the wording printed on the page. A dropdown is the opposite, accepting an unlisted value by turning itself into an editable combo box so the custom text becomes legal. Anything that is none of those four, a push button or a digital signature field for instance, is treated as unfillable and only causes trouble if your JSON names it directly. If you need a real handwritten mark rather than a form value, sign-pdf places a signature image on a page you choose.

Filling a form, from the field name hunt to the download

1. Open the blank form in Acrobat, Preview or any PDF editor and read the internal name of each field you want to set out of its properties panel.
2. Write those names into one flat JSON object, for example {"full_name": "Jane Doe", "agree_terms": true, "state": "CA"}, and save it as a .json file. Pasting it into json-formatter first will tell you whether it parses.
3. Drop the PDF and the JSON file onto the box above together, or press Choose files and select both. The box lists what it takes, and the two roles are told apart by extension rather than by the order you added them.
4. Tick Flatten fields after filling (makes them read-only, prevents further edits) only if the answers are final.
5. Press Fill a PDF Form. The finished document arrives named after your input with -filled on the end, so w9.pdf downloads as w9-filled.pdf.

Flattening, and what it does to the fields you never touched

Flattening is not a cosmetic lock. Each field’s rendered appearance is painted into the page content as ordinary graphics and then the field object itself is deleted, across the entire form rather than only the boxes you set. A checkbox you never mentioned is baked in at whatever state it was already in, and afterwards there is no live field left to change, no record of what type it used to be, and no undo.

Leave the option off and the document comes back still fillable, which is usually what you want in the middle of a workflow. You can lock it down later as its own pass with flatten-pdf, which is the better order when a signature or a countersignature still has to go on first.

Where it refuses to run, and what the console shows you

The upload box only takes .pdf and .json, so a spreadsheet or a .txt list of answers is turned away before any processing starts. Exactly one of each is required. Files accumulate as you add them and there is no way to remove just one, so reload the page if the list ends up wrong.

Whatever goes wrong inside the module, the page itself shows a single general message rather than the specific reason. The real text is written to the browser’s developer console, and it is worth having open. For an unmatched key it names your bad keys and then lists every field the document really contains, which is often the fastest way to learn the names in the first place. For the wrong number of files it reports the PDF count before it looks at the JSON count, so two forms and no values are described as a PDF problem. Cancelling during a run clears everything and keeps no partial result.

One failure surprises people. pdf-lib redraws the appearance of every field it changed using Helvetica, a font limited to the Latin character set, so a value carrying Cyrillic, Greek or CJK characters throws an encoding error at save time and no file appears.

What pdf-lib rewrites on the way out

Filling is close to surgical. Page content, images, fonts and layout are untouched, and the fields you left alone keep their existing values. The document information is the exception, because pdf-lib refreshes it as it opens the file, stamping its own name into the producer entry and setting the modification date to now. If the output is heading somewhere public, follow up with remove-pdf-metadata, and browse the rest of the PDF tools for the reordering, merging and page number steps that usually come next.