DocReadi Document Intelligence API

Quickstart

Three commands from a fresh API key to extracted JSON. Get a key at /ui/settings/api-keys (sign up for the free trial first if you don't have a workspace).

# Replace dr_abc… with your real key.
curl -X POST https://docreadi.com/ingest/process \
  -H "X-Api-Key: dr_abc123…" \
  -F "file=@invoice.pdf" \
  -F "source=api"

curl https://docreadi.com/ingest/document/"$DOC_ID" \
  -H "X-Api-Key: dr_abc123…"

# status == "extracted" → response.data carries the typed fields
# for the document_type. AP invoices: invoice_number, vendor_name,
# subtotal, vat_amount, total_amount, line_items, …

Endpoints

Public endpoints are marked. Everything else requires an API key. 30 endpoints across 6 groups.

Confidence

Every extracted document carries two confidence signals on the response. The headline number (`confidence_score`) is the model's overall self-reported confidence in the whole extraction. The granular signal (`field_confidences`) is a dict of field-name → 0.0-1.0 score covering every field the model populated. Use the granular shape — averaging it out into a single document number washes away exactly the information that drives routing decisions.

Response shape

Every extracted document carries both signals on the response. Field names match the keys in data.

{
  "confidence_score": 0.94,
  "field_confidences": {
    "invoice_number": 0.99,
    "vendor_name": 0.98,
    "subtotal": 0.97,
    "vat_amount": 0.96,
    "total_amount": 0.99,
    "due_date": 0.65,
    "vendor_address": 0.78
  },
  "low_confidence_fields": [
    "due_date",
    "vendor_address"
  ]
}

Interpreting the numbers

The numbers come from the model's self-report. They're a useful ordinal signal — 'which field should the reviewer look at first' — but not a calibrated probability you can divide further. Validators (subtotal+VAT=total, ISO dates, VAT-number shapes) layer additional signal on top in a follow-up release.

Display rules

• We cap the displayed percentage at 99%. A model returning 1.0 still renders as 99% — true 100% is rare in any probabilistic system, and a 100% display trains users to over-trust.
• The Lowest Field column on /ui (the document queue) shows min(field_confidences.values()). Older docs without field_confidences fall back to confidence_score.
• low_confidence_fields is auto-derived from field_confidences (any field < 0.85 lands in the list). Kept for back-compat with the legacy binary signal.

Auto-approve gate. Per-tenant, per-doc-type confidence threshold at /ui/settings/review. Threshold gate compares against confidence_score today; future release will optionally gate on min(field_confidences) so a single bad field on an otherwise-good doc still routes to review.

Webhooks

Outbound HMAC-signed event push. Configure a subscription URL at /ui/settings/webhooks; the secret is shown to you exactly once at create time. Every event is delivered with at-least-once semantics — use the X-DocReadi-Event-Id header to dedupe.

Event types

Headers on every delivery

Verify the signature

Stripe-compatible. The signed payload is exactly f"{t}.{raw_request_body}". Recompute HMAC-SHA256 with your webhook secret, hex-encode it, and constant-time compare against the v1 value. Reject signatures whose timestamp is more than 5 minutes from now (replay guard).

import hmac, hashlib, time
def verify(secret: str, body: bytes, header: str) -> bool:
    parts = dict(p.split('=', 1) for p in header.split(','))
    t, v1 = parts.get('t'), parts.get('v1')
    if not t or not v1: return False
    if abs(int(time.time()) - int(t)) > 300: return False
    expected = hmac.new(secret.encode(), f'{t}.'.encode() + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, v1)

Retry policy. Exponential backoff: 30s, 2m, 10m, 1h, 6h. After 5 failed attempts the delivery dead-letters and stops retrying. Any 2xx response counts as success; 4xx and 5xx both schedule a retry.

Configure subscriptions at /ui/settings/webhooks.