---

name: form-filler description: Fill PDF forms programmatically with data from JSON, CSV, or dictionaries. Support for text fields, checkboxes, and dropdowns. Batch filling available.

Form Filler

Fill PDF forms programmatically with structured data.

Features

• Field Detection: Auto-detect form fields
• Multiple Field Types: Text, checkbox, dropdown, radio
• Data Sources: JSON, CSV, dictionary input
• Batch Filling: Fill multiple forms from data file
• Field Mapping: Map data keys to field names
• Flatten Option: Convert to non-editable PDF
• Form Info: List all fields and their types

Quick Start

from form_filler import FormFiller

filler = FormFiller()

# Load form
filler.load("application_form.pdf")

# Fill fields
filler.fill({
    "name": "John Doe",
    "email": "john@example.com",
    "date": "2024-01-15",
    "agree": True  # Checkbox
})

# Save filled form
filler.save("filled_form.pdf")

CLI Usage

# Fill from JSON data
python form_filler.py --input form.pdf --data data.json --output filled.pdf

# List form fields
python form_filler.py --input form.pdf --list-fields

# Fill from CSV (batch)
python form_filler.py --input form.pdf --batch data.csv --output-dir filled/

# Flatten filled form
python form_filler.py --input form.pdf --data data.json --flatten --output filled.pdf

# With field mapping
python form_filler.py --input form.pdf --data data.json --mapping mapping.json -o filled.pdf

API Reference

FormFiller Class

class FormFiller:
    def __init__(self)

    # Loading
    def load(self, filepath: str) -> 'FormFiller'

    # Field Operations
    def list_fields(self) -> List[Dict]
    def get_field_info(self, field_name: str) -> Dict
    def get_field_value(self, field_name: str) -> Any

    # Filling
    def fill(self, data: Dict) -> 'FormFiller'
    def fill_field(self, name: str, value: Any) -> 'FormFiller'
    def fill_from_json(self, filepath: str) -> 'FormFiller'
    def fill_from_csv_row(self, row: Dict) -> 'FormFiller'

    # Field Mapping
    def set_mapping(self, mapping: Dict[str, str]) -> 'FormFiller'

    # Output
    def save(self, filepath: str, flatten: bool = False) -> str
    def flatten(self) -> 'FormFiller'

    # Batch Processing
    def batch_fill(self, input_form: str, data_file: str,
                  output_dir: str) -> List[str]

Field Types

Text Fields

filler.fill({
    "first_name": "John",
    "last_name": "Doe",
    "address": "123 Main St"
})

Checkboxes

filler.fill({
    "agree_terms": True,
    "subscribe": False
})

Radio Buttons

filler.fill({
    "gender": "male",  # Value of selected option
    "payment_method": "credit_card"
})

Dropdowns

filler.fill({
    "country": "USA",
    "state": "California"
})

Field Discovery

fields = filler.list_fields()
# Returns:
# [
#     {"name": "first_name", "type": "text", "required": True},
#     {"name": "agree_terms", "type": "checkbox", "value": False},
#     {"name": "country", "type": "dropdown", "options": ["USA", "Canada", "UK"]}
# ]

Field Mapping

Map data keys to form field names:

filler.set_mapping({
    "fname": "first_name",     # data key -> form field
    "lname": "last_name",
    "addr": "address_line_1"
})

filler.fill({
    "fname": "John",           # Uses mapping
    "lname": "Doe"
})

Batch Filling

From CSV

# CSV format:
# first_name,last_name,email
# John,Doe,john@example.com
# Jane,Smith,jane@example.com

filler.batch_fill(
    input_form="application.pdf",
    data_file="applicants.csv",
    output_dir="filled_forms/"
)
# Creates: filled_forms/application_0.pdf, application_1.pdf, ...

From JSON Array

# JSON format:
# [
#     {"first_name": "John", "last_name": "Doe"},
#     {"first_name": "Jane", "last_name": "Smith"}
# ]

filler.batch_fill(
    input_form="form.pdf",
    data_file="data.json",
    output_dir="output/"
)

Dependencies

• PyMuPDF>=1.23.0
• pillow>=10.0.0
• pandas>=2.0.0