Field Review

Field Review is Talonic's cell-level human decision surface: fields that fail a blocking validation checkpoint, or that a Spec marks for review, wait here for a reviewer to approve, correct, or override them. The hub for this work is Products in the sidebar. The Products list carries a review-centric Status column (Needs review or Complete) for every data product, an amber dot on the Products nav entry signals that fields are pending somewhere in the workspace, and a Decision log tab records every action taken. Opening a product and clicking Review Mode walks its rows one by one with the source document beside a decision rail.

The former Review section is no longer in the sidebar. The legacy queue pages at /review and /review/queue stay reachable by direct URL, but day-to-day review starts from Products, because a reviewer usually thinks in terms of "the data product I am delivering" rather than a flat list of held cells. Each held field still shows its source document, the schema field, its provenance back to the text, and the checkpoint or trigger that routed it, so a reviewer always sees why the value stopped.

On a held field a reviewer can approve the extracted value, correct it to a new value, or override the checkpoint decision with a reason. Every action writes a promotion cell (a new value with a human-review source) and appends a row to the append-only decision log. Decisions are revisable: Review Mode's validated footer offers Edit, which re-decides a completed field and writes a fresh decision-log row while keeping the earlier ones, so the history of a value is never overwritten. Enum fields offer every allowed value in the picker, including codes no source produced, so a reviewer can pick the right code instead of typing it.

Who can decide: roles and the Senior Member gate

Deciding requires Member or above (shown in the app as Contract Management). Viewers can open Products and Review Mode and read the queue, but cannot act on it. A Spec author can tag a schema field complex (matched case-insensitively); a complex field can only be approved, corrected, overridden, claimed, or released by a Senior Member (shown as Senior Contract Management) or a workspace Admin. The gate is enforced on the server: a caller without the grant receives 403 INSUFFICIENT_PERMISSIONS, and bulk resolve skips complex items for that caller while resolving the rest. The UI mirrors the lock with a "Senior+" chip so nobody discovers it by failing.

A Member who cannot decide a complex field is not stuck. The rail offers Recommend {action} instead of the decision buttons: the reviewer picks approve, correct, or override, supplies the value and reasoning, and leaves it as a recommendation without touching the field's state. The item then shows a Recommended chip and "Recommended by {name}". When a Senior Member opens it, Use recommendation seeds the decision with the recommended value and justification; confirming it resolves the field and credits the recommender in the decision log. The internal queue filter recommendation=pending lists items that carry an open recommendation, which makes a natural daily worklist for senior reviewers.

API keys carry no workspace role, so a public API caller can never act on a complex field: those items are rejected by POST /v1/field-reviews/:docId/:fieldKey/resolve and skipped by bulk resolve. Route complex fields to human Senior Members, and use the API for the high-volume, low-risk fields where scripted resolution pays off. An Admin can also take a field out of review altogether with a standing rule, covered in Field Deprioritization.

The decision log

The Decision log tab on Products lists every decision: the field, the document, the prior and final values, the action, the reason, and Who. The Who column shows the reviewer's email address, falling back to the stored display name (kept on hover) when no email is available, and a machine-actor chip for system decisions such as capacity demotion or deprioritization. Recommendations appear with the recommender's email too. The public API carries the same information additively: entries from GET /v1/field-reviews/decisions include decidedByEmail and recommendedByEmail; decidedByEmail is null for machine actors, API-key decisions, and deleted users. The CSV export at /v1/field-reviews/decisions/export keeps its existing column shape.

• Products is the review hub: Status column, Decision log tab, and per-product Review Mode
• An amber dot on the Products nav entry signals fields pending review anywhere in the workspace
• /review and /review/queue remain reachable by direct URL only; the Review nav section is retired
• Per field, a reviewer can approve, correct, or override; decisions can be revised with Edit
• Member or above decides; Viewers read only
• complex-tagged fields need a Senior Member or Admin; others leave a recommendation
• The decision log identifies reviewers by email and credits recommenders on confirm
• The public API is /v1/field-reviews: resolve via POST /v1/field-reviews/:docId/:fieldKey/resolve or /v1/field-reviews/bulk-resolve

The public API exposes the same queue under /v1/field-reviews. List the held fields with GET /v1/field-reviews (filter by pipeline_id, trigger, or status), then resolve each one with POST /v1/field-reviews/:docId/:fieldKey/resolve and an action of approve, correct, or override (correct takes a corrected_value). GET /v1/field-reviews/summary returns queue counts, and the decision log is readable at /v1/field-reviews/decisions. This lets you script bulk resolution or connect the queue to an external review tool while the decision log captures every action exactly as it does for in-app decisions.

curl -s "https://api.talonic.com/v1/field-reviews?status=pending&limit=10" \
  -H "Authorization: Bearer $TALONIC_API_KEY"

# Response (one item per held document field):
# {
#   "items": [
#     {
#       "pipeline_document_id": "9c2e4a1b-7d3f-4e58-b6a2-0f1c8d9e7a54",
#       "field_key": "total_amount",
#       "document_name": "Invoice_Beta_Corp.pdf",
#       "value": "1240.0",
#       "trigger": "gate",
#       "status": "pending"
#     }
#   ],
#   "total": 24
# }

# Items are addressed by document ID + field key.

# Approve the extracted value:
curl -X POST https://api.talonic.com/v1/field-reviews/9c2e4a1b-7d3f-4e58-b6a2-0f1c8d9e7a54/total_amount/resolve \
  -H "Authorization: Bearer $TALONIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "action": "approve" }'

# Correct to a new value:
curl -X POST https://api.talonic.com/v1/field-reviews/9c2e4a1b-7d3f-4e58-b6a2-0f1c8d9e7a54/total_amount/resolve \
  -H "Authorization: Bearer $TALONIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "action": "correct", "corrected_value": "1240.00", "reason": "OCR dropped trailing zero" }'

# Resolve many items at once (up to 500). Complex fields are
# skipped for API keys, which carry no workspace role:
curl -X POST https://api.talonic.com/v1/field-reviews/bulk-resolve \
  -H "Authorization: Bearer $TALONIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "approve",
    "items": [
      {
        "pipeline_document_id": "9c2e4a1b-7d3f-4e58-b6a2-0f1c8d9e7a54",
        "field_key": "total_amount"
      }
    ]
  }'

{
  "fieldKey": "total_amount",
  "action": "correct",
  "priorValue": "1240.0",
  "finalValue": "1240.00",
  "reason": "OCR dropped trailing zero",
  "decidedByName": "A. Reviewer",
  "decidedByEmail": "reviewer@example.com",
  "decidedAt": "2026-10-01T09:14:22Z",
  "recommendedAction": null,
  "recommendedByName": null,
  "recommendedByEmail": null
}

Two endpoints help a reviewer work the queue efficiently at scale. GET /v1/field-reviews/triage returns the queue's shape rather than its items: a breakdown by reason, field, document, assignee, and tag, each group carrying a per-group reason mix, so a dashboard can show which fields are mostly safe to bulk-approve and which need a careful look. GET /v1/field-reviews/value-clusters groups held items by their current value: when a field is held across many documents with the same value, those items form one cluster you can review once and approve together with POST /v1/field-reviews/bulk-resolve.