Overview

Editing fills PDF form fields programmatically and returns a completed document. You give it a PDF and either natural-language instructions or a schema describing the fields and values, and Extend detects the form’s fields, fills them, and returns a downloadable PDF along with the values it wrote. Use it to auto-fill applications, pre-populate documents with customer data, and generate filled forms at scale.

Quick start

We’ll fill a blank IRS Form 1040 from natural-language instructions. For this quick-start we’ve uploaded the file here.

Grab a key from the Developers page and store it as the EXTEND_API_KEY environment variable. If you’re using an SDK, see the installation instructions.

$
export EXTEND_API_KEY="your_api_key_here"

The /edit endpoint takes a file and a config with instructions (or a schema).

1
import os
2
from extend_ai import Extend
3
4
client = Extend(token=os.environ["EXTEND_API_KEY"])
5
6
result = client.edit(
7
    file={
8
        "url": "https://extend-public-files.s3.us-east-2.amazonaws.com/f1040.pdf",
9
    },
10
    config={
11
        "instructions": (
12
            "Fill the taxpayer's first name as Jordan and last name as Avery. "
13
            "Set the Single filing status. Leave all other fields blank."
14
        ),
15
        "advancedOptions": {"flattenPdf": True},
16
    },
17
)
18
19
print(result)

1
with open("f1040.pdf", "rb") as f:
2
    uploaded = client.files.upload(file=f)
3
4
result = client.edit(file={"id": uploaded.id}, config=config)

Example response

After you run the code snippet above, you’ll see a response like this. Extend detects the form’s fields, fills the ones your instructions describe, and returns an output with the completed PDF in editedFile and the written values in filledValues.

1
{
2
  "object": "edit_run",
3
  "id": "edr_xK9mLPqRtN3vS8wF5hB2cQ",
4
  "status": "PROCESSED",
5
  "output": {
6
    "editedFile": {
7
      "id": "file_Ab3cDE45Fg6hIj7KlM8nO",
8
      "presignedUrl": "https://extend-files.s3.amazonaws.com/..."
9
    },
10
    "filledValues": {
11
      "Your first name and middle initial": "Jordan",
12
      "Last name": "Avery",
13
      "filing_status_single": true
14
    }
15
  },
16
  "metrics": { "processingTimeMs": 1234, "pageCount": 2, "fieldCount": 3 },
17
  "usage": { "credits": 1 }
18
}

Key fields

For full request/response details, see the Create Edit Run API reference.

Use the output

Read the download link off output.editedFile, and inspect output.filledValues to see what was written.

1
edited = result.output.edited_file
2
print("Download:", edited.presigned_url)  # expires after 15 minutes
3
4
for field, value in (result.output.filled_values or {}).items():
5
    print(f"{field}: {value}")

For the full response shape and status values, see Response Format.

Sync vs async

The example above calls the synchronous /edit endpoint. We also have an asynchronous /edit_runs endpoint that should be used for large files and high volume use cases.

See Async Processing for the full comparison, polling options, and webhook setup.

Configuration

The quick start sends file and config.instructions. To control how the form is filled, pass more options inside config. Here are the most commonly used ones; for the full reference, see Configuration.

Instructions

Natural-language guidance describing the values to fill and any special handling. The fastest way to start — Extend detects the form’s fields and fills the ones you describe.

1
{ "config": { "instructions": "Fill the applicant's name and today's date. Leave optional fields blank." } }

Schema

A JSON Schema that pins each field’s PDF type, value, and position using extend_edit:* keywords. Use it for exact, repeatable control over what gets filled and where.

1
{
2
  "config": {
3
    "schema": {
4
      "type": "object",
5
      "properties": {
6
        "applicant_name": {
7
          "type": ["string", "null"],
8
          "extend_edit:field_type": "text",
9
          "extend_edit:value": "Jane Smith"
10
        }
11
      }
12
    }
13
  }
14
}

Full schema reference →

Flatten the PDF

Flatten the document after editing so the filled fields become non-editable. Use it when generating final documents.

1
{ "config": { "advancedOptions": { "flattenPdf": true } } }

Tutorial video

Next steps