Form Filling

The form filling API fills PDF and image forms with your structured data. It works with native PDF form fields and scanned/image forms. Before you begin, make sure you have:

A Datalab account with an API key (new accounts include $5 in free credits)
Python 3.10+ installed
The Datalab SDK: pip install datalab-python-sdk
Your DATALAB_API_KEY environment variable set

Quick Start

from datalab_sdk import DatalabClient, FormFillingOptions

client = DatalabClient()

options = FormFillingOptions(
    field_data={
        "name": {"value": "John Doe", "description": "Full name"},
        "email": {"value": "john@example.com", "description": "Email address"},
        "date": {"value": "12/15/2024", "description": "Today's date"},
    }
)

result = client.fill("form.pdf", options=options)
result.save_output("filled_form.pdf")

print(f"Fields filled: {result.fields_filled}")
print(f"Fields not found: {result.fields_not_found}")

curl -X POST https://www.datalab.to/api/v1/fill \
  -H "X-API-Key: $DATALAB_API_KEY" \
  -F "file=@form.pdf" \
  -F 'field_data={"name": {"value": "John Doe", "description": "Full name"}, "email": {"value": "john@example.com", "description": "Email address"}}'

# Poll request_check_url from response until status is "complete"
# Response includes output_base64 with the filled form

import requests, json, time, base64, os

headers = {"X-API-Key": os.getenv("DATALAB_API_KEY")}

field_data = {
    "name": {"value": "John Doe", "description": "Full name"},
    "email": {"value": "john@example.com", "description": "Email"},
    "date": {"value": "12/15/2024", "description": "Date"}
}

with open("form.pdf", "rb") as f:
    response = requests.post(
        "https://www.datalab.to/api/v1/fill",
        files={"file": ("form.pdf", f, "application/pdf")},
        data={"field_data": json.dumps(field_data), "confidence_threshold": "0.5"},
        headers=headers
    )

check_url = response.json()["request_check_url"]

while True:
    result = requests.get(check_url, headers=headers).json()
    if result["status"] == "complete":
        pdf_bytes = base64.b64decode(result["output_base64"])
        with open("filled_form.pdf", "wb") as f:
            f.write(pdf_bytes)
        print(f"Fields filled: {result['fields_filled']}")
        break
    elif result["status"] == "failed":
        print(f"Error: {result.get('error')}")
        break
    time.sleep(2)

See SDK Form Filling for complete SDK documentation.

How It Works

Upload your form (PDF or image) with field data
The API detects form fields and matches them to your data
Fields are filled and the form is returned as PDF or PNG

Field Data Format

Provide field names with values and descriptions:

field_data = {
    "field_key": {
        "value": "The value to fill",
        "description": "Description to help match the field"
    }
}

Examples

Basic fields:

field_data = {
    "first_name": {"value": "John", "description": "First name"},
    "last_name": {"value": "Doe", "description": "Last name"},
    "ssn": {"value": "123-45-6789", "description": "Social Security Number"}
}

Checkboxes:

field_data = {
    "is_citizen": {"value": "yes", "description": "US citizenship status"},
    "agree_terms": {"value": "checked", "description": "Terms agreement"}
}

Values like "yes", "true", "1", "checked", "x" will check boxes. Compound data:

field_data = {
    "full_address": {
        "value": "123 Main St, New York, NY, 10001",
        "description": "Complete address"
    }
}

The API can split compound data across multiple form fields.

Options

Option	Type	Default	Description
`field_data`	dict	Required	Field names mapped to values and descriptions
`context`	str	None	Additional context to help match fields
`confidence_threshold`	float	`0.5`	Minimum confidence for field matching (0.0-1.0)
`max_pages`	int	None	Maximum pages to process
`page_range`	str	None	Specific pages to process
`skip_cache`	bool	`False`	Skip cached results
`processing_location`	string	-	Data residency region: `"eu"` or `"us"`. When set, use `file_url` or a pre-uploaded `datalab://` reference — multipart uploads are not supported. EU carries a regional pricing premium.

Context Parameter

Use context to improve matching for specific form types:

options = FormFillingOptions(
    field_data={...},
    context="W-4 Employee's Withholding Certificate for new hire"
)

Response

Field	Type	Description
`status`	str	`processing`, `complete`, or `failed`
`success`	bool	Whether filling succeeded
`output_format`	str	`pdf` or `png`
`output_base64`	str	Base64-encoded filled form
`fields_filled`	list	Field names that were filled
`fields_not_found`	list	Field names that couldn’t be matched
`page_count`	int	Pages processed
`runtime`	float	Processing time in seconds
`cost_breakdown`	dict	Cost details

Supported Form Types

PDF with native AcroForm fields - Uses PDF form fields directly
PDF with visual fields - Detects field locations and adds text overlays
Images (PNG, JPG) - Detects field locations and draws text on image

The API automatically detects the input type and uses the appropriate method.

Results are deleted from Datalab servers one hour after processing completes.

Next Steps

SDK Form Filling

Complete SDK reference for form filling

File Upload

Upload forms for reuse across requests

Pipelines

Chain processors into versioned, reusable pipelines.

Webhooks

Get notified when form filling completes

General

Document Conversion

Structured Extraction

Document Segmentation

File Management

Pipelines

Create Document

Track Changes

Table Recognition (Deprecated)

Forge Evals

Form Filling

Quick Start

How It Works

Field Data Format

Examples

Options

Context Parameter

Response

Supported Form Types

Next Steps

SDK Form Filling

File Upload

Pipelines

Webhooks

​Quick Start

​How It Works

​Field Data Format

​Examples

​Options

​Context Parameter

​Response

​Supported Form Types

​Next Steps

SDK Form Filling

File Upload

Pipelines

Webhooks

Quick Start

How It Works

Field Data Format

Examples

Options

Context Parameter

Response

Supported Form Types

Next Steps