Endpoints

Dry-run a fill by name

Same JSON Base64 pdf XOR templateId and values as fill, or the same multipart field pdf or templateId plus a values JSON object. Does not accept flatten. 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 whether the fill would succeed. written is the field count that would be written. Empty required names are listed in missingRequired as warnings. Fill still writes the PDF. No PDF bytes. Does not spend a unit. values keys are ISO fully qualified names (or the unique /T when there is only one). Omitted names stay unchanged. false is a value. Unknown names are unknown_field_name with close-match suggestions. A type mismatch is type_mismatch. A skipped import name is skipped_field_name. Validate-fill injects the same hosted appearance face as fill. The client does not send a TTF or a font field. A value that face cannot encode is appearance_unencodable (PdfPreserveFieldAppearanceError). One bad key fails the whole request. An empty required field is not a 400. A template with /NeedAppearances is rejected as need_appearances (PdfNeedAppearancesUnsupportedError). Password, XFA, and signed or certified templates are rejected as encrypted_pdf (PdfEncryptionUnsupportedError), xfa_unsupported (PdfXfaUnsupportedError), or signed_pdf (PdfSignedPdfUnsupportedError). Fill is not a second verb on POST /v1/render.

POST

validate-fill

curl --request POST \
  --url https://api.blinkpdf.io/v1/validate-fill \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "pdf": "<Base64>",
  "values": {
    "givenName": "Ada",
    "agree": true
  }
}
'

{
  "written": 1,
  "missingRequired": [
    "<string>"
  ]
}

{
  "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

values

object

required

Fill-by-name map. Keys are inspect names. Tx and Ch are strings, checkbox is boolean, radio is string or null. Omitted names stay unchanged. false is a value.

pdf

string<byte>

AcroForm PDF bytes, Base64-encoded. Does not store the PDF. 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

The fill body is acceptable. written is the field count that would be written. Empty required names are listed in missingRequired as warnings. Fill still writes the PDF. No PDF bytes are returned

written

integer

required

Field count that would be written. Omitted names are not counted.

Required range: x >= 0

missingRequired

string[]

required

Inspect names with /Ff Required that stay empty. Warnings. Fill still writes.

curl --request POST \
  --url https://api.blinkpdf.io/v1/validate-fill \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "pdf": "<Base64>",
  "values": {
    "givenName": "Ada",
    "agree": true
  }
}
'

{
  "written": 1,
  "missingRequired": [
    "<string>"
  ]
}

{
  "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."
}