Skip to main content

Get Field Review

Get reviewer detail for one held field: cell version history, validation verdicts, recovered source spans for provenance, and the prior decision history.

Get the full reviewer view for one held field, addressed by its pipeline document id and field key. The response bundles everything a human reviewer needs to decide on an extracted value: the queue item, the schema field metadata, the cell version history, the validation verdicts that flagged it, source spans locating the value in the original document (provenance), and the prior decision history for the field.

The cellHistory is the chain of cell versions for the field, showing how the value moved through transfer, extraction, resolution, and any human edits. The verdicts array is the per-validator output (evidence, business rules, n-shot, LLM judge) with each verdict's reasoning. Together they explain why the field was parked and what the candidate values are.

Source spans are best-effort. When a phase recorded a verbatim span it is returned directly; otherwise the server recovers a span by locating the value in the document and may mark it approximate. The priorDecisions array lists earlier human actions on the field so a reviewer sees the full audit trail before deciding. This endpoint requires an API key with the read scope.

Source spans are what make review fast: instead of rereading the document, the reviewer sees the exact quote the value came from. A span flagged approximate: true was recovered after the fact rather than written by the extracting phase.
GET/v1/field-reviews/{docId}/{fieldKey}

curl

curl -s https://api.talonic.com/v1/field-reviews/pd_uuid_1/total_amount \
  -H "Authorization: Bearer tlnc_your_api_key"

Response

Response fields

itemobjectThe queue item for this field (same shape as a list entry).
fieldobject | nullSchema field metadata (type, constraints, display name).
cellHistoryarrayCell versions for the field, oldest to newest, with source and span where available.
matchedSpanobject | nullRecovered source span for the current value. Carries approximate: true when recovered rather than written by a phase.
candidateSpansobject | nullPer-value spans for n-shot candidate values, keyed by value.
candidateSimilarityobject | nullPer-candidate similarity score to the current value (0-1), keyed by value.
verdictsarrayValidation verdicts that flagged the field.
verdicts[].validatorTypestringValidator that produced the verdict (evidence, business_rules, nshot, llm_judge).
verdicts[].verdictstringThe verdict band (e.g. pass, fail, different).
verdicts[].confidencenumber | nullValidator confidence.
verdicts[].reasoningstring | nullWhy the validator returned this verdict.
verdicts[].stageNamestring | nullValidation stage (gate) the verdict came from.
verdicts[].createdAtstringISO 8601 timestamp.
priorDecisionsarrayEarlier human decisions on this field. Advisory recommendations (a reviewer's proposal on a field they could not decide directly) are excluded here — a recommendation is never a resolution. The decisions list endpoint still includes them.
priorDecisions[].actionstringapprove, correct, or override — never recommend: this endpoint excludes advisory recommendation rows.
priorDecisions[].priorValuestring | nullValue before the decision.
priorDecisions[].finalValuestring | nullValue after the decision.
priorDecisions[].reasonstring | nullAudit note recorded with the decision.
priorDecisions[].decidedByNamestring | nullWho decided (api for API-driven decisions).
priorDecisions[].decidedAtstringISO 8601 timestamp.
priorDecisions[].recommendedActionstring | nullSet only on a recommend row: the action (approve or correct) the recommender proposed. Null on every other row.
priorDecisions[].recommendationIdstring | nullCredit link: the recommend row this decision confirmed or overruled, if the decider acted on one. Null when no recommendation preceded the decision.
priorDecisions[].recommendedByNamestring | nullName of the reviewer who made the linked recommendation, denormalized from recommendationId. Null when recommendationId is null.
priorDecisions[].decidedByEmailstring | nullEmail of the deciding user, joined live from the user record. Null for machine actors, API-key decisions, and deleted users.
priorDecisions[].recommendedByEmailstring | nullEmail of the reviewer who made the linked recommendation. Null when recommendationId is null or that user record no longer exists.

Response

{
  "item": {
    "pipeline_document_id": "pd_uuid_1",
    "field_key": "total_amount",
    "field_display_name": "Total Amount",
    "status": "blocked",
    "trigger": "gate",
    "reason": "failed_check",
    "current_value": "12,500.00",
    "confidence": 0.62
  },
  "field": { "field_name": "total_amount", "field_type": "number", "display_name": "Total Amount" },
  "cellHistory": [
    { "cellVersion": 1, "source": "llm_extraction", "value": "12,500.00", "sourceText": "Total due: 12,500.00" }
  ],
  "matchedSpan": { "text": "12,500.00", "approximate": false },
  "candidateSpans": null,
  "candidateSimilarity": null,
  "verdicts": [
    {
      "validatorType": "evidence",
      "verdict": "fail",
      "confidence": 0.62,
      "reasoning": "Amount does not reconcile with the line-item subtotal.",
      "stageName": "Amount reconciliation",
      "createdAt": "2024-09-14T11:02:33.000Z"
    }
  ],
  "priorDecisions": []
}

Errors

Error responses

400validation_errorInvalid document ID format. Must be a UUID.
401unauthorizedMissing or invalid API key.
404not_foundNo pipeline document with this ID exists for your organization.
429rate_limitedToo many requests. Retry after the period indicated in the Retry-After header.

Frequently asked questions

Why is matchedSpan sometimes marked approximate?+
When the writing phase recorded a verbatim source span it is returned directly. When no span was written, the server recovers one by locating the value in the document markdown and flags it `approximate: true`. Absence is stated explicitly when no span can be found.
What are candidate spans and similarity?+
For fields flagged by an n-shot reproducibility check, candidate values from the re-runs are located in the document (`candidateSpans`) and scored for similarity to the current value (`candidateSimilarity`), so a reviewer can pick a value with the supporting span highlighted.
What is in the cellHistory array?+
The chain of cell versions for the field, oldest to newest: how the value moved through transfer, extraction, resolution, and any human edits, each with its source and span where available. It shows a reviewer exactly where the current value came from.

Related

List Field Reviews
Resolve Field Review