Edit

Introduction

The edit API in Retab’s document processing pipeline enables intelligent document form filling. It supports PDF, Word (DOCX), Excel (XLSX), and PowerPoint (PPTX) files, automatically detecting fillable elements and populating them based on natural language instructions. This is ideal for automating form completion workflows, document generation, and batch processing of standardized forms.

Supported Formats

Format	Extension	Processing Method
PDF	`.pdf`	Computer vision + LLM form field detection
Word	`.docx`, `.doc`, `.odt`	Native XML editing (preserves formatting)
Excel	`.xlsx`, `.xls`, `.ods`	Native cell editing
PowerPoint	`.pptx`, `.ppt`, `.odp`	Native shape/text editing

How It Works

For PDF files:

Computer Vision: Detect form field bounding boxes with precise coordinates
LLM Inference: Name and classify detected fields semantically
Intelligent Filling: Match your instructions to the appropriate form fields
PDF Generation: Create a new PDF with the filled values

For Office files (DOCX, XLSX, PPTX):

Structure Extraction: Parse the document’s XML structure to identify all text elements
Element Detection: LLM identifies fillable placeholders (empty cells, whitespace after labels, placeholder text)
Native Editing: Apply edits directly to the XML, preserving all original formatting and styles
Document Generation: Return the filled document in its original format

Unlike manual form filling or template-based approaches, edit provides:

Multi-Format Support: PDF, Word, Excel, and PowerPoint files
Zero Configuration: No need to pre-define field positions or create templates
Natural Language Instructions: Describe what to fill in plain English or JSON
Format Preservation: Office files retain all original formatting, styles, and layout
Automatic Field Matching: LLM intelligently maps your data to form fields
MIMEData Output: Get the filled document as MIMEData with filename and base64 content

Edit API

The Edit API provides two main approaches:

Agent Fill (edit.agent.fill): AI-powered document filling that automatically detects and fills form fields
Template Fill (edit.templates.fill): Optimized filling using pre-defined templates (PDF only)

Agent Fill

The main endpoint for filling documents with AI. Supports all document formats.

EditRequest

Show properties

instructions

string

required

Natural language or JSON instructions describing how to fill the document. Include the field values you want to populate, e.g., “Name: John Doe, Date: 2025-01-15” or {"name": "John Doe", "date": "2025-01-15"}.

document

MIMEData

required

The document to edit. Supports PDF, DOCX, XLSX, and PPTX files. Can be a file path, URL, or MIMEData object containing:

filename: Name of the file (e.g., “form.pdf”, “template.docx”, “data.xlsx”)
url: Data URI with base64 content (e.g., “data:application/pdf;base64,…”)

model

LLMModel

default:"retab-small"

The AI model to use for element detection and filling. Recommended: retab-small for accuracy.

color

string

default:"#000080"

Hex color code for filled text (e.g., “#FF0000” for red). Defaults to dark blue. Only applies to PDF form filling.

Returns

EditResponse Object

An EditResponse object containing the filled document and form data.

Show properties

form_data

list[FormField]

List of form fields with filled values (primarily for PDF). Each field includes bbox, description, type, key, and value.

filled_document

MIMEData

The filled document as MIMEData containing filename and url (data URI with base64 content). Returns the same format as the input (PDF → PDF, DOCX → DOCX, etc.).

Generate Template (Infer Form Schema)

Automatically detect form fields in a PDF document using computer vision and LLM. This is useful for creating templates that can be reused for batch form filling.

InferFormSchemaRequest

Show properties

document

MIMEData

required

The PDF document to analyze. Only PDF format is supported for form schema inference.

model

LLMModel

default:"retab-small"

The AI model to use for field naming and classification.

Returns

InferFormSchemaResponse Object

Show properties

form_schema

FormSchema

The detected form schema containing a list of form fields with keys, descriptions, types, and bounding boxes.

annotated_pdf

MIMEData

PDF with bounding boxes drawn around detected fields for visual verification.

field_count

int

Number of fields detected in the document.

Use Case: PDF Form Filling

Fill PDF forms programmatically using natural language instructions.

from retab import Retab
import base64

client = Retab()

# Fill the form with natural language instructions
# The SDK accepts file paths directly
result = client.edit.agent.fill(
    document="application-form.pdf",
    instructions="""
    Full Name: Jane Smith
    Date of Birth: March 15, 1985
    Email: [email protected]
    Phone: (555) 123-4567
    Address: 456 Oak Avenue, Suite 200
    City: San Francisco
    State: California
    ZIP Code: 94102
    I agree to the terms and conditions: checked
    """,
    model="retab-small",
    color="#000080",  # Dark blue text (default)
)

# Save the filled PDF
if result.filled_document:
    # Extract base64 content from data URI
    base64_content = result.filled_document.url.split(",")[1]
    filled_bytes = base64.b64decode(base64_content)
    with open("filled-application.pdf", "wb") as f:
        f.write(filled_bytes)
    print("Filled form saved!")

# Review what was filled
print(f"Filled {len(result.form_data)} form fields:")
for field in result.form_data:
    if field.value:
        print(f"  - {field.key}: {field.value}")

Use Case: Generate Form Schema

Automatically detect and classify form fields in a PDF document. This creates a form schema that can be used to create templates for batch processing.

from retab import Retab
import base64

client = Retab()

# Generate form schema from a PDF
response = client.edit.templates.generate(
    document="blank-form.pdf",
    model="retab-small"
)

print(f"Detected {response.field_count} form fields:")
for field in response.form_schema.form_fields:
    print(f"  - {field.key}: {field.description} ({field.type})")
    print(f"    Position: page {field.bbox.page}, ({field.bbox.x}, {field.bbox.y})")

# Save the annotated PDF for visual verification
if response.annotated_pdf:
    base64_content = response.annotated_pdf.url.split(",")[1]
    with open("annotated-form.pdf", "wb") as f:
        f.write(base64.b64decode(base64_content))
    print("Annotated PDF saved for review!")

Use Case: Template-Based Form Filling

Use pre-defined templates for consistent form filling without re-detecting fields each time. This is optimized for batch processing scenarios.

from retab import Retab
import base64

client = Retab()

# Use the template fill endpoint for fast, consistent filling
result = client.edit.templates.fill(
    template_id="edittplt_abc123",
    instructions="""
    Full Name: Jane Smith
    Date of Birth: March 15, 1985
    Email: [email protected]
    """,
    model="retab-small",
    color="#000080",  # Dark blue text (default)
)

# Save the filled PDF
if result.filled_document:
    base64_content = result.filled_document.url.split(",")[1]
    with open("filled-from-template.pdf", "wb") as f:
        f.write(base64.b64decode(base64_content))
    print("Template-based form filled and saved!")

When to use templates vs agent fill:

Use edit.templates.fill() for batch processing the same PDF form with different data
Use edit.agent.fill() for one-off document filling or when you don’t have a pre-defined template

Templates skip the field detection step, making them faster and more consistent for repeated use.

Use Case: Managing Templates

Create, list, and manage your edit templates programmatically.

from retab import Retab
import base64

client = Retab()

# First, generate the form schema
schema_response = client.edit.templates.generate(
    document="blank-form.pdf",
    model="retab-small"
)

# Create a template from the detected schema
template = client.edit.templates.create(
    name="Employee Onboarding Form",
    document="blank-form.pdf",
    form_fields=schema_response.form_schema.form_fields
)
print(f"Created template: {template.id}")

# List all templates
templates = client.edit.templates.list(limit=10)
for t in templates.data:
    print(f"  - {t.name} ({t.id})")

# Get a specific template
template = client.edit.templates.get(template_id="tmpl_abc123")

# Update a template
updated = client.edit.templates.update(
    template_id="tmpl_abc123",
    name="Updated Form Name"
)

# Duplicate a template
duplicate = client.edit.templates.duplicate(
    template_id="tmpl_abc123",
    name="Employee Form - Copy"
)

# Delete a template
client.edit.templates.delete(template_id="tmpl_abc123")

Use Case: Batch Form Processing

Process multiple forms with different data programmatically. For best performance with repeated forms, use templates.

import base64
from retab import Retab

client = Retab()

# Sample data for multiple applicants
applicants = [
    {
        "name": "John Doe",
        "dob": "January 10, 1990",
        "email": "[email protected]",
        "phone": "(555) 111-2222"
    },
    {
        "name": "Alice Johnson", 
        "dob": "July 22, 1988",
        "email": "[email protected]",
        "phone": "(555) 333-4444"
    },
    {
        "name": "Bob Williams",
        "dob": "December 5, 1995",
        "email": "[email protected]", 
        "phone": "(555) 555-6666"
    }
]

# For batch processing, use templates.fill() with a pre-created template
# This skips field detection for each document, making it much faster
for i, applicant in enumerate(applicants):
    instructions = f"""
    Full Name: {applicant['name']}
    Date of Birth: {applicant['dob']}
    Email Address: {applicant['email']}
    Phone Number: {applicant['phone']}
    """
    
    result = client.edit.templates.fill(
        template_id="edittplt_your_template_id",
        instructions=instructions,
        model="retab-small"
    )
    
    if result.filled_document:
        output_filename = f"filled-form-{i+1}-{applicant['name'].replace(' ', '-')}.pdf"
        base64_content = result.filled_document.url.split(",")[1]
        with open(output_filename, "wb") as f:
            f.write(base64.b64decode(base64_content))
        print(f"Created: {output_filename}")

print(f"Processed {len(applicants)} forms successfully!")

Use Case: Word Document Filling

Fill Word documents (DOCX) while preserving all original formatting and styles.

from retab import Retab
import base64

client = Retab()

# Fill a Word document with JSON data
result = client.edit.agent.fill(
    document="contract-template.docx",
    instructions="""
    {
        "client_name": "Acme Corporation",
        "contract_date": "January 15, 2025",
        "project_description": "Website redesign and development",
        "total_amount": "$25,000",
        "payment_terms": "Net 30"
    }
    """,
    model="retab-small",
)

# Save the filled DOCX (preserves original formatting)
if result.filled_document:
    base64_content = result.filled_document.url.split(",")[1]
    filled_bytes = base64.b64decode(base64_content)
    with open("filled-contract.docx", "wb") as f:
        f.write(filled_bytes)
    print("Filled Word document saved!")

Use Case: Excel Spreadsheet Filling

Fill Excel spreadsheets by targeting specific cells with data.

from retab import Retab
import base64

client = Retab()

# Fill an Excel spreadsheet
result = client.edit.agent.fill(
    document="invoice-template.xlsx",
    instructions="""
    {
        "invoice_number": "INV-2025-001",
        "customer_name": "Tech Solutions Inc.",
        "invoice_date": "2025-01-15",
        "items": [
            {"description": "Consulting Services", "quantity": 10, "rate": 150},
            {"description": "Software License", "quantity": 1, "rate": 500}
        ],
        "total": "$2,000"
    }
    """,
    model="retab-small",
)

if result.filled_document:
    base64_content = result.filled_document.url.split(",")[1]
    with open("filled-invoice.xlsx", "wb") as f:
        f.write(base64.b64decode(base64_content))
    print("Filled Excel spreadsheet saved!")

Use Case: PowerPoint Presentation Filling

Fill PowerPoint presentations with dynamic content.

from retab import Retab
import base64

client = Retab()

# Fill a PowerPoint presentation
result = client.edit.agent.fill(
    document="sales-deck-template.pptx",
    instructions="""
    {
        "company_name": "Acme Corp",
        "presenter_name": "Jane Smith",
        "presentation_date": "Q1 2025",
        "revenue_figure": "$1.2M",
        "growth_percentage": "25%",
        "key_highlights": ["Expanded to 3 new markets", "Launched 2 new products", "Increased team by 40%"]
    }
    """,
    model="retab-small",
)

if result.filled_document:
    base64_content = result.filled_document.url.split(",")[1]
    with open("filled-sales-deck.pptx", "wb") as f:
        f.write(base64.b64decode(base64_content))
    print("Filled PowerPoint presentation saved!")

Best Practices

Model Selection

retab-large: Most accurate for complex documents with many fields or ambiguous layouts. Recommended for production use.
retab-small: Faster and more cost-effective, suitable for simple documents with clear field labels.

Format-Specific Tips

PDF Forms:

Works best with forms that have clear field labels
Supports both text fields and checkboxes
For checkboxes, use “checked” or “unchecked” as the value
Use edit.templates.generate() to preview detected fields before filling
Use the color parameter to customize the filled text color (e.g., color="#FF0000" for red)

Word Documents (DOCX):

Best for documents with placeholders like [Enter name] or blank spaces after labels
All formatting (fonts, styles, colors) is preserved
Tables are fully supported

Excel Spreadsheets (XLSX):

Ideal for templates with empty cells next to labels
Supports multiple sheets
Cell references use standard Excel notation (Sheet1!A1)

PowerPoint Presentations (PPTX):

Works with text placeholders in shapes
Tables within slides are supported
Preserves all slide formatting and layouts

Writing Effective Filling Instructions

Use JSON for structured data: {"name": "John", "date": "2025-01-15"} works great
Be explicit: Use field labels that match or closely resemble those in the document
Use key-value pairs: Format as “Field Name: Value” for best matching
Include context: If a document has multiple similar fields, add context like “Section A - Name: John”

Working with MIMEData

The filled_document response is a MIMEData object with filename and url properties
The url is a data URI with format-appropriate MIME type
Extract base64 content by splitting on comma: url.split(",")[1]
Python SDK accepts file paths directly and handles MIMEData conversion automatically
Output format matches input format (DOCX in → DOCX out, XLSX in → XLSX out)

Template Workflow

Generate: Use edit.templates.generate() to detect form fields in a blank PDF
Review: Check the annotated PDF to verify detected fields
Create: Save the form schema as a template with edit.templates.create()
Fill: Use edit.templates.fill() for fast batch processing with pre-defined templates

Overview

Core Concepts

Consensus

Introduction

Supported Formats

How It Works

Edit API

Agent Fill

Generate Template (Infer Form Schema)

Use Case: PDF Form Filling

Use Case: Generate Form Schema

Use Case: Template-Based Form Filling

Use Case: Managing Templates

Use Case: Batch Form Processing

Use Case: Word Document Filling

Use Case: Excel Spreadsheet Filling

Use Case: PowerPoint Presentation Filling

Best Practices

Model Selection

Format-Specific Tips

Writing Effective Filling Instructions

Working with MIMEData

Template Workflow

Overview

Core Concepts

Consensus

​Introduction

​Supported Formats

​How It Works

​Edit API

​Agent Fill

​Generate Template (Infer Form Schema)

​Use Case: PDF Form Filling

​Use Case: Generate Form Schema

​Use Case: Template-Based Form Filling

​Use Case: Managing Templates

​Use Case: Batch Form Processing

​Use Case: Word Document Filling

​Use Case: Excel Spreadsheet Filling

​Use Case: PowerPoint Presentation Filling

​Best Practices

​Model Selection

​Format-Specific Tips

​Writing Effective Filling Instructions

​Working with MIMEData

​Template Workflow

Introduction

Supported Formats

How It Works

Edit API

Agent Fill

Generate Template (Infer Form Schema)

Use Case: PDF Form Filling

Use Case: Generate Form Schema

Use Case: Template-Based Form Filling

Use Case: Managing Templates

Use Case: Batch Form Processing

Use Case: Word Document Filling

Use Case: Excel Spreadsheet Filling

Use Case: PowerPoint Presentation Filling

Best Practices

Model Selection

Format-Specific Tips

Writing Effective Filling Instructions

Working with MIMEData

Template Workflow