Skip to main content
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:
  1. A Datalab account with an API key (new accounts include $5 in free credits)
  2. Python 3.10+ installed
  3. The Datalab SDK: pip install datalab-python-sdk
  4. 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}")
See SDK Form Filling for complete SDK documentation.

​
How It Works

  1. Upload your form (PDF or image) with field data
  2. The API detects form fields and matches them to your data
  3. 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

OptionTypeDefaultDescription
field_datadictRequiredField names mapped to values and descriptions
contextstrNoneAdditional context to help match fields
confidence_thresholdfloat0.5Minimum confidence for field matching (0.0-1.0)
max_pagesintNoneMaximum pages to process
page_rangestrNoneSpecific pages to process
skip_cacheboolFalseSkip cached results

​
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

FieldTypeDescription
statusstrprocessing, complete, or failed
successboolWhether filling succeeded
output_formatstrpdf or png
output_base64strBase64-encoded filled form
fields_filledlistField names that were filled
fields_not_foundlistField names that couldn’t be matched
page_countintPages processed
runtimefloatProcessing time in seconds
cost_breakdowndictCost 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

Workflows

Chain form filling with other processing steps

Webhooks

Get notified when form filling completes