> This page is for version v2026-02-09 (default).
> For other versions, use one of these documentation indexes:
> - v2026-02-09 (default): https://docs.extend.ai/2026-02-09/llms.txt
> - v2025-04-21: https://docs.extend.ai/2025-04-21/llms.txt
> - v2024-12-23: https://docs.extend.ai/2024-12-23/llms.txt

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.extend.ai/llms.txt
> Use this file to discover all available pages before exploring further.
>
> ## API version
> The current API version is `2026-02-09`, served at the site root (no version prefix in URLs).
> If this page URL contains `/2025-04-21/` or `/2024-12-23/`, you are reading an older API version.
> Prefer the current docs at https://docs.extend.ai/llms.txt unless the user explicitly needs that older version.
> Do not treat older-version pages as the source of truth for new integrations.

# Form Detection Run Failed

POST 

Triggered when a FormDetectionRun created directly through the Form Detection API fails.

Internal FormDetectionRuns created by EditRuns without a schema do not emit this webhook. Their failures are reported through the parent `edit_run.failed` event.


Reference: https://docs.extend.ai/api-reference/webhook-events/edit/form-detection-run-failed-webhook

## Request

### Payload

- `eventId` (string, required) — Unique identifier for the event
- `payload` (FormDetectionRun, required) — A run that detects fields in a PDF form and generates an edit schema.

## Types

### FormDetectionRun

A run that detects fields in a PDF form and generates an edit schema.

- `object` (enum, required) — The type of object. Will always be `"form_detection_run"`.
  - Allowed values: `form_detection_run`
- `id` (string, required) — A unique identifier for the form detection run. Example: `"sgr_xK9mLPqRtN3vS8wF5hB2cQ"`
- `file` (FileSummary, required) — The input PDF submitted for form detection.
- `status` (enum, required) — The status of the form detection run: * `"PROCESSING"` - The form is still being analyzed * `"PROCESSED"` - Form detection completed successfully * `"FAILED"` - Form detection failed (see `failureReason` for details)
  - Allowed values: `PROCESSING`, `PROCESSED`, `FAILED`
- `failureReason` (string, required, nullable) — The reason for failure. **Availability:** Present when `status` is `"FAILED"`. Possible values include: * `UNABLE_TO_DOWNLOAD_FILE` * `FILE_TYPE_NOT_SUPPORTED` * `FILE_SIZE_TOO_LARGE` * `CORRUPT_FILE` * `FIELD_DETECTION_ERROR` * `PASSWORD_PROTECTED_FILE` * `FAILED_TO_CONVERT_TO_PDF` * `EMPTY_SCHEMA` * `INTERNAL_ERROR` * `INVALID_OPTIONS` * `OUT_OF_CREDITS` **Note:** Additional failure reasons may be added in the future. Your integration should handle unknown values gracefully.
- `failureMessage` (string, required, nullable) — A human-readable description of the failure. **Availability:** Present when `status` is `"FAILED"`.
- `config` (EditSchemaGenerationConfig, required) — The configuration used for this form detection run, including any default values that were applied.
- `output` (EditSchemaGenerationResponse, required, nullable) — The detected schema and optional mapping metadata. **Availability:** Present when `status` is `"PROCESSED"`.
- `metrics` (FormDetectionRunMetrics, required, nullable) — Metrics about the form detection process. **Availability:** Present when `status` is `"PROCESSED"`.
- `usage` (RunUsage, required, nullable) — Usage credits consumed by this form detection run.

### FileSummary

- `object` (enum, required) — The type of object. Will always be `"file"`.
  - Allowed values: `file`
- `id` (string, required) — ID for the file. Example: `"file_xK9mLPqRtN3vS8wF5hB2cQ"`
- `name` (string, required) — The name of the file Example: `"Invoices.pdf"`
- `type` (enum, required, nullable) — The type of the file. **Availability:** Present when the file type could be determined.
  - Allowed values: `PDF`, `CSV`, `IMG`, `TXT`, `DOCX`, `EXCEL`, `XML`, `HTML`
- `parentFileId` (string, required, nullable) — ID of the parent file. **Availability:** Present for files created via a Splitter in a workflow.
- `metadata` (FileMetadata, required)
- `createdAt` (string, required) — The time (in UTC) at which the object was created. Will follow the RFC 3339 format. Example: `"2024-03-21T16:45:00Z"`
- `updatedAt` (string, required) — The time (in UTC) at which the object was last updated. Will follow the RFC 3339 format. Example: `"2024-03-21T16:45:00Z"`

### EditSchemaGenerationConfig

Configuration options for edit schema generation.

- `engineVersion` (string, optional, default: 1.0.0) — The Edit engine version to use for form detection. Use an exact version for reproducible results, or `latest` to use the latest stable version. Defaults to `1.0.0` when omitted. Responses contain the resolved exact version.
- `inputSchema` (EditRootJSON, optional) — Optional existing edit schema to map onto the detected form fields. When provided, the response may include a `mappingResult` that shows which input schema paths matched the generated form fields.
- `instructions` (string, optional) — Custom instructions provided for schema generation.
- `advancedOptions` (EditSchemaGenerationConfigAdvancedOptions, optional) — Advanced options for schema generation.

### EditSchemaGenerationResponse

The generated schema and optional mapping metadata.

- `schema` (EditRootJSON, required) — The final generated schema after mapping. If no input schema was provided this will be the same as the annotatedSchema.
- `annotatedSchema` (EditRootJSON, required, nullable) — The original schema that was detected and annotated from the file.
- `mappingResult` (EditSchemaGenerationMappingResult, required, nullable) — Mapping information between `inputSchema` paths and detected form fields when an input schema was provided.

### FormDetectionRunMetrics

Metrics about the form detection process. **Availability:** Present when `status` is `"PROCESSED"`.

- `processingTimeMs` (double, required) — Total processing time in milliseconds.
- `pageCount` (integer, required) — The number of pages in the document.
- `fieldCount` (integer, required) — The total number of fields in the generated schema.
- `fieldsDetectedCount` (integer, required) — The number of fields that were automatically detected.
- `fieldsAnnotatedCount` (integer, required) — The number of fields annotated with positions.
- `fieldDetectionTimeMs` (double, required) — The time taken to detect fields, in milliseconds.
- `fieldAnnotationTimeMs` (double, required) — The time taken to annotate field positions, in milliseconds.

### RunUsage

Usage credits consumed by a run. **Availability:** This field will not be returned for: * Runs created before October 7, 2025 * Customers on legacy billing systems For more details on how credits work, see our [Credits Guide](https://docs.extend.ai/general/how-credits-work).

- `credits` (double, required) — The credits consumed by this run. For most run types this is the line item for the run's own work; for `workflow_run` this is the aggregate across all child runs.
- `totalCredits` (double, optional) — The total credits accounted for under this run, including any other runs it was responsible for creating. For example, an extract run on a fresh upload triggers a parse run, so `totalCredits` includes both line items. For runs that didn't trigger any other work — like `parse_run`, `edit_run` and `workflow_run` — `totalCredits` equals `credits`. **Availability:** Present on runs persisted on or after May 14, 2026. Runs persisted before that date will omit this field.
- `breakdown` (list of RunUsageBreakdownEntry, optional) — The chargeable resources that make up `totalCredits`, including this run itself when it has its own line item. For `workflow_run`, lists every contributing child run sorted by creation time (the workflow itself isn't chargeable and has no line item). **Availability:** Present on runs persisted on or after May 14, 2026. Runs persisted before that date will omit this field.

### FileMetadata

- `pageCount` (double, optional) — The number of pages in the file. This is only set for PDF/DOCX files.
- `parentSplit` (ParentSplit, optional) — The split metadata details for a derivative file. **Availability:** Only included if this file is a derivative of another file, for instance if it was created via a Splitter in a workflow.

### EditRootJSON

JSON Schema definition for editing PDF documents. The schema defines the structure and placement of fields to edit. It also supports JSON Schema conditional keywords at the root level, including `dependentRequired`, `if` / `then` / `else`, and logical combinators such as `allOf`, `oneOf`, `anyOf`, and `not`. Conditional property constraints do not accept `extend_edit:*` keys.

- `type` (enum, required) — Must be "object" for the root schema
  - Allowed values: `object`
- `properties` (map from string to EditJSON, required) — Map of field names to their schema definitions
- `required` (list of string, optional) — List of required field names
- `additionalProperties` (boolean, optional) — Whether additional properties are allowed
- `dependentRequired` (map from string to list of string, optional) — Map of field names to additional fields that become required when the key field is present.
- `if` (EditConditionalClause, optional) — Recursive conditional clause for edit schemas. Use these clauses with root-level `if` / `then` / `else`, `dependentRequired`, and logical combinators to model conditional field requirements.
- `then` (EditConditionalClause, optional) — Recursive conditional clause for edit schemas. Use these clauses with root-level `if` / `then` / `else`, `dependentRequired`, and logical combinators to model conditional field requirements.
- `else` (EditConditionalClause, optional) — Recursive conditional clause for edit schemas. Use these clauses with root-level `if` / `then` / `else`, `dependentRequired`, and logical combinators to model conditional field requirements.
- `allOf` (list of EditConditionalClause, optional) — List of conditional clauses that must all match.
- `oneOf` (list of EditConditionalClause, optional) — List of conditional clauses where exactly one must match.
- `anyOf` (list of EditConditionalClause, optional) — List of conditional clauses where at least one must match.
- `not` (EditConditionalClause, optional) — Recursive conditional clause for edit schemas. Use these clauses with root-level `if` / `then` / `else`, `dependentRequired`, and logical combinators to model conditional field requirements.

### EditSchemaGenerationConfigAdvancedOptions

Advanced options for schema generation.

- `tableParsingEnabled` (boolean, optional) — Whether to parse table regions as arrays of objects. Defaults to `false`.
- `radioEnumsEnabled` (boolean, optional) — Whether to represent radio groups as enums so only one option can be selected. Defaults to `true` for Edit `1.0.0` and `1.0.0-beta`, and `false` for `0.0.1`.
- `nativeFieldsOnly` (boolean, optional) — If enabled, only native AcroForm fields from the PDF will be imported and used in the schema, skipping object detection. Defaults to `false`.
- `conditionalGenerationEnabled` (boolean, optional) — When enabled, reads requirements explicitly stated in the form and adds supported root-level JSON Schema conditional validation rules to the generated schema. These rules validate form data when the schema is used for an edit; they do not add interactive UI behavior. If generated edit values do not satisfy the rules, the Edit run fails with `SCHEMA_VALIDATION_ERROR`. Defaults to `false`.

### EditSchemaGenerationMappingResult

Mapping information between an input schema and the detected form fields.

- `matches` (list of EditSchemaGenerationMappingMatch, required) — Fields from the input schema that were successfully mapped to detected form fields.
- `unmatchedInputPaths` (list of string, required) — Input schema field paths that could not be matched to the form.
- `unusedFormFieldKeys` (list of string, required) — Detected form field keys that were not used by the input schema mapping.

### RunUsageBreakdownEntry

One line item in a run's `usage.breakdown`. Each entry corresponds to a concrete chargeable resource that contributed credits to the parent operation. When `charges` is present, it itemizes the cost drivers behind this entry's `credits`.

- `object` (enum, required) — The public object type of the contributing resource. Mirrors the top-level `object` field on the corresponding endpoint so callers can fetch the underlying resource by id if they want more detail.
  - Allowed values: `extract_run`, `classify_run`, `split_run`, `parse_run`, `edit_run`, `form_detection_run`
- `id` (string, required) — The id of the contributing resource (e.g. `pr_3UZSj69pYZDKHFuuX57ic`).
- `credits` (double, required) — Credits charged to the contributing resource.
- `charges` (list of RunUsageBreakdownCharge, optional) — Itemized cost drivers that make up this entry's `credits`. When present, `sum(charges[].credits) === credits`. **Availability:** Present on runs persisted on or after June 10, 2026. Runs persisted before that date will omit this field.

### ParentSplit

The split metadata details for a derivative file. **Availability:** Only included if this file is a derivative of another file, for instance if it was created via a Splitter in a workflow.

- `id` (string, required) — The ID of the split.
- `type` (string, required) — The type of the split.
- `identifier` (string, required) — The identifier of the split.
- `startPage` (integer, required) — The start page of the split.
- `endPage` (integer, required) — The end page of the split.

### EditJSON

Schema definition for a field to edit in a PDF. This is a union type that supports: * `EditStringJSONSchema` - type: ["string", "null"], field_type: "text" | "signature" * `EditNumberJSONSchema` - type: ["number", "null"], field_type: "text" * `EditIntegerJSONSchema` - type: ["integer", "null"], field_type: "text" * `EditBooleanJSONSchema` - type: ["boolean", "null"], field_type: "checkbox" | "radio" * `EditArrayJSONSchema` - type: "array", field_type: "text" | "table" * `EditEnumJSONSchema` - has enum property (no type field), field_type: "radio" | "optionList" | "dropdown" * `EditObjectJSON` - type: "object", field_type: "signature" All variants share common `extend_edit:*` properties for positioning and styling.

- `type` (any, optional) — The JSON schema type of the field. Can be: * A string: "array" or "object" * A nullable tuple array: ["string", "null"], ["number", "null"], ["integer", "null"], ["boolean", "null"] * Omitted for enum fields (use enum property instead)
- `description` (string, optional) — Description of the field
- `extend_edit:field_type` (enum, optional) — The PDF field type to edit. Allowed values depend on the schema type: * `["string", "null"]` → `text`, `signature` * `["number", "null"]` → `text` * `["integer", "null"]` → `text` * `["boolean", "null"]` → `checkbox`, `radio` * `"array"` → `text`, `table` * `"object"` → `signature` * enum fields (no type) → `radio`, `optionList`, `dropdown`
  - Allowed values: `text`, `checkbox`, `radio`, `dropdown`, `optionList`, `signature`, `table`, `unknown`
- `extend_edit:bbox` (EditBoundingBox, optional) — Bounding box coordinates for the field location in the PDF (pixel coordinates)
- `extend_edit:bboxes` (list of EditBoundingBox, optional) — Array of bounding boxes for radio enums. Enum at index i corresponds to bbox at index i.
- `extend_edit:page_index` (integer, optional) — Zero-based page index where the field should be placed
- `extend_edit:text_edit_options` (EditTextOptions, optional) — Text styling options for text fields
- `extend_edit:column_width` (double, optional) — Width of the column as a percentage (for table fields)
- `extend_edit:source_acroform` (EditSourceAcroForm, optional) — Details about the original PDF form field. When Detect Form returns this property, include it unchanged in Edit requests.
- `extend_edit:value` (any, optional) — The value to fill into this field. Can be any type. This will force the value at this field to be filled with this value. If a value is not provided, we will attempt to generate or infer one based on the instructions.
- `extend_edit:image` (EditJsonExtendEditImage, optional) — Image fill for signature fields. Only PNG and JPEG image URLs are supported.
- `extend_edit:row_heights` (list of double, optional) — Array of row height percentages for array/table fields (e.g. [0.25, 0.50, 0.25])
- `items` (EditObjectJSON, optional) — Schema for array items (when type is "array"). Must be an EditObjectJSON.
- `properties` (map from string to EditJSON, optional) — Nested properties for object types. Each property follows the EditJSON structure.
- `enum` (list of string, optional) — Allowed values for enum/dropdown/radio fields
- `extend:descriptions` (list of string, optional) — Human-readable labels for the values in `enum`, in the same order. Include this property when using a schema returned by Detect Form.
- `maxItems` (integer, optional) — Maximum number of rows for array/table fields
- `required` (list of string, optional) — List of required property names (for object types)
- `additionalProperties` (boolean, optional) — Whether additional properties are allowed (for object types)

### EditConditionalClause

Recursive conditional clause for edit schemas. Use these clauses with root-level `if` / `then` / `else`, `dependentRequired`, and logical combinators to model conditional field requirements.

- `properties` (map from string to EditConditionalProperty, optional) — Conditional field constraints keyed by top-level property name.
- `required` (list of string, optional) — List of fields that must be present when this clause applies.
- `dependentRequired` (map from string to list of string, optional) — Map of field names to additional fields that become required when the key field is present.
- `if` (EditConditionalClause, optional) — Recursive conditional clause for edit schemas. Use these clauses with root-level `if` / `then` / `else`, `dependentRequired`, and logical combinators to model conditional field requirements.
- `then` (EditConditionalClause, optional) — Recursive conditional clause for edit schemas. Use these clauses with root-level `if` / `then` / `else`, `dependentRequired`, and logical combinators to model conditional field requirements.
- `else` (EditConditionalClause, optional) — Recursive conditional clause for edit schemas. Use these clauses with root-level `if` / `then` / `else`, `dependentRequired`, and logical combinators to model conditional field requirements.
- `allOf` (list of EditConditionalClause, optional) — List of nested conditional clauses that must all match.
- `oneOf` (list of EditConditionalClause, optional) — List of nested conditional clauses where exactly one must match.
- `anyOf` (list of EditConditionalClause, optional) — List of nested conditional clauses where at least one must match.
- `not` (EditConditionalClause, optional) — Recursive conditional clause for edit schemas. Use these clauses with root-level `if` / `then` / `else`, `dependentRequired`, and logical combinators to model conditional field requirements.

### EditSchemaGenerationMappingMatch

A successful mapping between an input schema path and a detected form field.

- `inputPath` (string, required) — The path from the provided `inputSchema`.
- `formFieldKey` (string, required) — The detected form field key matched to the input path.

### RunUsageBreakdownCharge

A single cost driver within a breakdown entry's credit total. The per-unit rate is `credits / quantity`. Certain charges, such as `agent_usage`, have a unit of `usd`

- `product` (string, required) — Identifier for the billable cost driver. Base charges use the processor and tier (e.g. `extraction_performance`, `extraction_light`, `parse_light`); add-ons use the feature code (e.g. `review_agent`, `large_array_max_context`, `extraction_schema_groups`, `priority_parsing`, `agentic_text_correction`, `advanced_excel_parsing`); `agent_usage` is an Operator overage for unusually high effort relative to document size.
- `unit` (enum, required) — The unit `quantity` is measured in. `page` for per-page charges, `cell` for advanced Excel parsing, `usd` for additional amounts billed such as Operator overages (`agent_usage`).
  - Allowed values: `page`, `cell`, `usd`
- `quantity` (double, required) — How many units this charge was billed for.
- `credits` (double, required) — Credits consumed by this charge.
- `pages` (list of integer, optional) — 1-indexed page numbers that incurred this charge. Present on usage-based add-ons that are only billed for the pages where they actually applied (e.g. `agentic_text_correction`, `agentic_table_correction`).

### EditBoundingBox

Bounding box coordinates for the field location in the PDF (pixel coordinates)

- `left` (double, required) — The left coordinate of the bounding box (pixels)
- `top` (double, required) — The top coordinate of the bounding box (pixels)
- `right` (double, required) — The right coordinate of the bounding box (pixels)
- `bottom` (double, required) — The bottom coordinate of the bounding box (pixels)

### EditTextOptions

Text styling options for text fields

- `fontSize` (double, optional) — Font size in points
- `color` (list of integer, optional) — RGB color values from 0 to 255 for text color.
- `opacity` (double, optional) — Text opacity from 0 to 1. Defaults to 1.
- `font` (string, optional) — Font family name
- `combing` (boolean, optional) — Whether this is a combed field (like SSN fields with individual character boxes)
- `maxLength` (integer, optional) — Maximum number of characters allowed
- `multiLine` (boolean, optional) — Whether text can wrap across multiple lines
- `fontColor` (list of integer, optional, deprecated) — Deprecated alias for `color`. RGB color values from 0 to 255.

### EditSourceAcroForm

Details about the original PDF form field. When Detect Form returns this property, include it unchanged in Edit requests.

- `fieldName` (string, required) — Name of the PDF form field.
- `fieldType` (enum, required) — Type of the original native PDF field.
  - Allowed values: `text`, `checkbox`, `radio`, `dropdown`, `optionList`, `signature`
- `optionMap` (list of EditSourceAcroFormOption, optional) — Supported choices for radio, dropdown, and option-list fields.
- `optionValue` (string, optional) — Value used when this option is selected.

### EditJsonExtendEditImage

Image fill for signature fields. Only PNG and JPEG image URLs are supported.

- `image_url` (string, required) — URL of the image to place in the signature field.

### EditObjectJSON

Schema definition for an object field in a PDF edit schema. Used for signature fields and as items schema for arrays/tables.

- `type` (enum, optional) — Must be "object" for object schemas
  - Allowed values: `object`
- `description` (string, optional) — Description of the field
- `extend_edit:field_type` (enum, optional) — The PDF field type. For object schemas, must be "signature".
  - Allowed values: `signature`
- `properties` (map from string to EditJSON, optional) — Nested properties. Each property follows the EditJSON structure.
- `required` (list of string, optional) — List of required property names
- `additionalProperties` (boolean, optional) — Whether additional properties are allowed

### EditConditionalProperty

Field-level schema fragment used inside conditional clauses. These condition objects support nested JSON Schema structure such as `type`, `enum`, `items`, `properties`, `required`, and `contains`, but do not allow any `extend_edit:*` placement or styling keys.

- `type` (any, optional) — JSON Schema type for the conditional property. Can be a simple type such as `"object"` or `"array"`, a nullable tuple like `["string", "null"]`, or omitted for enum-only constraints.
- `description` (string, optional) — Description of the field constraint.
- `enum` (list of EditConditionalPropertyEnumItems, optional) — Allowed values for enum-based conditional constraints.
- `items` (EditConditionalProperty, optional) — Nested array item schema for conditional array constraints.
- `properties` (map from string to EditConditionalProperty, optional) — Nested object property constraints.
- `required` (list of string, optional) — Required nested object properties.
- `additionalProperties` (boolean, optional) — Whether additional nested object properties are allowed.
- `const` (any, optional) — Exact value that the property must match.
- `pattern` (string, optional) — Regular expression that string values must match.
- `contains` (EditConditionalProperty, optional) — Conditional schema that at least one array item must satisfy.
- `minimum` (double, optional) — Inclusive lower bound for numeric values.
- `maximum` (double, optional) — Inclusive upper bound for numeric values.
- `exclusiveMinimum` (double, optional) — Exclusive lower bound for numeric values.
- `exclusiveMaximum` (double, optional) — Exclusive upper bound for numeric values.
- `minLength` (integer, optional) — Minimum string length.
- `maxLength` (integer, optional) — Maximum string length.
- `minItems` (integer, optional) — Minimum number of array items.
- `maxItems` (integer, optional) — Maximum number of array items.
- `minContains` (integer, optional) — Minimum number of matching items for `contains`.
- `maxContains` (integer, optional) — Maximum number of matching items for `contains`.

### EditSourceAcroFormOption

A supported choice for a PDF form field.

- `schemaValue` (string, required) — Value used in the Edit schema.
- `exportValue` (string, required) — Value used by the PDF form field.
- `displayValue` (string, required) — Label shown in the PDF form.

### EditConditionalPropertyEnumItems