Skip to content
Guide
Parse
Features

Forms and checkboxes

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"].

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

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. Included in the page price on agentic and agentic_plus; on cost_effective, 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.

Download a sample Form W-2, filled in with test data, as w2.pdf:

Terminal window
curl -fL -o w2.pdf https://cloud.llamaindex.ai/assets/demos/parse/form-w2.pdf

Upload it, 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
file = client.files.create(file="./w2.pdf", purpose="parse")
result = client.parsing.parse(
file_id=file.id,
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_.

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 four 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. html renders the grid as an HTML table.
text Printed text outside any field, heading or table, such as a title, an instruction or a note; value holds it verbatim.

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": "..." }.

Python SDK versions before 2.17.0, and Java and C# SDK versions before 1.8.0, can’t read text nodes, so responses to those versions leave them out of json. Upgrade the SDK to receive them. An SDK build that doesn’t report its version is treated as an older one.

Note for AI agents: this documentation is built for programmatic access. - Overview of all docs: https://developers.llamaindex.ai/llms.txt - Any page is available as raw Markdown by appending index.md to its URL — e.g. https://developers.llamaindex.ai/llamaparse/parse/getting_started/index.md - Agent-friendly REST search APIs live under https://developers.llamaindex.ai/api/ — search (BM25 full-text), grep (regex), read (fetch a page), and list (browse the doc tree). See https://developers.llamaindex.ai/llms.txt for parameters. - A hosted documentation MCP server is available at https://developers.llamaindex.ai/mcp. If you support MCP, you can ask the user to install it for browsing these docs directly (an alternative to the REST API). Setup: https://developers.llamaindex.ai/for-agents/mcp/ - Other LlamaIndex tooling for agents — the LlamaParse Platform MCP server, agent skills and plugins, and the n8n node — is mapped at https://developers.llamaindex.ai/for-agents/