Endpoints

List fillable AcroForm fields

Accepts template bytes as JSON Base64 (pdf) or multipart field pdf, or templateId XOR pdf for a stored blank template (same store as GET /v1/templates/:id). Same x-api-key as render. Does not apply plan bodyBytes to live pdf bytes. Stays request/response and unmetered. Sits on plan ratePerMin and concurrency (same post-auth limiters as fill). Burst is 429 rate_limited. Returns every fillable field (name, kind, required, options, current /V, widgets) plus skipped import names and warnings. A name with more than one widget lists every {page,rect}. Cloned placements also get a multi_widget warning: one fill-by-name value paints every placement. Radio options are not that warning. A PDF with no widgets inspects to fields: [] plus reason no_widgets. If the PDF has no widgets, make it a form in studio first. Does not store the PDF. Does not spend a unit. Does not write a filled PDF. Does not accept values. A template with no /AcroForm, /NeedAppearances, a password, XFA, or a document signature or certification is rejected (no_acroform, need_appearances (PdfNeedAppearancesUnsupportedError), encrypted_pdf (PdfEncryptionUnsupportedError), xfa_unsupported (PdfXfaUnsupportedError), or signed_pdf (PdfSignedPdfUnsupportedError)). Not a second verb on POST /v1/render.

POST

inspect

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

{
  "fields": "<array>",
  "skipped": "<array>",
  "warnings": "<array>",
  "reason": "no_widgets"
}

{
  "error": "unauthorized"
}

{
  "error": "payload_too_large"
}

{
  "error": "rate_limited",
  "detail": "Tier rate limit exceeded. Retry after the Retry-After interval or upgrade for higher sustained throughput."
}

{
  "error": "service_unavailable",
  "detail": "Subscription tier lookup is temporarily unavailable. Retry the request."
}

Authorizations

x-api-key

string

header

required

API key issued from your Blink PDF account, prefixed bp_. Send it in the x-api-key header on every request. The documentation and health endpoints are exempt.

Body

pdf

string<byte>

AcroForm PDF bytes, Base64-encoded. Does not store the PDF. Does not spend a unit. XOR with templateId.

templateId

string

Stored template id from POST /v1/templates. XOR with pdf. Same store as GET /v1/templates/:id. Unknown, deleted, or foreign is 404.

Response

Fillable fields plus skipped import names and warnings. A name with more than one widget lists widgets. Cloned placements also include multi_widget; radio options do not. Or fields: [] plus reason no_widgets when the PDF has no widgets. Names are the keys fill accepts

fields

array

required

Fillable terminals. name is the fill-by-name key.

skipped

array

required

Import-omitted names (signature, pushbutton, …).

warnings

array

required

Always present. multi_widget when a name has more than one placement.

reason

string

Present when fields and skipped are both empty. Make it a form in studio first.

Allowed value: "no_widgets"

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

{
  "fields": "<array>",
  "skipped": "<array>",
  "warnings": "<array>",
  "reason": "no_widgets"
}

{
  "error": "unauthorized"
}

{
  "error": "payload_too_large"
}

{
  "error": "rate_limited",
  "detail": "Tier rate limit exceeded. Retry after the Retry-After interval or upgrade for higher sustained throughput."
}

{
  "error": "service_unavailable",
  "detail": "Subscription tier lookup is temporarily unavailable. Retry the request."
}