Form Filling

Overview

The form filling API lets you programmatically fill forms in PDFs and images. It works with both:

Native PDF forms - Forms with actual form fields
Image-based forms - Scanned forms or images with visual form layouts

The API matches your field data to form fields and returns a filled PDF or image.

Basic Usage

from datalab_sdk import DatalabClient, FormFillingOptions

client = DatalabClient()

options = FormFillingOptions(
    field_data={
        "full_name": {"value": "John Doe", "description": "Full legal name"},
        "date_of_birth": {"value": "1990-01-15", "description": "Date of birth"},
        "address": {"value": "123 Main St, City, ST 12345", "description": "Mailing address"},
    }
)

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

Form Filling 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 (e.g., `"0-2"`). For spreadsheets, filters by sheet index.
`skip_cache`	bool	`False`	Skip cached results

Field Data Format

Each field in field_data is a dictionary with:

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

The description helps the API match your field key to the actual form field, especially when field names in the PDF don’t match your data structure.

Example with Multiple Field Types

options = FormFillingOptions(
    field_data={
        # Text fields
        "name": {"value": "Jane Smith", "description": "Full name"},
        "email": {"value": "jane@example.com", "description": "Email address"},

        # Date fields
        "date": {"value": "2024-01-15", "description": "Today's date"},

        # Numeric fields
        "amount": {"value": "1500.00", "description": "Total amount"},

        # Checkbox (use descriptive value)
        "agree_terms": {"value": "Yes", "description": "Agreement checkbox"},

        # Signature (text is rendered)
        "signature": {"value": "Jane Smith", "description": "Signature field"},
    },
    context="This is an employment application form"
)

Using Context

The context parameter provides additional information to improve field matching:

options = FormFillingOptions(
    field_data={
        "ssn": {"value": "123-45-6789", "description": "Social Security Number"},
        "employer": {"value": "Acme Corp", "description": "Current employer name"},
    },
    context="W-4 tax withholding form for new employee onboarding"
)

Confidence Threshold

Adjust confidence_threshold to control field matching strictness:

options = FormFillingOptions(
    field_data={...},
    confidence_threshold=0.7,  # Higher = more strict matching
)

Lower values (0.3-0.5): More fields matched, but may have incorrect matches
Higher values (0.7-0.9): Fewer fields matched, but more accurate

Form Filling Result

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

# Check results
print(result.success)           # True if filling succeeded
print(result.status)            # "complete" when done
print(result.output_format)     # "pdf" or "png"
print(result.fields_filled)     # List of successfully filled fields
print(result.fields_not_found)  # List of fields that couldn't be matched
print(result.page_count)        # Number of pages processed
print(result.cost_breakdown)    # Cost details

Result Fields

Field	Type	Description
`success`	bool	Whether form filling succeeded
`status`	str	Processing status
`output_format`	str	Output type: `"pdf"` or `"png"`
`output_base64`	str	Base64-encoded filled form
`fields_filled`	list	Field names that were successfully filled
`fields_not_found`	list	Field names that couldn’t be matched
`page_count`	int	Number of pages processed
`runtime`	float	Processing time in seconds
`cost_breakdown`	dict	Cost details

Saving the Filled Form

# Save to file
result.save_output("filled_form.pdf")

# Or access the raw base64 data
import base64
pdf_bytes = base64.b64decode(result.output_base64)
with open("filled.pdf", "wb") as f:
    f.write(pdf_bytes)

Filling Image Forms

The API also works with image-based forms (PNG, JPG, etc.):

result = client.fill("scanned_form.png", options=options)
result.save_output("filled_form.png")  # Returns filled image

For images, the output is a PNG with the field values rendered onto the image.

From URL

Fill a form from a URL:

result = client.fill(
    file_url="https://example.com/form.pdf",
    options=options
)

Async Usage

import asyncio
from datalab_sdk import AsyncDatalabClient, FormFillingOptions

async def fill_form():
    async with AsyncDatalabClient() as client:
        options = FormFillingOptions(
            field_data={
                "name": {"value": "John Doe", "description": "Full name"},
            }
        )
        result = await client.fill("form.pdf", options=options)
        result.save_output("filled.pdf")

asyncio.run(fill_form())

Handling Unmatched Fields

Check which fields couldn’t be matched:

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

if result.fields_not_found:
    print("These fields couldn't be matched:")
    for field in result.fields_not_found:
        print(f"  - {field}")

    # Consider adjusting descriptions or lowering confidence threshold

Example: Tax Form

from datalab_sdk import DatalabClient, FormFillingOptions

client = DatalabClient()

options = FormFillingOptions(
    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"},
        "address": {"value": "123 Main Street", "description": "Street address"},
        "city": {"value": "Springfield", "description": "City"},
        "state": {"value": "IL", "description": "State abbreviation"},
        "zip": {"value": "62701", "description": "ZIP code"},
        "filing_status": {"value": "Single", "description": "Filing status"},
        "signature": {"value": "John Doe", "description": "Taxpayer signature"},
        "date": {"value": "2024-04-15", "description": "Date signed"},
    },
    context="IRS W-4 Employee's Withholding Certificate"
)

result = client.fill("w4_form.pdf", options=options)

print(f"Filled {len(result.fields_filled)} fields")
print(f"Unmatched: {result.fields_not_found}")

result.save_output("w4_filled.pdf")

Next Steps

Form Filling Recipe

Detailed guide on form filling with field matching and templates.

File Management

Upload, list, and manage files in Datalab storage.

Conversion SDK

Convert documents to Markdown, HTML, JSON, or chunks.

Pipelines

Chain processors into versioned, reusable pipelines.

Welcome

On-prem

Platform

Overview

Basic Usage

Form Filling Options

Field Data Format

Example with Multiple Field Types

Using Context

Confidence Threshold

Form Filling Result

Result Fields

Saving the Filled Form

Filling Image Forms

From URL

Async Usage

Handling Unmatched Fields

Example: Tax Form

Next Steps

Form Filling Recipe

File Management

Conversion SDK

Pipelines

​Overview

​Basic Usage

​Form Filling Options

​Field Data Format

​Example with Multiple Field Types

​Using Context

​Confidence Threshold

​Form Filling Result

​Result Fields

​Saving the Filled Form

​Filling Image Forms

​From URL

​Async Usage

​Handling Unmatched Fields

​Example: Tax Form

​Next Steps

Form Filling Recipe

File Management

Conversion SDK

Pipelines

Overview

Basic Usage

Form Filling Options

Field Data Format

Example with Multiple Field Types

Using Context

Confidence Threshold

Form Filling Result

Result Fields

Saving the Filled Form

Filling Image Forms

From URL

Async Usage

Handling Unmatched Fields

Example: Tax Form

Next Steps