PDF Form Fields & Fill Form

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

Upload the PDF form via the file upload endpoint
Extract fields via POST /tools/pdf/form-fields — returns field names, types, options, and current values
Fill fields via POST /tools/pdf/fill-form — set values for each field by name
Poll the job via GET /tools/jobs/{jobId} until status is COMPLETED
Download the filled PDF via GET /tools/files/{fileId}/download

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.

Step 1: Extract form fields

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

Request

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 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:

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

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 for job completion notification.

Fields object

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

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

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.

Response (after polling)

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

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

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

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" }'

{ "id": "fields-job-id", "status": "PENDING" }

Poll until completed:

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:

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
  }'

{ "id": "fill-job-id", "status": "PENDING" }

4. Poll and download

# 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.

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.

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

Overview

Document JSON Syntax

Tools Guides

Images

Rendering

Bulk Rendering

Projects & Documents

Tools File Management

Tools PDF Actions

Tools Document Actions

Lens (AI)

Tools Jobs

PDF Form Fields & Fill Form

Workflow overview

Step 1: Extract form fields

Request

Request body

Response (after polling)

Field object properties

Supported field types

Step 2: Fill form fields

Request

Request body

Fields object

Response (after polling)

Complete example

1. Upload the PDF form

2. Extract form fields

3. Fill the form

4. Poll and download

Flatten vs. non-flatten

Error handling

​Workflow overview

​Step 1: Extract form fields

​Request

​Request body

​Response (after polling)

​Field object properties

​Supported field types

​Step 2: Fill form fields

​Request

​Request body

​Fields object

​Response (after polling)

​Complete example

​1. Upload the PDF form

​2. Extract form fields

​3. Fill the form

​4. Poll and download

​Flatten vs. non-flatten

​Error handling

Workflow overview

Step 1: Extract form fields

Request

Request body

Response (after polling)

Field object properties

Supported field types

Step 2: Fill form fields

Request

Request body

Fields object

Response (after polling)

Complete example

1. Upload the PDF form

2. Extract form fields

3. Fill the form

4. Poll and download

Flatten vs. non-flatten

Error handling