Endpoint reference
POST /api/add-fields
Create fillable form fields in an existing PDF: text boxes, multiline text, checkboxes, radio groups, dropdowns and signature boxes, each at a page and position you give. Returns the PDF with standard AcroForm fields as application/pdf.
Request
Method: POST. URL: https://pdfops.dev/api/add-fields. Body: multipart/form-data.
| Field | Type | Required | Description |
|---|---|---|---|
pdf | File (PDF binary) | Yes | Exactly one PDF, up to 4 MB and 2,000 pages. The whole request must stay under 4.5 MB, Vercel's platform request limit. |
fields | String (JSON array) | Yes | The fields to create. Up to 200 entries and 256 KB, and up to 200 widgets in total (a radio option counts as one). See Fields. |
password | String | No | Opens a PDF that needs a user password. Not needed for owner-locked files with an empty user password. |
The optional X-API-Key header works as on /api/merge: no header is anonymous, 100 requests per IP per month; a valid key uses your tier's quota; an invalid or revoked key returns 401 invalid_api_key. A successful (2xx) call counts 1 request, however many fields it adds. Check consumption with GET /api/usage.
Coordinates
Positions are in PDF points, 72 to the inch, measured from the bottom-left corner of the page as a viewer shows it, the same frame and 1-based page numbers as /api/edit. A US Letter page is 612 × 792 points and A4 is 595 × 842. If a page is rotated, or has a crop box, the origin is still the bottom-left of what you see, so you never have to undo the rotation yourself; the text inside a field stays upright. A PDF viewer's measuring tool shows where a blank line sits; measure from the bottom edge, not the top.
x and y are the field's bottom-left corner, and width and height extend right and up. The whole rectangle must lie inside the page. A field with a border (the default) draws it half a point outside the rectangle on each side, so a bordered text, checkbox, radio or dropdown field flush against a page edge is out of bounds; set border to false or move it in by a point. A signature box draws its border inside its rectangle, so it can sit flush.
Fields
Every entry has type, name and page. Every type except radio also has x, y, width and height. Nothing is added unless every entry is valid.
Keys every type takes
| Key | Type | Default | Description |
|---|---|---|---|
type | String | Required | text, checkbox, radio, dropdown or signature. |
name | String | Required | 1 to 200 characters, no dot, not blank, no control characters. Unique within the request and in the PDF. See Names. |
page | Integer | Required | 1-based page number. |
x, y, width, height | Number | Required (not for radio) | The rectangle in points. Each side is at least 4 points. |
required | Boolean | false | Sets the field's Required flag. Viewers that honour it ask for a value; this API does not enforce it. |
read_only | Boolean | false | Sets the field's ReadOnly flag. /api/fill-form still fills it. |
border | Boolean | true | Draw a black outline 1 point wide. false draws none. |
background | Boolean | false | true paints an opaque white background; by default there is none, so the page artwork under the field stays visible. |
Text fields: "type": "text"
| Key | Type | Default | Description |
|---|---|---|---|
multiline | Boolean | false | Allow several lines. A single-line field takes no line break. |
max_length | Integer | No limit | 1 to 65,535 characters. /api/fill-form rejects a longer value. |
default | String | Empty | The starting value, drawn in the field. Up to 65,536 characters (131,072 across all defaults in the request), no longer than max_length, and a line break only if multiline is true. Standard fonts cover the WinAnsi set: € and “ ” are accepted, Ł and CJK characters fail with unsupported_characters. |
font_size | Number or "auto" | See Font size | 1 to 200 points, or "auto". Read Font size before using "auto". |
Checkboxes: "type": "checkbox"
| Key | Type | Default | Description |
|---|---|---|---|
checked | Boolean | false | Start ticked. |
Radio groups: "type": "radio"
One entry makes one group named name, with one button per option; only one can be selected. The entry has no rectangle of its own: each option has its own.
| Key | Type | Default | Description |
|---|---|---|---|
options | Array | Required | 1 to 100 objects {"value", "x", "y", "width", "height"}. value is 1 to 200 characters, unique in the group, not "Off", and never drawn, so it need not be WinAnsi. Each option's rectangle follows the same rules and the same coordinates as any field, and may be on the group's page only. |
default | String | None selected | One of the option values, selected to start. |
Dropdowns: "type": "dropdown"
| Key | Type | Default | Description |
|---|---|---|---|
options | Array of strings | Required | 1 to 100 non-empty, unique strings with no line break. WinAnsi characters only (é, €, œ are accepted; Ł and CJK characters fail with unsupported_characters). |
default | String | None selected | One of the options. |
font_size | Number or "auto" | See Font size | 1 to 200 points, or "auto". See Font size. |
Signature boxes: "type": "signature"
Takes only the keys every type takes. It creates an empty signature field for a signing tool to use later; see Behavioral notes.
Font size
font_size is a number of points from 1 to 200, or the string "auto". It only changes text and dropdown fields; checkboxes, radio groups and signature boxes accept a valid value and ignore it.
- Omitted (the default): text, multiline text and dropdown fields get a fixed size: 12 points, or the largest size at which one line fits the field's height if that is smaller, and at least 4 points. The stored size for a box 300, 70, 24, 14 and 8 points high is 12, 12, 12, 9 and 4. Because it is fixed, text draws predictably when the field is filled.
- A number: exactly that size, fixed.
"auto": the field is stored with size 0, and the size is chosen when the field is filled with/api/fill-form, as described next.
What "auto" does today, as observed on this API: when a blank auto field is filled, the text is sized to the box in both directions. A long value shrinks (a long sentence in a 260 × 70 point single-line field came out at 13 points) and a short one is enlarged (Hi in a 260 × 70 point field is drawn at 60 points). That size is then saved into the field on its first fill, so if you fill the already-filled output again with a longer value, it keeps the 60-point size and the value is clipped. For predictable text, leave font_size out or set a number.
In a fixed-size field, a value longer than the box is clipped, not shrunk: a multiline field shows the lines that fit and cuts off the rest at the bottom. No characters are dropped; /api/fill-form stores a multiline value with line breaks added where it wraps. If your fillers send long text, make the box taller or set a smaller number.
Names
A name is how /api/fill-form and /api/inspect refer to the field. It is 1 to 200 characters, with no dot, no control characters and not only spaces. A dot is refused because it would make a parent field and a child field. Names must be unique within the request, and must not collide with a field already in the PDF.
Collisions are judged on the Unicode-normalised (NFC) name. A new name collides with an existing field of the same name, and with the first part of an existing dotted name: if the PDF already has form1.name, the name form1 is taken. Either returns duplicate_field. The existing form is read as /api/inspect reads it: a PDF whose form has more than 2,000 fields once yours are added is refused with too_many_fields.
Response
On success: 200 OK, Content-Type: application/pdf, body is the PDF with the new fields. Existing fields, their values and the page content are kept.
If the input had a hybrid AcroForm/XFA layer, the XFA layer is not preserved on save, and the response carries an x-pdfops-warning header that starts with xfa-layer-dropped, the same header /api/fill-form sends.
On any failure: 4xx or 500, Content-Type: application/json, body is { "error": "<code>", "details": "<explanation>" }.
Error codes
| Error code | Status | Trigger |
|---|---|---|
invalid_multipart | 400 | Request body could not be parsed as multipart/form-data. |
missing_pdf | 400 | The request does not have exactly one pdf file field. |
pdf_too_large | 400 | The pdf file is over 4 MB. |
invalid_pdf | 400 | The PDF could not be parsed (corrupt, or not a PDF), or its existing form could not be read well enough to extend it. |
encrypted_pdf | 400 | The PDF needs a password we were not given. Send it as the password form field. |
decompressed_too_large | 400 | Object streams inside the PDF decompress to over 32 MB. |
too_many_pages | 400 | The PDF has over 2,000 pages. |
invalid_fields | 400 | fields is missing, not valid JSON, not a non-empty array, over 256 KB, or an entry has an unknown type, a bad name or value, a side under 4 points, bad options, a default that is too long or not allowed, or a rectangle outside the page. details names the entry and key, such as fields[2].width. |
too_many_fields | 400 | More than 200 entries, more than 200 widgets in total, or the PDF's form would pass 2,000 fields. |
duplicate_field | 400 | A name is used twice in the request, or already exists in the PDF. |
invalid_pages | 400 | An entry's page is past the end of the document. |
unsupported_characters | 400 | A text default or a dropdown option has a character the standard fonts cannot draw. details names the first one. |
save_failed | 500 | PDF serialization failed. Retryable. |
request_too_large | 413 | The whole request body is over 4.5 MB (Vercel's platform request limit). Rejected before anything is parsed. |
invalid_api_key | 401 | An X-API-Key header was sent but the key is unknown or revoked. Get a fresh key at /pricing. |
rate_limited | 429 | The anonymous per-IP limit (100/month) or your key's monthly quota is used up. Retry-After gives seconds until next calendar month. |
Example
Add a name box, a multi-line notes box and a checkbox to a one-page agreement. The checkbox is 14 points square; the notes box is 300 × 70 points.
curl -X POST https://pdfops.dev/api/add-fields \
-F "pdf=@agreement.pdf" \
-F 'fields=[
{"type":"text","name":"full_name","page":1,"x":160,"y":695,"width":240,"height":20},
{"type":"text","name":"notes","page":1,"x":160,"y":580,"width":300,"height":70,"multiline":true,"max_length":500},
{"type":"checkbox","name":"agree","page":1,"x":160,"y":518,"width":14,"height":14}
]' \
-o fillable.pdf
Keyless calls work: 100 requests per IP per month with no key. With a key, add -H "X-API-Key: pdfops_live_..." to any request here; it raises your quota to your tier's.
A radio group is one entry whose options each carry a rectangle. Here plan has three buttons in a row, with basic selected:
curl -X POST https://pdfops.dev/api/add-fields \
-F "pdf=@agreement.pdf" \
-F 'fields=[
{"type":"radio","name":"plan","page":1,"options":[
{"value":"basic","x":160,"y":478,"width":14,"height":14},
{"value":"pro","x":240,"y":478,"width":14,"height":14},
{"value":"team","x":320,"y":478,"width":14,"height":14}
],"default":"basic"}
]' \
-o fillable.pdf
A dropdown takes a list of strings:
curl -X POST https://pdfops.dev/api/add-fields \
-F "pdf=@agreement.pdf" \
-F 'fields=[
{"type":"dropdown","name":"country","page":1,"x":160,"y":425,"width":160,"height":20,
"options":["Canada","Germany","Poland","United States"],"default":"Canada"}
]' \
-o fillable.pdf
A signature box is an empty field with an outline, 240 × 50 points here:
curl -X POST https://pdfops.dev/api/add-fields \
-F "pdf=@agreement.pdf" \
-F 'fields=[
{"type":"signature","name":"signer","page":1,"x":160,"y":340,"width":240,"height":50}
]' \
-o fillable.pdf
Recipe: add fields, then fill them
A flat PDF has nothing for /api/fill-form to fill. Add the fields first, then fill them by name. Two calls, 2 requests:
# 1. Add the fields
curl -X POST https://pdfops.dev/api/add-fields \
-F "pdf=@agreement.pdf" \
-F 'fields=[
{"type":"text","name":"full_name","page":1,"x":160,"y":695,"width":240,"height":20},
{"type":"text","name":"notes","page":1,"x":160,"y":580,"width":300,"height":70,"multiline":true},
{"type":"checkbox","name":"agree","page":1,"x":160,"y":518,"width":14,"height":14},
{"type":"radio","name":"plan","page":1,"options":[
{"value":"basic","x":160,"y":478,"width":14,"height":14},
{"value":"pro","x":240,"y":478,"width":14,"height":14},
{"value":"team","x":320,"y":478,"width":14,"height":14}
]},
{"type":"dropdown","name":"country","page":1,"x":160,"y":425,"width":160,"height":20,
"options":["Canada","Germany","Poland","United States"]},
{"type":"signature","name":"signer","page":1,"x":160,"y":340,"width":240,"height":50}
]' \
-o fillable.pdf
# 2. Fill them
curl -X POST https://pdfops.dev/api/fill-form \
-F "pdf=@fillable.pdf" \
-F 'fields={"full_name":"Jordan Lee","notes":"Net 30 terms.\nSecond line of notes.","agree":"true","plan":"pro","country":"Poland"}' \
-o filled.pdf
The signature box is left untouched by the fill, and the fill output keeps it as an empty field. Sending a value for it, such as "signer":"x", returns 400 unsupported_field_type. With flatten=true the empty outline is baked into the page along with every other field.
Not sure what a PDF's fields are called? /api/inspect lists the names, types and options, including the ones you just added. Signature boxes show up there as unsupported.
Using this for real? A free API key raises the keyless 100 calls per IP to 250 requests a month, with no card.
Code examples
Have an API key? Add an X-API-Key header to any request. It is optional, and it raises your quota from 100/IP/month to your tier's.
JavaScript (Node.js 22+) — built-in fetch + FormData
import { readFile, writeFile } from 'node:fs/promises';
const fd = new FormData();
fd.append('pdf', new Blob([await readFile('agreement.pdf')], { type: 'application/pdf' }), 'agreement.pdf');
fd.append('fields', JSON.stringify([
{ type: 'text', name: 'full_name', page: 1, x: 160, y: 695, width: 240, height: 20 },
{ type: 'checkbox', name: 'agree', page: 1, x: 160, y: 518, width: 14, height: 14 },
]));
// The key is optional: send the header only when you have one.
const headers = process.env.PDFOPS_API_KEY ? { 'X-API-Key': process.env.PDFOPS_API_KEY } : {};
const res = await fetch('https://pdfops.dev/api/add-fields', { method: 'POST', headers, body: fd });
if (!res.ok) {
const err = await res.json();
throw new Error(`PDFops add-fields failed: ${err.error}: ${err.details}`);
}
await writeFile('fillable.pdf', Buffer.from(await res.arrayBuffer()));
Python — requests
import json, os, requests
fields = [
{"type": "text", "name": "full_name", "page": 1, "x": 160, "y": 695, "width": 240, "height": 20},
{"type": "checkbox", "name": "agree", "page": 1, "x": 160, "y": 518, "width": 14, "height": 14},
]
# The key is optional: send the header only when you have one.
headers = {"X-API-Key": os.environ["PDFOPS_API_KEY"]} if os.environ.get("PDFOPS_API_KEY") else {}
with open("agreement.pdf", "rb") as pdf:
res = requests.post(
"https://pdfops.dev/api/add-fields",
headers=headers,
files={"pdf": pdf},
data={"fields": json.dumps(fields)},
)
res.raise_for_status()
open("fillable.pdf", "wb").write(res.content)
From an AI agent (MCP)
The hosted MCP server at https://pdfops.dev/api/mcp exposes this as the pdf_add_fields tool, with pdf_path, fields and an optional password. The fields entries are the same objects as above, and the tool returns the PDF inline. Fill the result with pdf_fill. See PDFops for AI agents.
Behavioral notes
- The signature type is an empty signature field, not an e-signature. It is a box a signing tool can later sign into. Nothing is signed here, no certificate is added, and
/api/fill-formcannot fill it. For a visible signature image on the page use/api/edit; that is not a digital signature either. - The fields are standard AcroForm fields. There is no JavaScript, no calculated values and no validation script;
max_lengthand the dropdown's option list are the only constraints. - Standard fonts only. Fields use Helvetica, and text defaults and dropdown options must be in the WinAnsi set (
€,“,—andœwork;Łand CJK characters fail). Radio option values are never drawn, so they can be any text. - Appearance. Each new field is saved with its own appearance, so a default value, a tick or a selected button shows without a viewer recalculating anything. A viewer may still redraw a field itself, so text size can differ between viewers, most in auto-sized fields. We check rendering with poppler.
- The page content is not changed. Fields are added on top of the page, and fields already in the PDF are kept as they are.
- The output is deterministic. The same input gives the same bytes: the modification date and producer are pinned, and an existing creation date is kept.
- Limits: 4 MB per PDF, 2,000 pages, 200 fields and 200 widgets per request, 100 options per radio group or dropdown, 256 KB of
fields, 2,000 fields in the finished form, 4.5 MB per request (Vercel's platform limit).
FAQ
How do I make a PDF fillable with an API?
Send the PDF and a fields list. Each entry gives a type, a unique name, a page and a rectangle (x, y, width, height) in points from the bottom-left of the page. The response is the same PDF with standard AcroForm fields at those positions, which /api/fill-form and PDF viewers that support form filling can fill.
Does the signature field sign the document?
No. The signature type creates an empty signature field for a signing tool to use later. Nothing is signed and no certificate is added. To draw a visible signature image on the page, use /api/edit, which is also not a cryptographic signature.
How do I fill the fields I just added?
Send the output to /api/fill-form with an object that maps each field name to a string. A checkbox takes "true" or "false", a radio group takes one of the option values you created, and a dropdown takes one of its options.
Why is my long text cut off in a multiline field?
A field you create without font_size has a fixed size (12 pt, or smaller in a short box), so a value longer than the box is clipped at the bottom, not shrunk. Make the box taller or set a smaller font_size. Setting font_size to "auto" instead sizes the text when the field is first filled and then keeps that size, so a later, longer value can still be clipped.
Why was my field name rejected?
A name must be 1 to 200 characters with no dot, and it cannot match a field already in the PDF. Dots would make a parent and child field, and a name that matches the first part of an existing dotted name, such as form1 next to form1.name, is refused too. The error is duplicate_field or invalid_fields, and details names the entry.
Related: Fill form fields · Inspect a form · Stamp text and images.
Get a free API key. Keyless calls get 100 requests per IP per month; a free key raises that to 250, with no card. Enter your email and the key arrives in your inbox.