Forms and checkboxes

Beta

With processing_options.forms set to "enrich", Parse runs an additional form-analysis pass on the pages it detects as forms and returns each one as structured JSON: sections, labeled fields with their entered values, checkbox and signature states, fillable grids, and a bounding box per field. The regular markdown and items output is returned alongside. Read the JSON back with expand=["forms"].

Beta

Enriched forms output is in beta. It is being actively improved. The output shape and field vocabulary may still change.

When to use it

• Loading filled forms into your own system, keyed by the field ids printed on the form (1a, Part III, box 13).
• Telling blank fields from filled ones, and reading checkbox and signature state directly instead of inferring it from text.
• Building a review UI that highlights where on the page each field value came from.
• Key-value extraction from tax forms, applications, claims, and intake sheets, scanned or digital.

If you only need the text laid out as it appears on the page, output_options.spatial_text is a lighter alternative that works on every tier. For a guaranteed JSON shape defined by your own schema, use Extract instead.

Options

Option	Type	Default	What it does
processing_options.forms	"default" or "enrich"	"default"	"enrich" runs the form pass on pages detected as forms. Not available on fast. Adds 10 credits per page containing a form; pages with no form return an empty forms list at no extra cost.
output_options.spatial_text	object	unset	Whitespace-preserving text for forms and receipts. Retrieve with expand=["text"].
input_options.image.camera_photo_correction	boolean	unset	For photographed forms: crop, perspective-correct, and flatten lighting before parsing.

Retrieve the result with expand=["forms"] for inline JSON, or expand=["forms_content_metadata"] for a presigned download URL to the same JSON as a file. In the Web UI, turn on Enriched forms output under Processing Options > Forms; the result page then gains a Forms tab.

Example

Turn on the form pass and print each form as a flattened field list:

from llama_cloud import LlamaCloud

client = LlamaCloud()  # reads LLAMA_CLOUD_API_KEY from the environment

result = client.parsing.parse(
    file_id="FILE_ID",  # uploaded with client.files.create(file=..., purpose="parse")
    tier="agentic",
    version="latest",
    processing_options={"forms": "enrich"},
    expand=["forms"],
)

for page in result.forms.pages:
    if not page.success:
        print(f"page {page.page_number} failed: {page.error}")
        continue
    for form in page.forms:
        print(form.list.md)  # flattened "label: value" bullets, ready for a prompt

The enriched forms example installs llama-cloud>=2.15, the version that carries the forms result fields. In the Python SDK, camelCase API fields are exposed in snake_case (valueItems is value_items, isEmpty is is_empty), and json is exposed as json_.

What you get

result.forms.pages has one entry per page. Each detected form carries the same content twice: json, the structured tree, and list, a flattened bullet list whose md drops straight into a prompt. This trimmed excerpt is from a filled W-2:

{
  "page_number": 1, "page_width": 612, "page_height": 792, "success": true,
  "forms": [{
    "json": [
      { "type": "field", "field": "text", "id": "1", "label": "Wages, tips, other compensation", "value": "29,513",
        "bbox": [{ "x": 349.2, "y": 96.5, "w": 114.0, "h": 12.2 }] },
      { "type": "field", "field": "text", "id": "d", "label": "Control number", "isEmpty": true },
      { "type": "field", "field": "multi_select", "id": "13", "valueItems": [
        { "type": "field", "field": "checkbox", "label": "Statutory employee", "value": true },
        { "type": "field", "field": "checkbox", "label": "Retirement plan", "value": false } ] }
    ],
    "list": { "md": "- [1] Wages, tips, other compensation: 29,513\n- [d] Control number:\n- [13]\n  - [x] Statutory employee\n  - [ ] Retirement plan" }
  }]
}

The tree has three node types:

type	Meaning
section	A grouping printed on the form (Part III, box 15); items holds its children in reading order.
field	One entry. field is text, checkbox, single_select, multi_select, or signature.
table	A fillable grid with columns and rows; a cell is a string, null when blank, or { "items": [...] } holding its own fields.

How value reads depends on the field kind: text holds the entered text verbatim, and a blank field has isEmpty: true and no value; checkbox and signature hold a boolean, checked or signed; single_select and multi_select have no value and list their options in valueItems, each usually a checkbox with its own boolean. bbox is in page points, the same coordinate space as items. Always check success before reading a page: a page whose form pass failed is { "page_number": N, "success": false, "error": "..." }.

See also

• Enriched forms output example: walking the tree, select fields, and downloading the forms file, in every SDK
• Configuring Parse: enriched forms output
• Response format: forms for every field and node type
• Layout and bounding boxes for rendering field boxes on a page screenshot
• OCR and languages for scanned and photographed forms