PDF API: fill and parse PDF forms

What it is for

The API is built for one job: putting data into existing PDF forms, and reading it back out. Typical uses:

• Client intake. A law, accounting or immigration practice collects answers in its own system and generates the completed PDF form for signature.
• Onboarding packets. HR fills direct deposit, tax and policy acknowledgement forms from the employee record instead of asking people to type the same details three times.
• Data capture. Completed fillable PDFs come back by email; /parse pulls the field values into JSON so nobody retypes them.
• Batch generation. One template, hundreds of records, one call per PDF.

It is not a PDF rendering engine. It does not create PDFs from HTML, convert file formats, or add form fields to a flat document. For those, use the browser tools: HTML to PDF, Word to PDF, and Make a PDF fillable.

How a typical integration works

1. Prepare the template once. Start from a PDF that already has AcroForm fields (most government and HR forms do). If yours is flat, add fields with Make a PDF fillable and download the result.
2. Discover the field names. Send the template to /parse. Save the fields array; the name values are the keys you will fill.
3. Map your data. Build an object of field name to value. Strings for text fields, booleans for checkboxes, the option label for dropdowns and radio groups.
4. Fill. Send the template and the map to /fill. Check skipped for names that did not match, then decode pdf from base64 and store or send it.
5. Flatten or not. With flatten true (the default) the values become part of the page and cannot be edited. Set it to false when the recipient still needs to complete or correct fields.

Authentication and limits

Send your key as a bearer token on every request. The API also accepts the same key in an x-api-key header.

Authorization: Bearer fk_live_your_key

Every key gets 100 requests per calendar day (UTC). Each response includes a remaining count, and the 101st request returns 429 until the day rolls over. Keys generated on this page are not tied to an account; keys generated after you sign up show up in your dashboard. For production volume, subscribe to the API plan.

POST /api/v1/parse

Extract form fields, page count, metadata and text from a PDF. Send the PDF as base64 in JSON, or as multipart form-data in a file field.

curl -X POST https://fillable.ca/api/v1/parse \
  -H "Authorization: Bearer fk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"pdf":"<base64-encoded-pdf>"}'

Multipart form:

curl -X POST https://fillable.ca/api/v1/parse \
  -H "Authorization: Bearer fk_live_your_key" \
  -F "file=@intake-form.pdf"

Response:

{
  "pageCount": 12,
  "title": "Client Intake Form",
  "author": null,
  "fieldCount": 18,
  "fields": [
    { "name": "full_name", "type": "TextField", "value": "" },
    { "name": "agree", "type": "CheckBox", "value": false },
    { "name": "province", "type": "Other" }
  ],
  "text": ["Page 1 text ...", "Page 2 text ..."],
  "remaining": 99
}

POST /api/v1/fill

Fill a PDF’s form fields and get the completed PDF back as base64. JSON only.

curl -X POST https://fillable.ca/api/v1/fill \
  -H "Authorization: Bearer fk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "pdf": "<base64-encoded-pdf>",
    "fields": { "full_name": "Jane Smith", "agree": true, "province": "ON" },
    "flatten": true
  }'

Response:

{
  "applied": ["full_name", "agree", "province"],
  "skipped": [],
  "remaining": 98,
  "pdf": "<base64-encoded-filled-pdf>"
}

flatten defaults to true. A flattened PDF keeps the values as page content, which is what you want for a final copy. Send false to keep the fields live.

Code examples

Node (18 or later, no dependencies):

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

const key = process.env.FILLABLE_KEY;
const pdf = (await readFile("intake-form.pdf")).toString("base64");

// 1. Discover the field names
const parsed = await fetch("https://fillable.ca/api/v1/parse", {
  method: "POST",
  headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json" },
  body: JSON.stringify({ pdf }),
}).then((r) => r.json());
console.log(parsed.fields.map((f) => f.name));

// 2. Fill and flatten
const filled = await fetch("https://fillable.ca/api/v1/fill", {
  method: "POST",
  headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json" },
  body: JSON.stringify({ pdf, fields: { full_name: "Jane Smith", agree: true }, flatten: true }),
}).then((r) => r.json());

if (filled.skipped?.length) console.warn("Not applied:", filled.skipped);
await writeFile("intake-form-filled.pdf", Buffer.from(filled.pdf, "base64"));

Python (requests):

import base64, os, requests

key = os.environ["FILLABLE_KEY"]
headers = {"Authorization": f"Bearer {key}"}

with open("intake-form.pdf", "rb") as f:
    pdf_b64 = base64.b64encode(f.read()).decode()

parsed = requests.post("https://fillable.ca/api/v1/parse",
                       headers=headers, json={"pdf": pdf_b64}).json()
print([f["name"] for f in parsed["fields"]])

filled = requests.post("https://fillable.ca/api/v1/fill", headers=headers,
                       json={"pdf": pdf_b64,
                             "fields": {"full_name": "Jane Smith", "agree": True},
                             "flatten": True}).json()

with open("intake-form-filled.pdf", "wb") as out:
    out.write(base64.b64decode(filled["pdf"]))

Errors

• 400 bad request: missing pdf, missing fields, invalid JSON, or no file in a multipart upload. The error string says which.
• 401 missing or invalid API key.
• 422 the PDF could not be opened or processed. Common causes: not a PDF, corrupted file, or a file that needs repair. Run it through Repair PDF and retry.
• 429 daily limit reached for this key.

Encrypted PDFs are opened with encryption ignored, so owner-password-protected forms usually work. A file that needs a user password to open will fail with 422; remove the password first with Unlock PDF if you have the right to.

Privacy and handling

• PDFs are processed in memory and are not stored. Nothing about the document content is logged.
• The only stored record is the per-key daily request count.
• All traffic is over HTTPS. Keys are shown once at creation; if you lose one, generate a new one.
• Keep keys server-side. Do not embed them in browser code or mobile apps.

Notes

• Field names come from the PDF’s form. Use /parse first to discover them, then /fill.
• Field names are case sensitive and can contain dots or spaces; send them exactly as returned.
• Need higher limits or a signed agreement? See the API plan or email info@fourcents.ca.