---
title: "List embedded AcroForm fields of the uploaded PDF"
method: GET
path: "/api/v1/documents/{id}/form-fields"
tags: ["Documents"]
---

# List embedded AcroForm fields of the uploaded PDF

`GET /api/v1/documents/{id}/form-fields`

## Request

- Base URL: `https://api.korala.ai`
- URL: `https://api.korala.ai/api/v1/documents/{id}/form-fields`
- Auth: one of:
  - API key in header `X-API-Key`
  - `bearer` (a scheme the document does not define)

Fillable PDFs (e.g. IRS tax forms like the W-9 or W-8BEN) embed their form fields in the file. This returns each field with its exact position, type, and name, so fields can be created with acroFieldName links instead of guessed coordinates. Returns an empty list for flat PDFs.

## Path parameters

- `id` string, required

## Response `200`

- AcroFormFieldDto[]
  - `name` string, required: Fully-qualified AcroForm field name (unique per field)
  - `kind` 'text' | 'checkbox' | 'radio' | 'dropdown' | 'signature', required: Kind of embedded form field
  - `pageNumber` number, required: 1-based page number
  - `xPosition` number, required: PDF points from the left edge (top-left origin)
  - `yPosition` number, required: PDF points from the top edge (top-left origin)
  - `width` number, required
  - `height` number, required
  - `maxLength` number: Maximum characters the form field accepts (comb/character boxes)
  - `multiline` boolean: Whether the text field is multiline
  - `comb` boolean: Comb field: characters sit in `maxLength` equally spaced cells
  - `label` string: The form author's tooltip (/TU) for this field — its human-readable label
  - `required` boolean: Whether the form itself marks this field as required
  - `readOnly` boolean: Read-only fields are computed or locked by the form and are never imported as signer-fillable fields
  - `fontSize` number: Point size from the field default appearance (/DA); absent when the form auto-sizes the text
  - `fontFamily` string: Base font the form draws this field with
  - `textColor` string: Text color from the field default appearance, as #rrggbb
  - `alignment` 'left' | 'center' | 'right': Horizontal alignment of the value inside the field box
  - `optionValue` string: For radio groups (one entry per option): the option export value
  - `options` string[]: For dropdowns/list boxes: the allowed values
  - `currentValue` string: Value already present in the PDF ('checked' for checked boxes)

## Other responses

- `400`: Malformed UUID in path parameter (`id`).

---

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