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.
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 |
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
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"
}
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" }
curl https://api.autype.com/api/v1/dev/tools/jobs/fields-job-id \
-H "X-API-Key: YOUR_API_KEY"
metadata.fields array tells you exactly which fields exist, their types, and available options.
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 |
