Edit File (Sync) | Extend Documentation

{
  "object": "edit_run",
  "id": "edr_xK9mLPqRtN3vS8wF5hB2cQ",
  "file": {
    "object": "file",
    "id": "file_xK9mLPqRtN3vS8wF5hB2cQ",
    "name": "Invoices.pdf",
    "type": "PDF",
    "parentFileId": "file_Zk9mNP12Qw4yTv8BdR3H",
    "metadata": {
      "pageCount": 30,
      "parentSplit": {
        "id": "string",
        "type": "Invoice",
        "identifier": "other_2_9",
        "startPage": 1,
        "endPage": 10
      }
    },
    "createdAt": "2024-03-21T16:45:00Z",
    "updatedAt": "2024-03-21T16:45:00Z"
  },
  "status": "PROCESSING",
  "failureReason": "FILE_TYPE_NOT_SUPPORTED",
  "failureMessage": "File type not supported. Edit runs currently require a PDF.",
  "config": {
    "engineVersion": "1.0.0",
    "schema": {
      "type": "object",
      "properties": {},
      "required": [
        "string"
      ],
      "additionalProperties": true,
      "dependentRequired": {},
      "if": {
        "properties": {},
        "required": [
          "string"
        ],
        "dependentRequired": {},
        "allOf": [
          null
        ],
        "oneOf": [
          null
        ],
        "anyOf": [
          null
        ]
      },
      "then": {
        "properties": {},
        "required": [
          "string"
        ],
        "dependentRequired": {},
        "allOf": [
          null
        ],
        "oneOf": [
          null
        ],
        "anyOf": [
          null
        ]
      },
      "else": {
        "properties": {},
        "required": [
          "string"
        ],
        "dependentRequired": {},
        "allOf": [
          null
        ],
        "oneOf": [
          null
        ],
        "anyOf": [
          null
        ]
      },
      "allOf": [
        {
          "properties": {},
          "required": [
            "string"
          ],
          "dependentRequired": {},
          "allOf": [
            null
          ],
          "oneOf": [
            null
          ],
          "anyOf": [
            null
          ]
        }
      ],
      "oneOf": [
        {
          "properties": {},
          "required": [
            "string"
          ],
          "dependentRequired": {},
          "allOf": [
            null
          ],
          "oneOf": [
            null
          ],
          "anyOf": [
            null
          ]
        }
      ],
      "anyOf": [
        {
          "properties": {},
          "required": [
            "string"
          ],
          "dependentRequired": {},
          "allOf": [
            null
          ],
          "oneOf": [
            null
          ],
          "anyOf": [
            null
          ]
        }
      ],
      "not": {
        "properties": {},
        "required": [
          "string"
        ],
        "dependentRequired": {},
        "allOf": [
          null
        ],
        "oneOf": [
          null
        ],
        "anyOf": [
          null
        ]
      }
    },
    "instructions": "string",
    "schemaGenerationInstructions": "string",
    "advancedOptions": {
      "tableParsingEnabled": true,
      "flattenPdf": true,
      "radioEnumsEnabled": true,
      "nativeFieldsOnly": true,
      "conditionalGenerationEnabled": true
    }
  },
  "output": {
    "editedFile": {
      "id": "file_Ab3cDE45Fg6hIj7KlM8nO",
      "presignedUrl": "https://extend-files.s3.amazonaws.com/..."
    },
    "filledValues": {}
  },
  "metrics": {
    "processingTimeMs": 1234,
    "pageCount": 5,
    "fieldCount": 10,
    "fieldsDetectedCount": 8,
    "fieldsAnnotatedCount": 10,
    "fieldDetectionTimeMs": 500,
    "fieldAnnotationTimeMs": 200,
    "fieldFillingTimeMs": 300
  },
  "usage": {
    "credits": 9,
    "totalCredits": 15,
    "breakdown": [
      {
        "object": "parse_run",
        "id": "pr_3UZSj69pYZDKHFuuX57ic",
        "credits": 6,
        "charges": [
          {
            "product": "extraction_performance",
            "unit": "page",
            "quantity": 10,
            "credits": 30
          },
          {
            "product": "review_agent",
            "unit": "page",
            "quantity": 10,
            "credits": 10
          },
          {
            "product": "agentic_text_correction",
            "unit": "page",
            "quantity": 3,
            "credits": 3,
            "pages": [
              2,
              4,
              7
            ]
          }
        ]
      }
    ]
  }
}

Edit a file synchronously, waiting for the result before returning. This endpoint has a 5-minute timeout — if processing takes longer, the request will fail.

Note: This endpoint is intended for onboarding and testing only. For production workloads, use POST /edit_runs with polling or webhooks instead, as it provides better reliability for large files and avoids timeout issues.

The Edit endpoint allows you to detect and fill form fields in PDF documents.

Pass file to edit a document directly, or templateId to run against a saved edit template. Exactly one of file or templateId must be provided.

For more details, see the Edit File guide. See Editing Error Handling for HTTP errors and run failure reasons.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Request

This endpoint expects an object.

fileobjectOptional

The file to be edited. Mutually exclusive with templateId — provide one or the other.

Files can be provided as a URL or an Extend file ID.

templateIdstringOptional

The ID of a saved edit template to run against. Mutually exclusive with file — provide one or the other.

The template’s saved file is used as the input file, and its saved config (schema, instructions, engine version, and advanced options) is used to fill in any values not set on the request’s own config. Values set on the request’s config always take precedence over the template’s.

Example: "edt_xK9mLPqRtN3vS8wF5hB2cQ"

configobjectOptional

Configuration options for the editing process.

Response

Successfully edited file

objectenum

The type of object. Will always be "edit_run".

Allowed values:

idstring

A unique identifier for the edit run.

Example: "edr_xK9mLPqRtN3vS8wF5hB2cQ"

fileobject

The input file that was submitted for editing.

statusenum

The status of the edit run:

"PROCESSING" - The file is still being processed
"PROCESSED" - The file was successfully edited
"FAILED" - The editing failed (see failureReason for details)

Allowed values:

failureReasonstring or null

The reason for failure.

Availability: Present when status is "FAILED".

Possible values include:

UNABLE_TO_DOWNLOAD_FILE - Failed to load the requested file
FILE_TYPE_NOT_SUPPORTED - File type not supported. Edit runs currently require a PDF
FILE_SIZE_TOO_LARGE - The file exceeds the maximum allowed size
CORRUPT_FILE - The file appears to be corrupted and cannot be edited
FIELD_DETECTION_ERROR - An error occurred during field detection
PASSWORD_PROTECTED_FILE - The file is password protected and cannot be edited
FAILED_TO_CONVERT_TO_PDF - The file could not be converted to PDF for processing
INTERNAL_ERROR - An unexpected internal error occurred
INVALID_OPTIONS - The provided configuration options are invalid
EMPTY_SCHEMA - No schema was provided and no fields could be detected
OUT_OF_CREDITS - Insufficient credits to process the file
SCHEMA_VALIDATION_ERROR - The generated output value failed validation against the edit schema

Note: Additional failure reasons may be added in the future. Your integration should handle unknown values gracefully.

failureMessagestring or null

A human-readable description of the failure.

Availability: Present when status is "FAILED".

configobject

The configuration used for this edit run, including any default values that were applied.

outputobject or null

The output of the edit run.

Availability: Present when status is "PROCESSED".

metricsobject or null

Metrics about the editing process.

Availability: Present when status is "PROCESSED".

usageobject or null

Usage credits consumed by this edit run.

Availability: Present when status is "PROCESSED", the run was created after October 7, 2025, and the customer is on the current billing system.

Errors

400

Bad Request Error

401

Unauthorized Error

402

Payment Required Error

403

Forbidden Error

404

Not Found Error

422

Unprocessable Entity Error

429

Too Many Requests Error

500

Internal Server Error

Authentication

Headers

Request

Response

Errors