Skip to main content
The edit.run() method fills PDF forms and modifies DOCX documents programmatically. You provide instructions describing what to fill, and Edit populates the document.

​
Basic Usage

from pathlib import Path
from reducto import Reducto

client = Reducto()

# Upload a form
upload = client.upload(file=Path("application.pdf"))

# Fill the form
result = client.edit.run(
    document_url=upload.file_id,
    edit_instructions="Fill in the name field with 'John Doe' and the date with '12/25/2024'"
)

# Access the filled document
print(result.document_url)  # URL to download filled document

​
Method Signature

def edit.run(
    document_url: str,
    edit_instructions: str,
    edit_options: dict | None = None,
    form_schema: list | None = None,
    priority: bool | None = None
) -> EditResponse

​
Parameters

ParameterTypeRequiredDescription
document_urlstrYesFile ID (reducto://...) or URL of the document to edit
edit_instructionsstrYesNatural language instructions describing how to fill the form
edit_optionsdict | NoneNoEdit options (color, overflow pages)
form_schemalist | NoneNoExplicit form schema for structured filling
prioritybool | NoneNoRequest priority processing

​
Edit Instructions

Provide natural language instructions describing what to fill: 
result = client.edit.run(
    document_url=upload.file_id,
    edit_instructions="""
    Fill in the following fields:
    - Full Name: John Doe
    - Email: [email protected]
    - Date: December 25, 2024
    - Check the 'I agree' checkbox
    """
)

​
Form Schema

For more control, provide an explicit form schema: 
result = client.edit.run(
    document_url=upload.file_id,
    edit_instructions="Fill the form with the provided data",
    form_schema=[
        {"field_name": "full_name", "value": "John Doe"},
        {"field_name": "email", "value": "[email protected]"},
        {"field_name": "date", "value": "12/25/2024"},
        {"field_name": "agree_checkbox", "value": True}
    ]
)

​
Edit Options

Customize edit behavior: 
result = client.edit.run(
    document_url=upload.file_id,
    edit_instructions="Fill the form",
    edit_options={
        "color": "#0000FF",  # Text color (hex)
        "enable_overflow_pages": True  # Add pages if content overflows
    }
)

​
Response Structure

result: EditResponse = client.edit.run(...)

# Filled document URL
print(result.document_url)  # str: URL to download the filled document

# Form schema (if auto-detected)
print(result.form_schema)   # list: Detected form fields

​
Error Handling

from reducto import Reducto
import reducto

try:
    result = client.edit.run(
        document_url=upload.file_id,
        edit_instructions="Fill the name field"
    )
except reducto.APIConnectionError as e:
    print(f"Connection failed: {e}")
except reducto.APIStatusError as e:
    print(f"Edit failed: {e.status_code} - {e.response}")

​
Complete Example

from pathlib import Path
from reducto import Reducto
import requests

client = Reducto()

# Upload form
upload = client.upload(file=Path("job-application.pdf"))

# Fill form with instructions
result = client.edit.run(
    document_url=upload.file_id,
    edit_instructions="""
    Fill in the job application with:
    - Applicant Name: Jane Smith
    - Email: [email protected]  
    - Phone: 555-1234
    - Date: 12/25/2024
    - Check the signature checkbox
    """,
    edit_options={
        "color": "#000000"
    }
)

# Download filled form
response = requests.get(result.document_url)
with open("filled-application.pdf", "wb") as f:
    f.write(response.content)

print("Form filled and saved!")

​
Best Practices

Clear Instructions

Write clear, specific instructions about which fields to fill and with what values.

Use Form Schema

For precise control, use form_schema to specify exact field mappings.

​
Next Steps