> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blinkpdf.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Fill a PDF form by name

> Inspect an AcroForm, send { name: value }, and get a filled PDF. Same bp_ key as render. Fill spends 1 unit. Inspect and validate-fill do not.

Blink PDF has **two verbs**. **Render** turns Markdown into a PDF. **Fill** takes a blank AcroForm plus a `{ name: value }` map and returns a filled PDF.

Fill is not a mode on `POST /v1/render`. There is no `/v1/forms` route — that path is `404`. Use the fill paths below with the same `bp_` key you already use to render.

## Paths

| Verb | Path | Spends a unit? |
| - | - | - |
| Inspect | `POST /v1/inspect` | No |
| Dry-run | `POST /v1/validate-fill` | No |
| Fill | `POST /v1/fill` | **1 unit** |
| Library | `/v1/templates` | No |

Send `pdf` (Base64 or a multipart file) **or** `templateId` — never both, never neither. Unknown, deleted, or another account's id is `404`.

<CardGroup cols={2}>
  <Card title="Inspect" icon="list-check" href="/fill/inspect">
    List fillable names and kinds before you write values.
  </Card>

  <Card title="Fill" icon="pen-to-square" href="/fill/fill">
    Write appearances, optional flatten, named errors, and validate-fill.
  </Card>

  <Card title="Templates" icon="box-archive" href="/fill/templates">
    Store a blank once, then fill by id. Account-owned, not key-owned.
  </Card>

  <Card title="MCP fill" icon="robot" href="/mcp/fill">
    `inspect_form` → `validate_fill` → `fill_form` for agents.
  </Card>
</CardGroup>

## Inspect, then fill (under five minutes)

The same `bp_` key as render. This synthetic intake has two fields: `givenName` (text) and `agree` (checkbox). It is not a real-world form.

```bash theme={null}
export BLINKPDF_API_KEY="bp_xxxxxxxxxxxxxxxxxxxx"

INTAKE_PDF='JVBERi0xLjcKMSAwIG9iago8PCAvVHlwZSAvQ2F0YWxvZyAvUGFnZXMgMiAwIFIgL0Fjcm9Gb3JtIDQgMCBSID4+CmVuZG9iagoyIDAgb2JqCjw8IC9UeXBlIC9QYWdlcyAvS2lkcyBbMyAwIFJdIC9Db3VudCAxID4+CmVuZG9iagozIDAgb2JqCjw8IC9UeXBlIC9QYWdlIC9QYXJlbnQgMiAwIFIgL01lZGlhQm94IFswIDAgNDAwIDUwMF0gL0NvbnRlbnRzIDUgMCBSIC9SZXNvdXJjZXMgPDwgPj4gL0Fubm90cyBbNiAwIFIgNyAwIFJdID4+CmVuZG9iago0IDAgb2JqCjw8IC9GaWVsZHMgWzYgMCBSIDcgMCBSXSAvREEgKC9IZWx2IDEyIFRmIDAgZykgL0RSIDw8IC9Gb250IDw8IC9IZWx2IDEwIDAgUiA+PiA+PiA+PgplbmRvYmoKNSAwIG9iago8PCAvTGVuZ3RoIDE4ID4+CnN0cmVhbQoxMDAgMTAwIDUwIDUwIHJlCmYKZW5kc3RyZWFtCmVuZG9iago2IDAgb2JqCjw8IC9UIChnaXZlbk5hbWUpIC9GVCAvVHggL1YgKCkgL0RBICgvSGVsdiAxMiBUZiAwIGcpIC9TdWJ0eXBlIC9XaWRnZXQgL1JlY3QgWzIwIDQ0MCAxMjAgNDcwXSAvUCAzIDAgUiA+PgplbmRvYmoKNyAwIG9iago8PCAvVCAoYWdyZWUpIC9GVCAvQnRuIC9WIC9PZmYgL0FTIC9PZmYgL0FQIDw8IC9OIDw8IC9PZmYgOCAwIFIgL1llcyA5IDAgUiA+PiA+PiAvU3VidHlwZSAvV2lkZ2V0IC9SZWN0IFsyMCA0MDAgMzYgNDE2XSAvUCAzIDAgUiA+PgplbmRvYmoKOCAwIG9iago8PCAvVHlwZSAvWE9iamVjdCAvU3VidHlwZSAvRm9ybSAvQkJveCBbMCAwIDE2IDE2XSAvTGVuZ3RoIDEyID4+CnN0cmVhbQowIDAgMTAgMTAgcmUKZW5kc3RyZWFtCmVuZG9iago5IDAgb2JqCjw8IC9UeXBlIC9YT2JqZWN0IC9TdWJ0eXBlIC9Gb3JtIC9CQm94IFswIDAgMTYgMTZdIC9MZW5ndGggMTEgPj4Kc3RyZWFtCjkgOSBtIDEgMSBsCmVuZHN0cmVhbQplbmRvYmoKMTAgMCBvYmoKPDwgL1R5cGUgL0ZvbnQgL1N1YnR5cGUgL1R5cGUxIC9CYXNlRm9udCAvSGVsdmV0aWNhIC9FbmNvZGluZyAvV2luQW5zaUVuY29kaW5nID4+CmVuZG9iagp4cmVmCjAgMTEKMDAwMDAwMDAwMCA2NTUzNSBmIAowMDAwMDAwMDA5IDAwMDAwIG4gCjAwMDAwMDAwNzQgMDAwMDAgbiAKMDAwMDAwMDEzMSAwMDAwMCBuIAowMDAwMDAwMjU3IDAwMDAwIG4gCjAwMDAwMDAzNTcgMDAwMDAgbiAKMDAwMDAwMDQyNSAwMDAwMCBuIAowMDAwMDAwNTQ2IDAwMDAwIG4gCjAwMDAwMDA2OTMgMDAwMDAgbiAKMDAwMDAwMDgwMyAwMDAwMCBuIAowMDAwMDAwOTEyIDAwMDAwIG4gCnRyYWlsZXIKPDwgL1NpemUgMTEgL1Jvb3QgMSAwIFIgPj4Kc3RhcnR4cmVmCjEwMTAKJSVFT0YK'

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\":\"${INTAKE_PDF}\"}"

curl https://api.blinkpdf.io/v1/fill \
  --request POST \
  --header "x-api-key: ${BLINKPDF_API_KEY}" \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/pdf' \
  --data "{\"pdf\":\"${INTAKE_PDF}\",\"values\":{\"givenName\":\"Ada\",\"agree\":true}}" \
  --output intake-filled.pdf
```

Inspect returns JSON names. Fill returns `application/pdf` with written appearances. Open `intake-filled.pdf` — the text already shows. Do not set `/NeedAppearances`.

<Tip>
  On **Free**, a real form often exceeds the 128 KiB fill-by-bytes body. [Store the blank](/fill/templates), then fill with `{ "templateId": "<id>", "values": { … } }`.
</Tip>

## Rules that stay true

* **Same key.** A `bp_` key that can render can fill. Do not mint a fill key.
* **One unit.** A successful `POST /v1/fill` costs **1 unit** on the same allowance as render. Inspect, validate-fill, and the template library do not spend a unit.
* **Atomic values.** One bad key fails the whole request. No silent drop. `false` is a value (checkbox Off), not an omit.
* **Never `/NeedAppearances`.** A template that already has the flag is rejected (`need_appearances`). The filled PDF never includes it.
* **REST streams.** `POST /v1/fill` does not keep the output. MCP `fill_form` returns a signed download link (24 hours unless you persist).

See [Pricing](/plans/pricing) for units and template caps, and [Zero Retention](/concepts/zero-retention) for what happens to fill values.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.