POST /api/inspect

This is the first call in the natural workflow: inspect to learn the field names, fill-form to set them, merge to combine the results. You can't fill fields whose names you don't know.

Request

Method: POST. URL: https://pdfops.dev/api/inspect. Body: multipart/form-data.

Successful (2xx) calls count 1 request against your quota — the same meter as the other PDF endpoints. Check consumption with GET /api/usage.

Response

On success: 200 OK, Content-Type: application/json:

{
  "count": 4,
  "fields": [
    { "name": "customer_name", "type": "text", "value": "", "readOnly": false },
    { "name": "agreed_to_terms", "type": "checkbox", "checked": false, "readOnly": false },
    { "name": "plan", "type": "radio", "value": "Starter", "options": ["Starter", "Pro"], "readOnly": false },
    { "name": "approval", "type": "unsupported", "raw": "PDFSignature", "readOnly": false }
  ],
  "fillTemplate": {
    "customer_name": "",
    "agreed_to_terms": "true",
    "plan": "Starter"
  }
}

A PDF with no AcroForm returns 200 with {"count": 0, "fields": [], "fillTemplate": {}} — deliberately not an error, because "does this PDF have fields?" is exactly the question you're asking.

On any failure: 4xx, Content-Type: application/json, body is { "error": "<code>", "details": "<explanation>" }.

Field objects

How type maps to AcroForm classes and which extra property each carries:

Error codes

Note there's no no_form error here: a form-less PDF is a valid answer (count: 0), not a failure.

Example — curl

Don't have a fillable PDF? Grab the sample invoice-template.pdf with customer_name + total fields.

curl -X POST https://pdfops.dev/api/inspect \
  -F "pdf=@invoice-template.pdf" \
  -H "X-API-Key: pdfops_live_..."  # optional — raises your quota to your tier

Example — JavaScript: inspect, then fill

fillTemplate is shaped so it pipes straight into /api/fill-form — overwrite the placeholders and send:

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

const pdf = await readFile('invoice-template.pdf');
const blob = new Blob([pdf], { type: 'application/pdf' });

// 1. Inspect — learn the field names.
const fd = new FormData();
fd.append('pdf', blob, 'invoice-template.pdf');
const { fillTemplate } = await (
  await fetch('https://pdfops.dev/api/inspect', { method: 'POST', body: fd })
).json();

// 2. Fill — overwrite the placeholders, pipe the template into fill-form.
const fields = { ...fillTemplate, customer_name: 'Acme Co', total: '$1,250.00' };
const fillFd = new FormData();
fillFd.append('pdf', blob, 'invoice-template.pdf');
fillFd.append('fields', JSON.stringify(fields));
const res = await fetch('https://pdfops.dev/api/fill-form', { method: 'POST', body: fillFd });

await writeFile('filled.pdf', Buffer.from(await res.arrayBuffer()));

FAQ

← All docs · PDFops home