Get Extraction

Retrieve a full extraction result by ID with GET /v1/extractions/:id — field values, per-field confidence, normalized numeric magnitudes, and metadata.

The Get Extraction endpoint, GET /v1/extractions/:id, retrieves the complete extraction result for a single document, including all extracted field values, per-field confidence scores, and processing metadata. This is the primary endpoint for consuming structured data produced by the extraction pipeline. The id is the document UUID — extractions are 1:1 with documents.

The response includes the source document summary, a data object with field values, and a confidence object with both an overall score (rounded to two decimals) and individual scores for each field. Fields that have been manually corrected appear in the locked_fields array with confidence 1.0. When the document was submitted with caller tags, the response also echoes batch_id and metadata — both are present only when they were set, so untagged documents serialize without the keys.

Numeric values additionally carry a normalization envelope in two parallel maps: normalized gives each numeric field's canonical base-unit magnitude, and units gives the detected reporting scale (units, thousands, millions, billions, trillions, lakhs, or crores), non-currency unit (currently percent), and ISO currency. A financial statement that prints 674,538 under an "(in thousands)" caption thus also reports normalized = 674538000, so you can aggregate and compare across documents without re-deriving each document's reporting scale. Only fields whose values are genuinely numeric appear in these maps; the raw data values are never modified, per-share amounts are never scaled, and percentages are a rate — never scaled.

Treat the confidence scores as your routing signal: a common integration auto-accepts fields above a threshold you choose and routes the rest to review or the [correction endpoints](correct-extraction). Note two derived values in the metadata: document.pages and processing.pages_processed are estimated from file size rather than counted, and processing.duration_ms sums the document's processing log.

GET/v1/extractions/:id

curl

curl -s https://api.talonic.com/v1/extractions/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer tlnc_your_api_key"

Response

Response fields

iduuidExtraction UUID (identical to the document UUID).

statusstringExtraction status: complete, processing, failed.

documentobjectSource document summary: id, filename, pages (estimated from file size), type_detected.

dataobjectExtracted field values as a key-value map, exactly as read from the document.

normalizedobjectPer numeric field, the canonical base-unit magnitude (the displayed number × the detected scale multiplier). Fields without a numeric value are omitted.

unitsobjectPer numeric field: { scale, unit, currency }. scale is the detected reporting scale (units/thousands/millions/…), unit is a non-currency unit such as percent or null, currency is an ISO code or null.

batch_idstringThe caller-supplied grouping key from submission. Present only when set.

metadataobjectThe caller-supplied flat metadata from submission. Present only when set.

confidenceobjectConfidence scores: overall (0–1, rounded to two decimals) and fields (per-field score map).

locked_fieldsarrayField names that have been manually corrected and locked.

processingobjectProcessing metadata: duration_ms (summed over processing steps), pages_processed (estimated), region.

created_atstringISO 8601 creation timestamp.

linksobjectRelated resource URLs: self, data, document, dashboard.

Response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "complete",
  "document": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "filename": "invoice-0847.pdf",
    "pages": 2,
    "type_detected": "invoice"
  },
  "data": {
    "vendor_name": "Acme Corp",
    "invoice_number": "INV-2026-0847",
    "total_amount": 14250.00,
    "vat_rate": 19,
    "due_date": "2026-03-15"
  },
  "normalized": {
    "total_amount": 14250,
    "vat_rate": 19
  },
  "units": {
    "total_amount": { "scale": "units", "unit": null, "currency": "EUR" },
    "vat_rate": { "scale": "units", "unit": "percent", "currency": null }
  },
  "batch_id": "ERP-2026-07-14-001",
  "metadata": { "source_system": "sap" },
  "confidence": {
    "overall": 0.94,
    "fields": {
      "vendor_name": 0.99,
      "invoice_number": 0.98,
      "total_amount": 0.96,
      "vat_rate": 0.88,
      "due_date": 0.91
    }
  },
  "locked_fields": [],
  "processing": {
    "duration_ms": 3420,
    "pages_processed": 2,
    "region": "eu-west"
  },
  "created_at": "2026-07-14T10:33:12.000Z",
  "links": {
    "self": "/v1/extractions/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "data": "/v1/extractions/a1b2c3d4-e5f6-7890-abcd-ef1234567890/data",
    "document": "/v1/documents/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "dashboard": "https://app.talonic.com/documents/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

Aggregate with normalized, display with data: normalized magnitudes are scale-corrected into base units (a value under an "in millions" header is multiplied out), while data preserves exactly what the document prints. Summing raw data values across documents with different reporting scales silently mixes units.

Errors

Error responses

401unauthorizedMissing or invalid API key.

404not_foundNo extraction with this ID exists for your organization — also returned for documents your Sources IAM rules hide from this key.

429rate_limitedToo many requests. Retry after the period indicated in the Retry-After header.

Frequently asked questions

What does a locked_fields entry mean?+

A locked field has been manually corrected via the correction endpoints. Locked fields always have a confidence of 1.0 and will not be overwritten by re-extraction.

What processing metadata is available?+

The `processing` object includes `duration_ms` (total extraction time, summed over processing steps), `pages_processed` (estimated from file size, like document.pages), and `region` (the datacenter region that handled the request).

How should I use the per-field confidence scores?+

The `confidence.fields` map scores each extracted field from 0 to 1, and `confidence.overall` combines them (rounded to two decimals). A common integration pattern is to auto-accept fields above a threshold you choose and route lower-scoring fields to human review or correction.

What are the normalized and units maps for?+

Cross-document numeric aggregation. normalized holds each numeric field's base-unit magnitude — the printed number multiplied by the reporting scale detected from column headers, section headings, or "(in thousands)"-style captions — and units records that scale plus any percent unit or ISO currency. The raw data value is always preserved unchanged.

Why is a field missing from normalized?+

Only genuinely numeric values carry the envelope: prose, dates, identifiers like INV-1, and values that merely contain digits are skipped, as are parenthesized negatives (skipped conservatively rather than risking a wrong sign). Per-share amounts are deliberately never scaled, and percentages carry unit: "percent" but never a scale multiplier.

When are batch_id and metadata present?+

Only when the document was submitted with those caller tags (for example via POST /v1/run or the ingestion endpoints). Documents submitted without tags return no batch_id or metadata keys at all, so older payload shapes are unchanged.