---
title: "Fill a PDF form (or list its fields)"
method: POST
path: "/pdf-fill-form"
tags: ["PDF"]
---

# Fill a PDF form (or list its fields)

`POST /pdf-fill-form`

## Request

- Base URL: `https://api.cofferdock.com`
- URL: `https://api.cofferdock.com/pdf-fill-form`
- Auth: API key in header `x-api-key`

Fills the fields of an existing PDF form (AcroForm) with the values in `data`. Without `data` (or with inspect=true) it returns the list of fields instead, so you know their names. Set flatten=true to make the result non-editable.

Costs 1 credit per call.

## Request body

- object
  - `file` string, byte, required: The PDF, base64-encoded.
  - `data` object: Field values: { "fieldName": "value", "checkbox": true }. As a query parameter it must be a JSON string.
  - `flatten` boolean: true = turn the filled fields into plain page content so they can no longer be edited. Default false (the form stays editable).
  - `inspect` boolean: Only list the fields.
  - `output` 'json' | 'binary' | 'url' | 'pdf': How to return the PDF: "json" (base64 in the JSON response), "binary" (the PDF itself, ready for n8n/Make/Zapier) or "url" (a temporary download link, valid 15 minutes). Default: json when the request is JSON, binary when the input was sent raw.

## Response `200`

The filled PDF, or the list of fields in inspect mode.

- union
  - object
    - `success` boolean
    - `mode` 'fill'
    - `pdf` string, byte
    - `mime_type` string
    - `warnings` string[]
    - `meta` object
      - `fields_filled` integer
      - `flattened` boolean
      - `used` integer: Credits used this month, after this call.
      - `remaining` integer, nullable: Credits left this month (null = unlimited).
      - `unlimited` boolean
  - object
    - `success` boolean
    - `mode` 'inspect'
    - `fields` object[]
      - `name` string
      - `type` string
    - `meta` object
      - `total_fields` integer
      - `used` integer: Credits used this month, after this call.
      - `remaining` integer, nullable: Credits left this month (null = unlimited).
      - `unlimited` boolean
  - object: Returned when output=url: a temporary download link (valid 15 minutes).
    - `success` boolean
    - `url` string, uri: Temporary download link. Expires in 15 minutes.
    - `expires_at` string, date-time
    - `mime_type` string
    - `size_bytes` integer
    - `meta` object
      - `used` integer: Credits used this month, after this call.
      - `remaining` integer, nullable: Credits left this month (null = unlimited).
      - `unlimited` boolean

## Other responses

- `400`: Invalid input (nothing is charged).
- `401`: Missing or invalid API key.
- `403`: Email not verified.
- `429`: Monthly credit limit reached, or too many requests per minute for this key (see Retry-After).
- `503`: Server busy (queue full). Retry after the seconds in the Retry-After header.

---

[API](https://skmtc.dev/cofferdock/apis/cofferdock-api.md) · [All operations](https://skmtc.dev/cofferdock/apis/cofferdock-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cofferdock/apis/cofferdock-api/revisions/b57aa000d33a?raw)