---
title: "Intelligent Document Processing (IDP)"
source: "https://docs.vertesiahq.com/content/grounded-extraction"
markdown: "https://docs.vertesiahq.com/llms/content/grounded-extraction.md"
---

# Intelligent Document Processing (IDP)

Vertesia IDP extracts structured data from digital, scanned, and handwritten documents. Every extracted value keeps a citation to its source, and the result records how each value was verified before it is used by downstream systems.

IDP is designed for documents such as purchase orders, invoices, order acknowledgements, applications, and forms where structured fields are more useful than a page-by-page transcription.

## What IDP produces

An IDP run can produce:

- properties shaped by the content type schema
- page and region citations for extracted values
- a verification breakdown for digital, AI-verified, and unverified values
- a document-level `good_to_go` or `needs_review` verdict
- applied reviewer corrections and unresolved issues
- downloadable source, citation, and annotated proof artifacts
- a `document_processed` event for processes, webhooks, and operational reporting

The result updates the content object's properties through standard intake. It can also render those properties into concise markdown for search, embeddings, and agents.

## How it works

1. **Prepare the pages.** Vertesia uses the document text layer where it is reliable. Scanned or handwritten pages are prepared for visual extraction or OCR according to the policy.
2. **Extract against the schema.** The extraction model returns structured data and identifies the source location for every value.
3. **Verify citations.** Values are matched against digital text or OCR evidence where possible.
4. **Review when required.** A review model examines values that are not fully verified, difficult pages, and possible omissions. Confident source-grounded corrections are applied automatically; unresolved uncertainty remains an issue.
5. **Issue a verdict.** After corrections, the reviewer decides whether the result is faithful and complete enough for downstream processing. Business rules can still run in downstream systems.
6. **Publish the outcome.** The object stores the extraction result and Vertesia publishes an operational event that can start the next process.

## Verification states

The verification breakdown counts values, not model confidence claims:

| State | Meaning |
|---|---|
| **Digitally verified** | The extracted value matches source text from the digital document or its OCR representation. |
| **AI verified** | The reviewer confirmed the value directly against the page image. This is the primary verification path for handwriting and other content without dependable digital text. |
| **Unverified** | The value was read from the page but has not been confirmed by text matching or the reviewer. |

Studio displays the counts separately so operators can distinguish deterministic text verification from visual model verification. Selecting a value highlights its citation on the source page.

The document also carries a verification score and a separate complexity score. Complexity describes how difficult the source was to read; it can route difficult content to a stronger extraction model without being confused with the quality of the final result.

## The reviewer verdict

When review is enabled, the reviewer evaluates source fidelity, semantic meaning, and material completeness after applying confident corrections:

- `good_to_go` means the extracted data is faithful and complete enough to enter downstream processing.
- `needs_review` means material uncertainty or an unsafe correction remains and a person or another process should inspect the result.

The reviewer is not a replacement for domain validation. A downstream order process can still check product identifiers, totals, account status, or other business rules.

## Configure IDP in Studio

IDP is part of standard intake and is configured per content type:

1. Open **Content > Types** and select the type.
2. Open the **Intake** tab.
3. In **Extraction**, enable property extraction and choose the evidence source.
4. Open **Grounding** and enable IDP grounding.
5. Select the primary, hard-content, and review models as needed.
6. Enable review for documents that should receive an AI verification pass.
7. Save the policy and reprocess existing documents, or upload new documents normally.

Project-wide defaults live under **Settings > Project > Intake**. A content type inherits those defaults and overrides only the fields configured on the type.

See [Intake Configuration](/content/intake-policies) for the full policy hierarchy and combined IDP/markdown examples.

## Example policy

```json
{
  "text_conversion": {
    "enabled": false
  },
  "extraction": {
    "enabled": true,
    "source": "mixed",
    "grounding": {
      "enabled": true,
      "use_vision": true,
      "raster_mode": "vision",
      "hardness_threshold": 0.5,
      "min_citation_density": 0.3,
      "review": {
        "enabled": true,
        "coverage_threshold": 0.2
      }
    }
  },
  "rendering_template": "# Order {{properties.order_number}}\n\n**Vendor:** {{properties.vendor_name}}\n**Total:** {{properties.total_amount}}"
}
```

In this setup, IDP produces the structured properties and a rendering template produces the object's markdown text. Enable [Markdown Conversion](/semantic/getting-started) as well when the complete document narrative must remain available.

### Common grounding settings

| Setting | Purpose |
|---|---|
| `enabled` | Enables IDP for the type. |
| `use_vision` | Lets extraction use the page image in addition to document text. |
| `raster_mode` | Uses direct visual reading or OCR for image-only pages. |
| `config` | Primary extraction model configuration. |
| `hard_config` | Model configuration used for difficult content. |
| `hardness_threshold` | Complexity level that activates the hard-content model. |
| `window_pages` | Limits pages per extraction call for long documents. |
| `min_citation_density` | Rejects results that cite too few extracted values. |
| `review.enabled` | Enables post-extraction verification and correction. |
| `review.config` | Review model configuration. |
| `review.force` | Reviews every result, regardless of complexity. |
| `review.coverage_threshold` | Reviews results when a page appears under-cited. |

The structured form covers the common fields. The **JSON** tab remains available for advanced settings and validates the policy against the current schema.

## Control what is extracted

The content type's `object_schema` defines the result shape. Mark fields that are populated by downstream systems with `"x-extract": false` so they are not sent to the extraction model.

```json
{
  "type": "object",
  "properties": {
    "order_number": { "type": "string" },
    "erp_order_id": {
      "type": "string",
      "x-extract": false
    },
    "line_items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "sku": { "type": "string" },
          "quantity": { "type": "number" },
          "catalog_match_id": {
            "type": "string",
            "x-extract": false
          }
        }
      }
    }
  }
}
```

## Inspect the result

Open the object and select its IDP result view. The page viewer and structured data are shown together:

- select a field to highlight its cited region
- switch between the original and instrumented page when visual grid grounding was used
- inspect whether the value was digitally verified, AI verified, or remains unverified
- review the final verdict, reason, corrections, and unresolved issues
- download the complete result JSON and proof artifacts when deeper inspection is required

The full result is stored as `grounded-extraction.json`. It contains the extracted data, citations, page locations, verification information, complexity, verdict, and review record.

## SDK access

Normal processing should use standard intake so the complete project and content type policies are applied. The analyze API is also available for a deliberate IDP rerun on an existing object:

```ts
await client.objects.analyze(objectId).startGroundedExtraction();
```

Read the completed operational result:

```ts
const result = await client.objects.analyze(objectId).getGroundedExtractionResult();

console.log(result.verdict);
console.log(result.verification);
console.log(result.data);
```

## Trigger downstream processing

After IDP completes, Vertesia publishes a `document_processed` event containing the object, run, verdict, verification counts, model information, result location, and workflow identifiers. Event Bus subscriptions can:

- start a process only for `good_to_go` documents
- route `needs_review` documents to a task inbox
- call a signed webhook
- feed operational dashboards and audit reporting

See [Event Subscriptions](/events/subscriptions#idp-document-events) for the event contract and subscription examples.