How DeepRead Works

DeepRead processes documents as background jobs. You upload a document, poll for the result or get a webhook, and receive Markdown text + optional structured JSON with per-field needs_review flags.

What DeepRead Does

Two engines read the document. extract (the default on Free and Standard) is one OCR pass; deep-extract (the default on Enterprise) reads every page twice, reconciles the two reads and verifies every extracted value. Both end with the same outputs.

The Processing Pipeline

Every document follows this flow; the middle depends on the engine you pick with pipeline:

Why async? These pipelines take seconds per page on extract and longer on deep-extract; async avoids request timeouts.

API Flow

1. Submit a document to POST /v1/process → returns { "id": "...", "status": "queued" }
2. Receive webhook notification when job completes (or check status manually with GET /v1/jobs/{id})
3. Use results (every response carries schema_version: "dp02"):
   • document.content.text = Markdown OCR output
   • document.layout = typed dp.lite.v1 layout object (blocks + page-mappings, on either engine)
   • extraction.fields = structured extraction list (if you provided a schema)
   • review.review_rate + per-field needs_review = what needs verification

See the API Reference for ready to implement examples: API Reference.

Structured extraction

To keep extraction accurate and fast on long documents, DeepRead uses a two-phase strategy:

1. Field page detection (fast): scans all pages (text-only) to find which pages likely contain each field’s value
2. Field extraction (accurate): runs vision extraction only on the relevant pages and returns per-field needs_review flags + validation

When validation fails, the field is flagged with needs_review: true and a review_reason.

How to read the results

Key idea: treat needs_review as your “needs verification” switch, and use the review summary for routing.

{
  "status": "completed",
  "schema_version": "dp02",
  "extraction": {
    "fields": [
      {
        "key": "total_amount",
        "value": 1250.0,
        "needs_review": true,
        "review_reason": "Consensus disagreement on page 3: ...",
        "location": { "page": 3 }
      }
    ]
  },
  "review": {
    "quality_score": 0.95,
    "review_rate": 0.05
  }
}

See Human Review Flags and Jobs & Webhooks.

Optimizer

The optimizer improves your schema using sample documents (not run on every production job). See The Optimizer.

Error Handling

Failed jobs return status: "failed" with an error message. Common errors:

See Error Handling & Retry for recovery strategies.