Override

Manually override the selected N-Shot value for a document-field pair by choosing a shot number. Records a full audit trail with from/to values and reason.

POST /v1/jobs/runs/{runId}/nshot/override manually overrides the selected value for a specific document-field comparison by choosing a shot number. Use it when the majority_value is wrong and a different shot produced the correct extraction — a common situation on yellow comparisons where the minority shot happens to match the document's canonical format, or on red comparisons where no majority exists at all.

The override is written onto the comparison as an audit record: selected_shot, the acting principal (actor_id: "api" for every override submitted through this endpoint), an overridden_at timestamp, from_value (the comparison's majority value), to_value (the chosen shot's value), and your optional free-text reason. The full updated comparison is returned, so the response doubles as a read of the new state.

Overrides are idempotent to repeat and safe to revise: submitting a new override for the same cell replaces the previous record wholesale. from_value always restates the original majority_value — not the previously overridden value — so the audit record always answers "what did the shots say vs. what did we pick" no matter how many times the cell was corrected.

Pair this endpoint with the [judge-decision endpoint](nshot-judge-decision) for scale: let the LLM judge propose values on flagged cells and accept them in bulk, reserving manual overrides for cells where you disagree with both the majority and the judge. Both paths mark the comparison as overridden in the [summary](nshot-summary), so review progress is visible from the aggregate counts.

Pass a selected_shot that exists in the comparison's values array. A shot number that matches no shot is not rejected: the override is still recorded, with to_value set to null. Check the values array first and pass one of its shot_number entries.

POST/v1/jobs/runs/{runId}/nshot/override

Body parameters

document_id*uuidDocument ID.

field_name*stringField name.

selected_shot*integerThe shot number whose value becomes the override value.

reasonstringOptional reason for the override, stored in the audit trail.

Request

curl -X POST https://api.talonic.com/v1/jobs/runs/a1b2c3d4-e5f6-7890-abcd-ef1234567890/nshot/override \
  -H "Authorization: Bearer tlnc_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "document_id": "d4e5f6a7-b8c9-0123-defa-234567890123",
    "field_name": "total_amount",
    "selected_shot": 1,
    "reason": "Canonical decimal format preferred"
  }'

Response

Response fields

idstringComparison UUID.

run_idstringJob run UUID.

document_idstringDocument UUID.

field_namestringField name.

statusstringAgreement status — unchanged by the override.

majority_valuestring | nullOriginal majority value.

valuesarrayPer-shot entries: shot_number, value, confidence, source_text.

overrideobjectThe recorded override.

override.selected_shotintegerThe shot number that was selected.

override.actor_idstringAlways "api" when overridden via this endpoint; "judge" when created by an accepted judge decision.

override.overridden_atstringISO 8601 timestamp of the override.

override.from_valuestring | nullThe comparison's majority value at the time of the override.

override.to_valuestring | nullThe selected shot's value; null when selected_shot matched no shot.

override.reasonstringReason provided for the override, when given.

Response

{
  "id": "5f8e2b1a-3c4d-4e5f-8a9b-0c1d2e3f4a5b",
  "run_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "document_id": "d4e5f6a7-b8c9-0123-defa-234567890123",
  "field_name": "total_amount",
  "status": "yellow",
  "agreement_score": 0.6667,
  "majority_value": "12450.00",
  "comparison_method": "exact",
  "values": [
    { "shot_number": 1, "value": "12450.00", "confidence": 0.95, "source_text": "Total due: 12,450.00 EUR" },
    { "shot_number": 2, "value": "12450.00", "confidence": 0.94, "source_text": "Total due: 12,450.00 EUR" },
    { "shot_number": 3, "value": "12,450.00", "confidence": 0.91, "source_text": "Total due: 12,450.00 EUR" }
  ],
  "override": {
    "selected_shot": 1,
    "actor_id": "api",
    "overridden_at": "2026-07-14T11:00:00.000Z",
    "from_value": "12450.00",
    "to_value": "12450.00",
    "reason": "Canonical decimal format preferred"
  },
  "judgement": null,
  "created_at": "2026-07-14T10:32:00.000Z",
  "links": {
    "self": "/v1/jobs/runs/a1b2c3d4-e5f6-7890-abcd-ef1234567890/nshot/comparison?document_id=d4e5f6a7-b8c9-0123-defa-234567890123&field_name=total_amount"
  }
}

Errors

Error responses

400validation_errorThe request body failed validation, e.g. document_id is not a UUID or selected_shot is not a number.

401unauthorizedMissing or invalid API key.

403forbiddenThe API key lacks the write scope required by this endpoint.

404not_foundNo job run with this ID exists for your organization, or no comparison found for the given document_id and field_name.

429rate_limitedDaily request quota for your tier reached. The counter resets at midnight UTC.

Frequently asked questions

Can I override the same comparison multiple times?+

Yes. Each override replaces the previous record wholesale. from_value always restates the comparison's original majority_value — not the previously overridden value — so the audit record consistently contrasts what the shots said with what you picked.

Does an override change the agreement status?+

No. The status (green/yellow/red), agreement_score, and majority_value reflect the original shot agreement and never change when an override is applied. The summary's overridden count is where review progress shows up.

What happens if I pass a selected_shot that does not exist?+

The override is still recorded, but to_value is set to null because no shot value matched. Check the comparison's values array first and pass one of its shot_number entries — shot 1 is the original extraction, shots 2..N are the re-extraction shots.

When should I override instead of accepting the judge?+

Accept judge recommendations for routine flagged cells — accepting creates the override automatically with actor_id "judge". Reach for a manual override when you disagree with both the majority and the judge, or when the judge was not enabled on the run and no recommendation exists.

Override

Response

Errors

Frequently asked questions

Related