Inspect an AcroForm

POST /v1/inspect returns every fillable field plus skipped import names. Use those name values as keys on fill. Do not invent /T tokens. Not POST /v1/render. Does not accept values. Does not store the PDF. Does not write appearances. Does not spend a unit.

Send

JSON { "pdf": "<Base64>" } or { "templateId": "…" } — exactly one. Multipart pdf (file) or templateId works the same. Same x-api-key as render.

curl https://api.blinkpdf.io/v1/inspect \
  --request POST \
  --header "x-api-key: ${BLINKPDF_API_KEY}" \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{"pdf":"<Base64>"}'

curl https://api.blinkpdf.io/v1/inspect \
  --request POST \
  --header "x-api-key: ${BLINKPDF_API_KEY}" \
  --header 'Accept: application/json' \
  -F [email protected]

curl https://api.blinkpdf.io/v1/inspect \
  --request POST \
  --header "x-api-key: ${BLINKPDF_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{"templateId":"<id>"}'

A copy-paste synthetic form is in the fill overview and the Quickstart. Unknown, deleted, or another account’s templateId is 404. Sending both pdf and templateId is 400. Extra keys such as values are 400.

What you get

{
  "fields": [
    {
      "name": "givenName",
      "kind": "Tx",
      "required": false,
      "value": "",
      "widgets": [{ "page": 0, "rect": [20, 30, 120, 60] }]
    },
    {
      "name": "agree",
      "kind": "checkbox",
      "required": false,
      "value": false,
      "widgets": [{ "page": 0, "rect": [20, 84, 36, 100] }]
    }
  ],
  "skipped": [],
  "warnings": []
}

Fields

Key	Role
`name`	ISO fully qualified name. Same key fill accepts. A form whose only name is one `/T` uses that unique `/T`.
`kind`	`Tx` / `checkbox` / `radio` / `Ch`. Pushbutton is not a kind.
`required`	`/Ff` Required. Metadata only — validate-fill lists empty required names in `missingRequired`; fill does not 400.
`options`	Radio/choice export values. Present on `radio` and `Ch`.
`maxLen`	Positive `/MaxLen`. Omitted when absent or unlimited (`0`).
`multiline`	`true` when the Multiline bit is set. Omitted for single-line.
`value`	Current `/V`: `Tx`/`Ch` string, checkbox boolean, radio string or `null`.
`widgets[]`	`{ page, rect }`. `page` is 0-based. One name may have many placements. One fill value paints every placement.

Skipped

skipped[] is { name, reason }. Filling a skipped name is 400 skipped_field_name — no silent drop.

`reason`	Why import omitted the name
`signature`	`/FT /Sig`
`pushbutton`	`/FT /Btn` + Pushbutton
`unmodeledFieldType`	`/FT` other than `Tx` / `Btn` / `Ch` / `Sig`
`choiceEdit`	Choice Edit bit
`choiceMultiSelect`	Choice MultiSelect bit
`choiceArrayValue`	Choice `/V` array

Warnings

warnings[] is always present. Empty when every fillable name has one widget.

`code`	When
`multi_widget`	`widgets.length` > 1. One fill-by-name value paints every placement. Radio options are not this warning.

No widgets

fields: [] and skipped: [] include reason: "no_widgets". That reason is omitted when fields or skipped is non-empty. If the PDF has no widgets, make it a form in studio first. Inspect is not a map editor.

Limits and rejects

Inspect is unmetered. It still sits on the same plan ratePerMin and concurrency limiters as fill — a burst is 429 rate_limited. It does not apply plan bodyBytes to live pdf bytes. Templates with no /AcroForm, /NeedAppearances, a password, XFA, or a document signature are rejected by name (no_acroform, need_appearances, encrypted_pdf, xfa_unsupported, signed_pdf). See Fill errors.

Persist the blank with POST /v1/templates if you want to inspect and fill by id later. Inspect itself does not store.

Get Started

Fill a form

Core Concepts

Guides

MCP Server

Configuration

Plans & Limits

Help

Inspect an AcroForm

Send

What you get

Fields

Skipped

Warnings

No widgets

Limits and rejects

​Send

​What you get

​Fields

​Skipped

​Warnings

​No widgets

​Limits and rejects

Send

What you get

Fields

Skipped

Warnings

No widgets

Limits and rejects