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

# document.extracted

Triggered when the document processing pipeline finishes, whether or not extraction actually ran.

## Event Type

`document.extracted`

## Description

This event fires once per document outcome: `completed` when the pipeline finished (extraction may have been skipped because validation flagged the document), and `failed` when extraction itself errored. The payload always includes a `classification` object describing which checklist item(s) the document matched, with per-item validation results on each matched item.

## Payload Structure

<ResponseField name="event" type="string" required>
  The event type, always `document.extracted`
</ResponseField>

<ResponseField name="workspaceId" type="string" required>
  ID of the workspace this event belongs to
</ResponseField>

<ResponseField name="leadId" type="string" required>
  ID of the lead this document belongs to
</ResponseField>

<ResponseField name="externalLeadId" type="string" required>
  External ID of the lead this document belongs to, if one was provided at
  creation
</ResponseField>

<ResponseField name="documentId" type="string" required>
  ID of the document that was processed
</ResponseField>

<ResponseField name="externalId" type="string" nullable>
  External identifier for the document, if one was provided at creation
</ResponseField>

<ResponseField name="status" type="string" required>
  `completed` when the pipeline finished or `failed` when extraction errored
</ResponseField>

<ResponseField name="parentActionId" type="string">
  ID of the parent action that triggered the pipeline
</ResponseField>

<ResponseField name="summary" type="string" nullable>
  One- to two-sentence document summary from OCR, when available (same as stored
  on the document)
</ResponseField>

<ResponseField name="type" type="string" nullable>
  Inferred document type from OCR (same as the `type` column on `documents`,
  e.g. `Bank Statement`, `Tax Return`). `null` when not set.
</ResponseField>

<ResponseField name="classification" type="object" required>
  How the document was classified before extraction (or an empty match list
  with a no-match reason)

  <Expandable title="classification">
    <ResponseField name="noMatchedItemReason" type="string" nullable>
      When the document was not matched to a checklist item, a short
      human-readable reason; otherwise `null`
    </ResponseField>

    <ResponseField name="matchedChecklistItems" type="array" required>
      Checklist item rows the model linked this document to

      <Expandable title="matchedChecklistItems[]">
        <ResponseField name="checklistItemCode" type="string" nullable>
          The checklist item code from configuration, if present
        </ResponseField>

        <ResponseField name="fieldType" type="string" nullable>
          Field type for the checklist item
        </ResponseField>

        <ResponseField name="label" type="string" required>
          Checklist item label
        </ResponseField>

        <ResponseField name="leadChecklistItemId" type="string" required>
          ID of the lead checklist item row
        </ResponseField>

        <ResponseField name="validation" type="object" nullable>
          Validation result for this checklist item. `null` when no validation
          ran (no rules, not a period-checked field type).

          <Expandable title="validation">
            <ResponseField name="reasons" type="string[]" required>
              For invalid items, one message per failed rule; empty when
              `status` is `valid`
            </ResponseField>

            <ResponseField name="status" type="string" required>
              `valid` when the item passed every rule, `invalid` when any rule
              failed
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="extractionResult" type="object" required>
  Returns any checklist items extracted from documents.

  <Expandable title="extractionResult">
    <ResponseField name="items" type="array">
      Array of extracted data items

      <Expandable title="items">
        <ResponseField name="checklistItemCode" type="string" nullable>
          The checklist item code from configuration, when the extracted value
          maps to a configured checklist item; `null` otherwise
        </ResponseField>

        <ResponseField name="label" type="string">
          Label/field name for the extracted value
        </ResponseField>

        <ResponseField name="leadChecklistItemId" type="string">
          ID of the lead checklist item this value was extracted for (if
          applicable)
        </ResponseField>

        <ResponseField name="value" type="string">
          Extracted value
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="extractedCount" type="number">
      Number of items with a non-empty extracted value
    </ResponseField>
  </Expandable>
</ResponseField>

## Examples

### Successful extraction

<ResponseExample>
  ```json theme={null}
  {
    "event": "document.extracted",
    "workspaceId": "6048d78a-584a-4f1e-9e39-e011ca4cc48c",
    "leadId": "910bb19a-2e9d-400f-8d15-9c461bb0f4aa",
    "externalLeadId": "SF-00142",
    "documentId": "ac52376a-fe68-4024-8b16-6acdcb9b3530",
    "externalId": "DOC-2025-001",
    "status": "completed",
    "parentActionId": "9d7fe2f3-ec1a-481c-b814-a0d1c8017e1f",
    "summary": "Business bank statement for Q1 2025 with ending balance and transactions.",
    "type": "Bank Statement",
    "classification": {
      "noMatchedItemReason": null,
      "matchedChecklistItems": [
        {
          "checklistItemCode": "company-legal-name",
          "fieldType": "TEXT",
          "label": "Company Name",
          "leadChecklistItemId": "adc887d0-7238-4ce0-998d-523a22c282f4",
          "validation": null
        }
      ]
    },
    "extractionResult": {
      "items": [
        {
          "checklistItemCode": "company-legal-name",
          "label": "Company Name",
          "leadChecklistItemId": "adc887d0-7238-4ce0-998d-523a22c282f4",
          "value": "OmniAI Technology Inc."
        }
      ],
      "extractedCount": 1
    }
  }
  ```
</ResponseExample>

### Completed with validation failure

When at least one matched checklist item has `validation.status: "invalid"`, extraction is not run, but the pipeline still reports `status: completed`. `extractionResult` is still present with an empty `items` array and `extractedCount: 0`; the per-item `validation` block on each matched item carries the failure reasons (`null` when no rules ran).

<ResponseExample>
  ```json theme={null}
  {
    "event": "document.extracted",
    "workspaceId": "6048d78a-584a-4f1e-9e39-e011ca4cc48c",
    "leadId": "910bb19a-2e9d-400f-8d15-9c461bb0f4aa",
    "externalLeadId": "SF-00142",
    "documentId": "8f0c3d1b-2a00-4f0d-8c1e-0e5f1a2b3c4d",
    "externalId": "DOC-2025-002",
    "status": "completed",
    "parentActionId": "9d7fe2f3-ec1a-481c-b814-a0d1c8017e1f",
    "summary": "Monthly business checking statement.",
    "type": "Bank Statement",
    "classification": {
      "noMatchedItemReason": null,
      "matchedChecklistItems": [
        {
          "checklistItemCode": "bank-statement",
          "fieldType": "BANK_STATEMENT",
          "label": "Recent bank statement",
          "leadChecklistItemId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9",
          "validation": {
            "reasons": [
              "The statement end date is earlier than the requested coverage period."
            ],
            "status": "invalid"
          }
        }
      ]
    },
    "extractionResult": {
      "items": [],
      "extractedCount": 0
    }
  }
  ```
</ResponseExample>