Inkspan › Guides › Fill PDF Form API

Fill PDF Form API

Populate AcroForm fields from a JSON object and get back a completed PDF — ideal for tax forms, applications, and government paperwork.

The fields parameter is a JSON string inside a multipart request, and field names are the form's internal names rather than its visible labels.

Example

import requests

files = {'file': open('input.pdf', 'rb')}
data = {'fields': "{\"full_name\":\"Ada Lovelace\",\"date\":\"2026-10-01\"}"}

r = requests.post(
    'https://api.inkspan.dev/v1/pdf/fill-form',
    headers={'X-API-Key': 'ink_live_...'},
    files=files, data=data,
)
r.raise_for_status()
with open('filled.pdf', 'wb') as f:
    f.write(r.content)

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

Is there a free tier?

Yes — 100 documents a month, no card required. Usage-based plans start at $19/month when you outgrow it.

How do I authenticate?

Send your key in the X-API-Key header on every request.

Do failed requests count against my quota?

No. Only successful requests are metered.

Get a free API key →

Full guides for /v1/pdf/fill-form: cURL · Python · Node.js · all guides