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

# PDF Form Fields & Fill Form

> Extract form field metadata from a PDF and fill form fields programmatically

The PDF form tools let you inspect form fields in a PDF document, then fill them with values programmatically. This is a two-step workflow: first extract the field names and types, then fill the fields with your data.

## Workflow overview

1. **Upload** the PDF form via the [file upload endpoint](/api-reference/developer-api/upload-a-file)
2. **Extract fields** via `POST /tools/pdf/form-fields` — returns field names, types, options, and current values
3. **Fill fields** via `POST /tools/pdf/fill-form` — set values for each field by name
4. **Poll the job** via `GET /tools/jobs/{jobId}` until status is `COMPLETED`
5. **Download** the filled PDF via `GET /tools/files/{fileId}/download`

<Info>
  All files for tool actions must be uploaded via `POST /tools/files/upload` (the **tools** file upload). Do not use the temporary image upload endpoint (`POST /images/upload`) — that is only for render jobs (JSON/Markdown rendering). The two upload endpoints use separate storage systems.
</Info>

## Step 1: Extract form fields

Use the form-fields endpoint to discover what fields exist in a PDF.

### Request

```bash theme={null}
curl -X POST https://api.autype.com/api/v1/dev/tools/pdf/form-fields \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "fileId": "uploaded-pdf-id" }'
```

### Request body

| Property  | Type   | Required | Description                                                                                |
| --------- | ------ | -------- | ------------------------------------------------------------------------------------------ |
| `fileId`  | string | **Yes**  | File ID of the uploaded PDF containing form fields.                                        |
| `webhook` | object | No       | Optional [webhook configuration](/api-reference/webhooks) for job completion notification. |

### Response (after polling)

The form-fields action is **metadata-only** — there is no output file. The result is returned in the `metadata.fields` array of the completed job:

```json theme={null}
{
  "id": "job-123",
  "action": "pdf.form-fields",
  "status": "COMPLETED",
  "inputFileIds": ["uploaded-pdf-id"],
  "outputFileId": null,
  "error": null,
  "metadata": {
    "fields": [
      {
        "name": "FullName",
        "type": "text",
        "value": null,
        "isReadOnly": false
      },
      {
        "name": "Gender",
        "type": "radio",
        "value": null,
        "options": ["Male", "Female"],
        "isReadOnly": false
      },
      {
        "name": "Married",
        "type": "checkbox",
        "value": false,
        "isReadOnly": false
      },
      {
        "name": "City",
        "type": "dropdown",
        "value": null,
        "options": ["New York", "London", "Berlin", "Paris", "Rome"],
        "isReadOnly": false
      },
      {
        "name": "Language",
        "type": "optionlist",
        "value": null,
        "options": ["English", "German", "French", "Italian"],
        "isReadOnly": false
      },
      {
        "name": "Notes",
        "type": "text",
        "value": null,
        "isReadOnly": false
      }
    ]
  },
  "createdAt": "2026-02-23T12:00:00.000Z",
  "startedAt": "2026-02-23T12:00:01.000Z",
  "completedAt": "2026-02-23T12:00:02.000Z"
}
```

### Field object properties

Each field in the `metadata.fields` array has the following properties:

| Property     | Type                      | Description                                                                                  |
| ------------ | ------------------------- | -------------------------------------------------------------------------------------------- |
| `name`       | string                    | The field name as defined in the PDF. Use this name when filling the field.                  |
| `type`       | string                    | Field type: `"text"`, `"checkbox"`, `"dropdown"`, `"radio"`, `"optionlist"`, or `"unknown"`. |
| `value`      | string \| boolean \| null | Current value of the field. `null` if empty, `boolean` for checkboxes.                       |
| `options`    | string\[]                 | Available options (only for `dropdown`, `radio`, and `optionlist` fields).                   |
| `isReadOnly` | boolean                   | Whether the field is read-only and cannot be filled.                                         |

### Supported field types

| Type         | Description                           | Value format for filling                          |
| ------------ | ------------------------------------- | ------------------------------------------------- |
| `text`       | Text input field                      | `string`                                          |
| `checkbox`   | Checkbox (checked/unchecked)          | `boolean` (`true` = checked, `false` = unchecked) |
| `dropdown`   | Dropdown select (single choice)       | `string` (must match one of the `options`)        |
| `radio`      | Radio button group (single choice)    | `string` (must match one of the `options`)        |
| `optionlist` | Option list (single choice)           | `string` (must match one of the `options`)        |
| `unknown`    | Unsupported field type (e.g. buttons) | Cannot be filled                                  |

## Step 2: Fill form fields

Once you know the field names and types, use the fill-form endpoint to set values.

### Request

```bash theme={null}
curl -X POST https://api.autype.com/api/v1/dev/tools/pdf/fill-form \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fileId": "uploaded-pdf-id",
    "fields": {
      "FullName": "John Doe",
      "Gender": "Male",
      "Married": true,
      "City": "Berlin",
      "Language": "German",
      "Notes": "Additional information"
    },
    "flatten": false
  }'
```

### Request body

| Property  | Type    | Required | Description                                                                                                                 |
| --------- | ------- | -------- | --------------------------------------------------------------------------------------------------------------------------- |
| `fileId`  | string  | **Yes**  | File ID of the uploaded PDF with form fields.                                                                               |
| `fields`  | object  | **Yes**  | Map of field names to values. At least one field is required.                                                               |
| `flatten` | boolean | No       | If `true`, form fields are flattened after filling — they become static text and can no longer be edited. Default: `false`. |
| `webhook` | object  | No       | Optional [webhook configuration](/api-reference/webhooks) for job completion notification.                                  |

### Fields object

The `fields` object maps field names (as returned by the form-fields endpoint) to their values:

```json theme={null}
{
  "fields": {
    "FullName": "John Doe",
    "ID": "12345",
    "Gender": "Male",
    "Married": true,
    "City": "New York",
    "Language": "English",
    "Notes": "Test notes"
  }
}
```

<Warning>
  For `dropdown`, `radio`, and `optionlist` fields, the value must exactly match one of the available `options` returned by the form-fields endpoint. Mismatched values will be skipped.
</Warning>

### Response (after polling)

```json theme={null}
{
  "id": "job-456",
  "action": "pdf.fill-form",
  "status": "COMPLETED",
  "inputFileIds": ["uploaded-pdf-id"],
  "outputFileId": "filled-pdf-id",
  "error": null,
  "metadata": {
    "filledCount": 6,
    "flatten": false
  },
  "createdAt": "2026-02-23T12:00:00.000Z",
  "startedAt": "2026-02-23T12:00:01.000Z",
  "completedAt": "2026-02-23T12:00:02.000Z"
}
```

| Metadata property | Type    | Description                                     |
| ----------------- | ------- | ----------------------------------------------- |
| `filledCount`     | number  | Number of fields that were successfully filled. |
| `flatten`         | boolean | Whether the form was flattened.                 |

## Complete example

### 1. Upload the PDF form

```bash theme={null}
curl -X POST https://api.autype.com/api/v1/dev/tools/files/upload \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@form.pdf"
```

```json theme={null}
{
  "id": "form-file-id",
  "filename": "form.pdf",
  "mimeType": "application/pdf",
  "sizeBytes": 12351,
  "kind": "input",
  "sourceAction": null,
  "expiresAt": "2026-02-24T12:00:00.000Z",
  "createdAt": "2026-02-23T12:00:00.000Z"
}
```

### 2. Extract form fields

```bash theme={null}
curl -X POST https://api.autype.com/api/v1/dev/tools/pdf/form-fields \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "fileId": "form-file-id" }'
```

```json theme={null}
{ "id": "fields-job-id", "status": "PENDING" }
```

Poll until completed:

```bash theme={null}
curl https://api.autype.com/api/v1/dev/tools/jobs/fields-job-id \
  -H "X-API-Key: YOUR_API_KEY"
```

The `metadata.fields` array tells you exactly which fields exist, their types, and available options.

### 3. Fill the form

Use the field names and types from step 2:

```bash theme={null}
curl -X POST https://api.autype.com/api/v1/dev/tools/pdf/fill-form \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fileId": "form-file-id",
    "fields": {
      "FullName": "Jane Doe",
      "ID": "67890",
      "Gender": "Female",
      "Married": false,
      "City": "Berlin",
      "Language": "German",
      "Notes": "Filled via API"
    },
    "flatten": true
  }'
```

```json theme={null}
{ "id": "fill-job-id", "status": "PENDING" }
```

### 4. Poll and download

```bash theme={null}
# Poll for completion
curl https://api.autype.com/api/v1/dev/tools/jobs/fill-job-id \
  -H "X-API-Key: YOUR_API_KEY"

# Download the filled PDF
curl https://api.autype.com/api/v1/dev/tools/files/filled-pdf-id/download \
  -H "X-API-Key: YOUR_API_KEY" \
  -o filled-form.pdf
```

## Flatten vs. non-flatten

| Mode                       | Description                                   | Use case                                                              |
| -------------------------- | --------------------------------------------- | --------------------------------------------------------------------- |
| `flatten: false` (default) | Fields remain editable in the output PDF.     | When recipients need to modify values.                                |
| `flatten: true`            | Fields are converted to static text/graphics. | For final documents, archiving, or when fields should not be changed. |

<Info>
  Flattening is irreversible — once flattened, the form fields cannot be edited again. Always keep the original PDF if you need to re-fill with different values.
</Info>

## Error handling

| Scenario                                       | HTTP Status | Error                            |
| ---------------------------------------------- | ----------- | -------------------------------- |
| Missing `fileId`                               | 400         | `fileId is required`             |
| Empty `fields` object                          | 400         | `At least one field is required` |
| File is not a PDF                              | 400         | `Invalid file type`              |
| Field name not found in PDF                    | —           | Field is silently skipped        |
| Value type mismatch (e.g. string for checkbox) | —           | Field is silently skipped        |
| Dropdown/radio value not in options            | —           | Field is silently skipped        |