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

SDK Surface

The edit SDK exposes the same workflow in both clients:

client.edits.create(...) for direct document filling (pass document=...) or template-based filling (pass template_id=...)
client.edits.templates.create(...) to register a reusable PDF form template
client.edits.templates.fill(...) to fill a saved template with new instructions

In both SDKs, color is a top-level argument on edits.create(...) and edits.templates.fill(...).

Edit API

The Edit API provides two main approaches:

Direct Fill (edits.create with document=...): AI-powered document filling that automatically detects and fills form fields
Template Fill (edits.templates.fill): Optimized filling using pre-defined templates (PDF only)

Direct 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

Edit Object

An Edit resource with the filled document and form data.

Show properties

string

Unique identifier of the edit record.

data

EditResult

Contains form_data (the filled FormField list, each with bbox, description, type, key, and value) and filled_document (the rendered PDF/DOCX/XLSX/PPTX as MIMEData).

usage

RetabUsage

Usage information for the edit operation.

Create Template (Pre-Register A Form)

Register a reusable PDF form template with its empty PDF and a list of form fields. You typically detect those fields in the dashboard first, or reuse a form schema you already own, and then persist the template for fast batch filling.

EditTemplateRequest

Show properties

name

string

required

Human-readable name for the template.

document

MIMEData

required

The empty PDF to use as the template background. Only PDF format is supported.

form_fields

array[FormField]

required

Ordered list of form fields (each with bbox, description, type, key).

Returns

EditTemplate Object

Show properties

string

Unique template identifier, used later by edits.templates.fill(template_id=...).

form_fields

list[FormField]

The form fields attached to the template.

field_count

int

Number of form fields in the template.

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.edits.create(
    document="application-form.pdf",
    instructions="""
    Full Name: Jane Smith
    Date of Birth: March 15, 1985
    Email: jane.smith@example.com
    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.data.filled_document:
    # Extract base64 content from data URI
    base64_content = result.data.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.data.form_data)} form fields:")
for field in result.data.form_data:
    if field.value:
        print(f"  - {field.key}: {field.value}")

Use Case: Create a Template

Persist an empty PDF together with its list of form fields as a reusable template. Templates are the recommended way to fill the same form repeatedly — they skip field detection on every fill and guarantee consistent field mapping.

from retab import Retab

client = Retab()

# Register a reusable template (document + form_fields)
template = client.edits.templates.create(
    name="Application Form",
    document="blank-form.pdf",
    form_fields=[
        {
            "key": "full_name",
            "description": "Applicant's full legal name",
            "type": "text",
            "bbox": {"left": 0.15, "top": 0.12, "width": 0.35, "height": 0.03, "page": 1},
        },
        {
            "key": "date_of_birth",
            "description": "Date of birth, ISO 8601",
            "type": "text",
            "bbox": {"left": 0.15, "top": 0.18, "width": 0.25, "height": 0.03, "page": 1},
        },
    ],
)

print(f"Template {template.id} with {template.field_count} fields ready for fill calls")

You can discover field bounding boxes visually in the Retab dashboard editor, then pass the resulting form_fields list into edits.templates.create(...) to persist it.

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.edits.templates.fill(
    template_id="edittplt_abc123",
    instructions="""
    Full Name: Jane Smith
    Date of Birth: March 15, 1985
    Email: jane.smith@example.com
    """,
    model="retab-small",
    color="#000080",  # Dark blue text (default)
)

# Save the filled PDF
if result.data.filled_document:
    base64_content = result.data.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 direct fill:

Use edits.templates.fill() for batch processing the same PDF form with different data
Use edits.create() with document=... 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: 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": "john.doe@example.com",
        "phone": "(555) 111-2222"
    },
    {
        "name": "Alice Johnson", 
        "dob": "July 22, 1988",
        "email": "alice.j@example.com",
        "phone": "(555) 333-4444"
    },
    {
        "name": "Bob Williams",
        "dob": "December 5, 1995",
        "email": "bob.w@example.com", 
        "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.edits.templates.fill(
        template_id="edittplt_your_template_id",
        instructions=instructions,
        model="retab-small"
    )
    
    if result.data.filled_document:
        output_filename = f"filled-form-{i+1}-{applicant['name'].replace(' ', '-')}.pdf"
        base64_content = result.data.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.edits.create(
    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.data.filled_document:
    base64_content = result.data.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.edits.create(
    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.data.filled_document:
    base64_content = result.data.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.edits.create(
    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.data.filled_document:
    base64_content = result.data.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 edits.templates.create() to register a reusable template with known form fields
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

Register: Use edits.templates.create() with a blank PDF and the list of form fields (bounding boxes + descriptions)
Review: Inspect template.form_fields to verify coverage
Fill: Use edits.templates.fill() for fast batch processing against the saved template

Overview

Primitives

Workflows

Core Concepts

Introduction

Supported Formats

How It Works

SDK Surface

Edit API

Direct Fill

Create Template (Pre-Register A Form)

Use Case: PDF Form Filling

Use Case: Create a Template

Use Case: Template-Based Form Filling

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

Primitives

Workflows

Core Concepts

​Introduction

​Supported Formats

​How It Works

​SDK Surface

​Edit API

​Direct Fill

​Create Template (Pre-Register A Form)

​Use Case: PDF Form Filling

​Use Case: Create a Template

​Use Case: Template-Based Form Filling

​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

SDK Surface

Edit API

Direct Fill

Create Template (Pre-Register A Form)

Use Case: PDF Form Filling

Use Case: Create a Template

Use Case: Template-Based Form Filling

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