---
title: "Correct extraction data"
method: PATCH
path: "/v1/extractions/{id}/data"
tags: ["Extractions"]
---

# Correct extraction data

`PATCH /v1/extractions/{id}/data`

## Request

- Base URL: `https://api.talonic.com`
- URL: `https://api.talonic.com/v1/extractions/{id}/data`
- Auth: HTTP bearer

Submit field-level corrections. Each key in the body is a field name; the value
is the corrected value. Corrected fields are locked at confidence 1.0.

Corrections are written to the **value plane** as new cell versions
(`source: api_correction`) and mirrored into the extraction data. They pass the
central cell-write authority guard first: a field whose current value was
promoted by review, or is held for approval, is **withheld** and reported in
`cells_skipped` instead of being overwritten. A document that has no
capture-layer record yet answers `value_plane: "not_migrated"` and is corrected
in the extraction data only.

## Path parameters

- `id` string, uuid, required

## Request body

- object: Object mapping field names to corrected values.

## Response `200`

Updated extraction with corrections applied.

- ExtractionCorrectionResponse: An extraction, plus what the correction did in the value plane. The top-level shape is unchanged from ExtractionResponse; the three correction fields are additive.
  - `id` string, uuid, required
  - `status` 'complete' | 'failed' | 'processing', required
  - `document` object, required
    - `id` string, uuid
    - `filename` string
    - `pages` integer
    - `type_detected` string, nullable
  - `data` object, required: Extracted key-value pairs.
  - `confidence` object, required
    - `overall` number, float
    - `fields` object
  - `locked_fields` string[]: Fields that have been manually corrected (locked at confidence 1.0).
  - `batch_id` string: The caller grouping key stamped on this document at ingestion (documents.client_batch_id) — e.g. from POST /v1/run or POST /v1/sources/:id/documents. Present only when set.
  - `metadata` object: The caller's flat metadata bag stamped on this document at ingestion (documents.client_metadata) — for a /v1/run input, its per-request EFFECTIVE merged bag (call-level metadata merged with any file_metadata entry). Present only when set.
  - `processing` object
    - `duration_ms` integer
    - `pages_processed` integer
    - `region` string
  - `created_at` string, date-time
  - `links` object
    - `self` string
    - `data` string
    - `document` string
    - `dashboard` string, uri
  - `value_plane` 'written' | 'not_migrated', required: `written` — the corrections landed as new value-plane cell versions. `not_migrated` — the document has no capture-layer record yet, so the correction was applied to the legacy extraction JSONB only.
  - `cells_written` string[], required: Field names that became new value-plane cell versions.
  - `cells_skipped` object[], required: Fields the central cell-write authority guard withheld. A value promoted by review (`human_review`, `auto_adjudication`, `agentic_review`) outranks a machine correction, and a cell held for approval stays held. A withheld field is not applied to the extraction data either — it keeps its previous value everywhere.
    - `field` string, required: The field name as submitted in the request body.
    - `reason` 'review_authority' | 'pending_approval', required

## Other responses

- `400`: The request is invalid.
- `401`: Missing or invalid API key.
- `403`: The API key does not have the required scope.
- `404`: The requested resource was not found.
- `429`: Daily rate limit exceeded.

---

[API](https://skmtc.dev/talonic/apis/talonic-api.md) · [All operations](https://skmtc.dev/talonic/apis/talonic-api/llms.txt) · [OpenAPI document](https://skmtc.dev/talonic/apis/talonic-api/revisions/678fe5f8c9c3?raw)