Skip to main content

​
Introduction

The edit method in Retab’s document processing pipeline enables intelligent PDF form filling. It automatically detects form fields in any PDF document using OCR and LLM inference, then fills them based on natural language instructions. This is ideal for automating form completion workflows, document generation, and batch processing of standardized forms. The edit workflow follows these steps:
  1. OCR Processing: Extract text elements with precise bounding box coordinates
  2. Form Field Detection: Use LLM to identify fillable fields (text inputs, checkboxes)
  3. Intelligent Filling: Match your instructions to the appropriate form fields
  4. PDF Generation: Create a new PDF with the filled values
Unlike manual form filling or template-based approaches, edit provides:
  • Zero Configuration: No need to pre-define field positions or create templates
  • Natural Language Instructions: Describe what to fill in plain English
  • Automatic Field Matching: LLM intelligently maps your data to form fields
  • MIMEData Output: Get the filled PDF as MIMEData with filename and base64 content
  • Checkbox Support: Handles both text fields and checkboxes

​
Edit API

​
EditRequest
EditRequest
​
Returns
EditResponse Object
An EditResponse object containing the filled PDF and form data.

​
Use Case: Automated 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.documents.edit(
    document="application-form.pdf",
    filling_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="gemini-2.5-pro",
)

# Save the filled PDF
if result.filled_pdf:
    # Extract base64 content from data URI
    base64_content = result.filled_pdf.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.description}: {field.value}")

​
Use Case: Batch Form Processing

Process multiple forms with different data programmatically. 
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"
    }
]

# Process each applicant using file path directly
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.documents.edit(
        document="template-form.pdf",
        filling_instructions=instructions,
        model="gemini-2.5-pro"
    )
    
    if result.filled_pdf:
        output_filename = f"filled-form-{i+1}-{applicant['name'].replace(' ', '-')}.pdf"
        base64_content = result.filled_pdf.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!")

​
Best Practices

​
Model Selection

  • gemini-2.5-pro: Most accurate for complex forms with many fields or ambiguous layouts. Recommended for production use.
  • gemini-2.5-flash: Faster and more cost-effective, suitable for simple forms with clear field labels.

​
Annotation Level Selection

  • line (default): Best for most standard forms where fields are organized in rows
  • block: Better for forms with dense text or multi-line field descriptions
  • token: Use when you need precise word-level detection for tightly packed forms

​
Writing Effective Filling Instructions

  • Be explicit: Use field labels that match or closely resemble those in the form
  • Use key-value pairs: Format as “Field Name: Value” for best matching
  • For checkboxes: Use “checked” or “unchecked” as the value
  • Include context: If a form has multiple similar fields, add context like “Section A - Name: John”

​
Working with MIMEData

  • The filled_pdf response is a MIMEData object with filename and url properties
  • The url is a data URI: data:application/pdf;base64,<base64_content>
  • Extract base64 content by splitting on comma: url.split(",")[1]
  • Python SDK accepts file paths directly and handles MIMEData conversion automatically