Filling a PDF form is one of those tasks that looks trivial until you try to automate it. The document on screen has a box labelled “Vendor name”; the PDF has a field called VND_NM_1. Coordinates drift between revisions, text doesn't fit, and the checkbox refuses to tick. If an agent is supposed to fill a W-9, an intake form, or a lease addendum, guessing coordinates is the wrong layer to work at.
AcroForm PDFs give you a better handle: named fields, typed values, and a form dictionary the file ships with. Two endpoints cover it — one to read the field list, one to write values into it. Here is the two-step loop, the value conventions that trip people up, and the delivery step (flatten, stamp, page numbers) that turns a filled form into something you can hand to a counterparty.
A fillable PDF contains an AcroForm dictionary listing every field with a name, a type, and optional flags. Tools like pdf-lib read that dictionary, set values on the field objects, and save a new file. The visual layout is untouched — only the field values change.
That definition sets the boundary honestly:
Field names are the whole contract, and you cannot trust the label printed on the page to match them. Start by asking the document what it contains. Send the PDF as multipart form data:
curl -s -F "pdf=@vendor-intake.pdf" \ https://agentmediatools.com/api/pdf-list-fields
Real response from a small intake form I generated for this test:
{
"success": true,
"fields": [
{ "name": "vendor_name", "type": "TextField" },
{ "name": "contact_email", "type": "TextField" },
{ "name": "account_number", "type": "TextField" },
{ "name": "accept_terms", "type": "CheckBox" },
{ "name": "country", "type": "Dropdown" }
],
"count": 5
}
Types come back in the vocabulary of the underlying library: TextField, CheckBox, Dropdown, RadioGroup, OptionList, Signature. The type matters because each one expects a different value shape in the next step.
Instead of a local file you can pass a public URL with -F "url=https://...". Field discovery is also the cheapest possible sanity check on a new template: cache the field list once per document revision and you never have to guess again.
Send the same PDF with a fields parameter containing a JSON object of field name to value:
curl -s -F "pdf=@vendor-intake.pdf" \
-F 'fields={"vendor_name":"Ada Lovelace","contact_email":"ada@example.com","accept_terms":true,"country":"CA"}' \
https://agentmediatools.com/api/pdf-form-fill
Response:
{
"success": true,
"filename": "3aeee3d1-b158-4c58-8af3-d3de6614b9b1.pdf",
"downloadUrl": "/downloads/3aeee3d1-b158-4c58-8af3-d3de6614b9b1.pdf",
"size": 4969,
"filled_fields": ["vendor_name", "contact_email", "accept_terms", "country"],
"missing_fields": [],
"available_fields": ["vendor_name", "contact_email", "account_number", "accept_terms", "country"],
"flattened": false
}
Three details in that payload are worth designing around:
filled_fields lists what actually took a value. missing_fields lists every key that failed — a typo in the name, a field that doesn't exist, or a value the field type rejected. available_fields echoes the full field list, so a failed call still tells you how to fix itself without a second request.downloadUrl is a path, not an absolute URL. Prefix it with https://agentmediatools.com when you fetch it. Treat it as a temporary delivery link, not permanent storage — copy the bytes somewhere you control if the document needs to survive.flattened reports what the request asked for, so log it alongside the file. A flattened form and an editable form are different artifacts.This is where most integrations fail quietly. The endpoint inspects each field's type and coerces the value:
| Field type | What to send | Behavior |
|---|---|---|
TextField | string or number | Converted to a string and set as the field value |
CheckBox | true, "true", "1", "Yes", "yes" | Checks the box; any other value unchecks it |
Dropdown | the exact option string | Must match an option already in the list, or the field lands in missing_fields |
RadioGroup | the exact option string | Same rule as dropdowns — no option, no fill |
Two consequences follow. First, "accept_terms": "no" doesn't leave the box alone — it actively unchecks it, which is what you want for a deterministic pipeline but surprising if you were passing a value through. Second, dropdowns and radios need the option value, not the label: if the choice list is ["US","CA","MX"], send CA — not Canada. When you don't know the option strings, a failed fill with missing_fields: ["country"] is your signal to inspect the template, not to retry harder.
Text fields stringify both strings and numbers, so amounts and IDs are safe as either. They are never reformatted, though: send the exact printed string you want for dates, phone numbers, and currency, or the page will show whatever you sent.
An unflattened output is still a form — fields remain editable. For anything you send to a client, a landlord, or a filing portal, flatten it so values become part of the page content:
curl -s -F "pdf=@vendor-intake.pdf" \
-F 'fields={"vendor_name":"Ada Lovelace","accept_terms":true,"country":"CA"}' \
-F "flatten=true" \
-F "stamp_text=Received 2026-10-30" \
-F "page_numbers=true" \
https://agentmediatools.com/api/pdf-form-fill
What each option does, exactly:
flatten — merges field appearance into the page and removes the form fields. Verified on the live API: re-submitting the flattened output to /api/pdf-list-fields returns count: 0. Keep a separate unflattened run if you may need corrections later.stamp_text — a single line of small grey text (truncated at 120 characters) placed bottom-right on every page. Good for intake timestamps, case IDs, or “copy” markers. It is a footer label, not a signature or a certificate.page_numbers — adds a centered n / total footer to each page. Useful when the template lacks pagination and the recipient prints it.Ordering inside the request is fixed: values are set first, then the form is flattened, then the stamp and page numbers are drawn. That's why a stamp survives flattening and why values never appear as editable text under it.
A complete, copy-pasteable script: discover fields, fill, download, and print anything that didn't take.
import json
import requests
BASE = "https://agentmediatools.com"
pdf_path = "vendor-intake.pdf"
# 1. Discover field names and types
with open(pdf_path, "rb") as fh:
listing = requests.post(
f"{BASE}/api/pdf-list-fields",
files={"pdf": fh},
timeout=60,
).json()
print("fields:", [(f["name"], f["type"]) for f in listing["fields"]])
# 2. Build the value map from your own data
values = {
"vendor_name": "Ada Lovelace",
"contact_email": "ada@example.com",
"accept_terms": True,
"country": "CA",
}
# 3. Fill, flatten, and stamp
with open(pdf_path, "rb") as fh:
result = requests.post(
f"{BASE}/api/pdf-form-fill",
files={"pdf": fh},
data={
"fields": json.dumps(values),
"flatten": "true",
"stamp_text": "Received 2026-10-30",
"page_numbers": "true",
},
timeout=90,
).json()
if not result.get("success"):
raise SystemExit(f"fill failed: {result}")
if result["missing_fields"]:
print("not filled:", result["missing_fields"], "of", result["available_fields"])
# 4. Save the artifact locally
out = requests.get(f"{BASE}{result['downloadUrl']}", timeout=60)
out.raise_for_status()
open("vendor-intake-filled.pdf", "wb").write(out.content)
print("saved", result["size"], "bytes, flattened:", result["flattened"])
The missing_fields branch is the part worth keeping. In a batch run it converts a silent partial fill into a per-document warning you can route to a human, which matters far more than speed when the output is a contract.
The hosted MCP server at https://agentmediatools.com/api/mcp exposes this route as the tool pdf_form_fill. Its arguments are pdf_url (a public URL — MCP calls cannot upload a local file), fields (an object), and the optional flatten, stamp_text, and page_numbers flags.
Two boundaries to plan around:
/api/pdf-list-fields once per template, or keep the field map in its instructions.The endpoint takes one PDF and one map per request, which is the right unit for a pipeline: one row of a spreadsheet, one vendor record, one applicant. Two habits keep a folder-scale run debuggable.
filled_fields, missing_fields, and flattened next to each artifact. When a counterparty says a box is blank, you know whether the write failed or the value was wrong.vendor_name to vendor_legal_name silently breaks every fill after it.| Symptom | Cause | Fix |
|---|---|---|
count: 0 from list-fields | Flat/scanned PDF or XFA form | No fields to fill; extract text or OCR instead |
Key in missing_fields | Name mismatch or wrong value type | Compare against available_fields; check dropdown option strings |
"fields must be valid JSON object" | Unquoted or malformed JSON in the multipart field | Serialize with json.dumps or JSON.stringify, never string concatenation |
| Remote file too large | url input above the 5 MB fetch cap | Upload the file as multipart instead |
| Filled copy looks editable | flatten not set | Send flatten=true for delivery copies |
One privacy note: filled documents are served from a temporary download path, so treat the link as public for its lifetime. For forms carrying tax IDs, health details, or addresses, that window is a real consideration — fetch the bytes promptly and avoid pasting download links into chat logs or issue trackers.
Form filling is the last mile of a document pipeline that usually starts with extraction. If you already pull data out of PDFs with the PDF processing endpoints, this closes the loop: read the fields, write the fields, flatten, deliver. The PDF form fill tool page runs the same request in a browser panel if you want to inspect a template by hand before automating it.
Fill a form in the browser, or call the same endpoint from your agent with an API key and a daily free allowance.
Open toolbox