> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reducto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Edit

> Fill PDF forms and modify DOCX documents using the Python SDK

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

```python theme={null}
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

```python theme={null}
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

| Parameter           | Type           | Required | Description                                                   |
| ------------------- | -------------- | -------- | ------------------------------------------------------------- |
| `document_url`      | `str`          | Yes      | File ID (`reducto://...`) or URL of the document to edit      |
| `edit_instructions` | `str`          | Yes      | Natural language instructions describing how to fill the form |
| `edit_options`      | `dict \| None` | No       | Edit options (color, overflow pages)                          |
| `form_schema`       | `list \| None` | No       | Explicit form schema for structured filling                   |
| `priority`          | `bool \| None` | No       | Request priority processing                                   |

***

## Edit Instructions

Provide natural language instructions describing what to fill:

```python theme={null}
result = client.edit.run(
    document_url=upload.file_id,
    edit_instructions="""
    Fill in the following fields:
    - Full Name: John Doe
    - Email: john@example.com
    - Date: December 25, 2024
    - Check the 'I agree' checkbox
    """
)
```

***

## Form Schema

For more control, provide an explicit form schema:

```python theme={null}
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": "john@example.com"},
        {"field_name": "date", "value": "12/25/2024"},
        {"field_name": "agree_checkbox", "value": True}
    ]
)
```

***

## Edit Options

Customize edit behavior:

```python theme={null}
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

```python theme={null}
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

```python theme={null}
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

```python theme={null}
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: jane@example.com  
    - 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

<CardGroup cols={2}>
  <Card title="Clear Instructions" icon="pen">
    Write clear, specific instructions about which fields to fill and with what values.
  </Card>

  <Card title="Use Form Schema" icon="list">
    For precise control, use `form_schema` to specify exact field mappings.
  </Card>
</CardGroup>

***

## Next Steps

* Learn about [form schema design](/configs/edit/form-schema)
* Explore the [async client](/sdk/python/async) for concurrent processing
* Check out the [edit overview](/editing/edit-overview) for more details