---
title: Forms and checkboxes | Developer Documentation
description: How Parse returns filled forms as structured JSON of labeled fields, values, checkbox and signature states, and fillable grids with the beta enriched forms option, plus spatial text for simpler form layouts.
---

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](../../../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](../../examples/enriched_forms/) 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](../../examples/enriched_forms/): walking the tree, select fields, and downloading the forms file, in every SDK
- [Configuring Parse: enriched forms output](../../guides/configuring-parse/#enriched-forms-output-beta)
- [Response format: forms](../../guides/response-format/#forms-beta) for every field and node type
- [Layout and bounding boxes](../layout-and-bounding-boxes/) for rendering field boxes on a page screenshot
- [OCR and languages](../ocr-and-languages/) for scanned and photographed forms