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

# Edit

> Fill forms and modify documents programmatically using natural language instructions.

## Overview

The Edit endpoint fills forms and modifies documents based on natural language instructions. Provide a document and describe what to change — Aifano handles field detection, text placement, and formatting automatically.

**Credits:** 4 credits per page

## Basic Usage

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://platform.aifano.com/edit" \
    -H "Authorization: Bearer $AIFANO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "document_url": "aifano://tax-form.pdf",
      "edit_instructions": "Fill this form with:\n- Full Name: John David Smith\n- Date of Birth: March 15, 1985\n- SSN: 123-45-6789\n- Check \"Yes\" for US Citizen\n- Select \"California\" for state"
    }'
  ```

  ```python Python theme={null}
  import requests

  result = requests.post(
      "https://platform.aifano.com/edit",
      headers={"Authorization": f"Bearer {AIFANO_API_KEY}"},
      json={
          "document_url": "aifano://tax-form.pdf",
          "edit_instructions": (
              "Fill this form with:\n"
              "- Full Name: John David Smith\n"
              "- Date of Birth: March 15, 1985\n"
              "- SSN: 123-45-6789"
          )
      }
  ).json()

  print(f"Edited document: {result['document_url']}")
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://platform.aifano.com/edit", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${AIFANO_API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      document_url: "aifano://tax-form.pdf",
      edit_instructions: "Fill name: John Smith, date: 2024-01-15"
    })
  });

  const result = await response.json();
  console.log(`Download: ${result.document_url}`);
  ```
</CodeGroup>

## Response

```json theme={null}
{
  "document_url": "https://platform.aifano.com/download/edited-form.pdf?token=...",
  "form_schema": [
    {
      "bbox": { "left": 0.1, "top": 0.2, "width": 0.4, "height": 0.03, "page": 1 },
      "description": "Name field in header section",
      "type": "text"
    }
  ],
  "usage": { "num_pages": 2, "credits": 8 }
}
```

The `document_url` is a presigned download link valid for 24 hours. The `form_schema` describes detected fields and can be reused for the same form type.

## Edit Options

Customize the editing behavior:

```json theme={null}
{
  "document_url": "aifano://document.pdf",
  "edit_instructions": "...",
  "edit_options": {
    "color": "#FF0000",
    "enable_overflow_pages": false
  }
}
```

| Option                  | Type      | Default   | Description                                                        |
| ----------------------- | --------- | --------- | ------------------------------------------------------------------ |
| `color`                 | `string`  | `#FF0000` | Highlight color for edits in hex format (DOCX only)                |
| `enable_overflow_pages` | `boolean` | `false`   | Create appendix pages for text exceeding field capacity (PDF only) |

## Form Schema

For repeatable form filling, provide a `form_schema` with predefined field locations. This improves speed and consistency when processing the same form type multiple times:

```json theme={null}
{
  "document_url": "aifano://application-form.pdf",
  "edit_instructions": "Fill with: Name: Jane Doe, DOB: 1990-05-20",
  "form_schema": [
    {
      "bbox": { "left": 0.1, "top": 0.2, "width": 0.4, "height": 0.03, "page": 1 },
      "description": "Full name field",
      "type": "text"
    },
    {
      "bbox": { "left": 0.1, "top": 0.25, "width": 0.2, "height": 0.03, "page": 1 },
      "description": "Date of birth field",
      "type": "text"
    }
  ]
}
```

<Tip>
  The first time you edit a PDF form, the response includes a `form_schema` with detected fields. Save this schema and reuse it for subsequent edits of the same form type to improve accuracy and speed.
</Tip>

## Supported Formats

| Format | Edits | Notes                                           |
| ------ | ----- | ----------------------------------------------- |
| PDF    | ✅     | Full form filling, text overlay, overflow pages |
| DOCX   | ✅     | Text replacement with color highlighting        |

## Async Processing

For large documents, use the async variant:

```bash theme={null}
curl -X POST "https://platform.aifano.com/edit_async" \
  -H "Authorization: Bearer $AIFANO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "document_url": "aifano://large-form.pdf",
    "edit_instructions": "Fill all fields with provided data..."
  }'
```

See [Async Processing](/documentation/async-processing) for details on polling and webhooks.

## Common Use Cases

<CardGroup cols={2}>
  <Card title="Tax Forms" icon="file-invoice">
    Auto-fill W-2s, 1099s, and other tax documents with employee or contractor data.
  </Card>

  <Card title="Insurance Claims" icon="shield">
    Complete claim forms with policyholder information and incident details.
  </Card>

  <Card title="Government Applications" icon="landmark">
    Fill permit applications, license renewals, and regulatory filings.
  </Card>

  <Card title="HR Onboarding" icon="user-plus">
    Pre-fill employment contracts, NDAs, and benefits enrollment forms.
  </Card>
</CardGroup>