> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.datalab.to/llms.txt
> Use this file to discover all available pages before exploring further.

# Form Fields

> Find the fillable fields on each page of a PDF or image with the Datalab SDK.

## Overview

`form_fields()` finds every fillable field on each page of a PDF or image: blank lines, empty boxes, tick boxes and signature blanks. Each field has a type, a box and the printed label next to it.

## Basic Usage

```python theme={null}
from datalab_sdk import DatalabClient

client = DatalabClient()

result = client.form_fields("form.pdf")

for page in result.pages:
    for field in page["fields"]:
        print(page["page"], field["field_type"], field["bbox"], field["label"])
```

## Form Fields Options

```python theme={null}
from datalab_sdk import FormFieldsOptions

options = FormFieldsOptions(page_range="0-2", skip_cache=True)
result = client.form_fields("form.pdf", options=options)
```

| Option | Type | Default | Description |
| - | - | - | - |
| `max_pages` | int | None | Maximum pages to process. Do not combine it with `page_range`. |
| `page_range` | str | None | Pages to process, for example `"0-2"` |
| `skip_cache` | bool | `False` | Skip cached results |
| `webhook_url` | str | None | URL that receives a call when the request completes |
| `processing_location` | str | None | Residency region, for example `"eu"` |

## Form Fields Result

| Field | Type | Description |
| - | - | - |
| `success` | bool | Whether detection succeeded |
| `status` | str | Processing status |
| `pages` | list | One dict per page with `page`, `fields` and `error` |
| `page_count` | int | Number of pages processed |
| `runtime` | float | Processing time in seconds |
| `cost_breakdown` | dict | Cost details |

Each entry of `fields` has:

| Key | Description |
| - | - |
| `field_type` | One of `signature`, `initials`, `email`, `name`, `firstName`, `lastName`, `company`, `title`, `date`, `text`, `checkbox`, `radio` |
| `bbox` | `[x0, y0, x1, y1]` as fractions of the page width and height, origin at the top-left corner |
| `label` | The printed label, or an empty string |

A page with `error` set was not read, or the model repeated itself and its fields may be incomplete.

## Draw the Boxes

Multiply the fractions by the size of the page image:

```python theme={null}
from PIL import Image, ImageDraw

image = Image.open("page.png")
draw = ImageDraw.Draw(image)
width, height = image.size

for field in result.pages[0]["fields"]:
    x0, y0, x1, y1 = field["bbox"]
    draw.rectangle([x0 * width, y0 * height, x1 * width, y1 * height], outline="red", width=2)

image.save("page_fields.png")
```

## Saving the Result

```python theme={null}
result.save_output("output/form")  # writes output/form.form_fields.json
```

## From URL

```python theme={null}
result = client.form_fields(file_url="https://example.com/form.pdf")
```

## Async Usage

```python theme={null}
import asyncio
from datalab_sdk import AsyncDatalabClient

async def find_fields():
    async with AsyncDatalabClient() as client:
        result = await client.form_fields("form.pdf")
        return result.pages

asyncio.run(find_fields())
```

## CLI

```bash theme={null}
datalab form-fields form.pdf --output_dir output
```

The command takes a file or a folder, and the same `--page_range`, `--max_pages` and `--skip_cache` options as the other commands.

## Next Steps

> [card] [Form Fields Recipe](https://documentation.datalab.to/docs/recipes/form-fields/form-fields-api-overview.md)
>
> The API, the response format and the options.

> [card] [Form Filling SDK](https://documentation.datalab.to/docs/welcome/sdk/form-filling.md)
>
> Fill the fields you found.

> [card] [CLI](https://documentation.datalab.to/docs/welcome/sdk/cli.md)
>
> Process files and folders from the command line.

> [card] [File Management](https://documentation.datalab.to/docs/welcome/sdk/file-management.md)
>
> Upload, list, and manage files in Datalab storage.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.