Skip to main content

Review Queue

The Review Queue is the human-in-the-loop layer for pipelines. When a blocking gate fails a field, or a field marked for review survives the run undecided, it is held for a person. The queue is a query over field states across every run, so it never drifts from the data. Each item carries its current value, confidence, and the stored verdicts that flagged it, and the value never reaches delivered output until someone decides it.

In the app, Products is the review hub. The sidebar has no separate Review entry: the Products list carries a Status column (Needs review or Complete) and a dot on the Products nav item when any product has fields pending review. Each product opens in Review Mode, the full-screen workbench described in Review Mode, and the Decision log tab on the Products page lists every decision across products. The cross-pipeline queue list stays reachable at /review/queue by direct URL for teams that prefer one long list.

A reviewer resolves an item one of three ways. Approve accepts the current value. Correct replaces it with a fixed value (for enum fields, a picker offers every allowed value, including ones no source produced). Override accepts a value with a required reason. Every action writes a promotion cell (a new canonical version with full confidence and a human-review source) and appends a row to an append-only decision log. A decision can be revised later with Edit: the revision writes a fresh decision row and promotion cell and keeps the earlier ones, so the history shows both.

The queue is built for volume. Items are classified by reason (missing value, disagreement, failed check, low confidence, likely fine), so a reviewer can triage the worst first. Identical values across many documents cluster together for one-click bulk approval, and a bulk-resolve call can clear up to 500 items at once, each running the same single-field decision path so one failure never aborts the batch. Items can be claimed for ownership, though the decision log, not the claim, remains the authority on who decided. A workspace Admin can also take a field out of review for every reviewer with a deprioritization rule.

Who can decide: roles, complex fields, and recommendations

Deciding requires the Member role or above (shown in the app as Contract Management); a Viewer sees the queue but cannot act. A Spec field tagged complex is locked further: only a Senior Member (Senior Contract Management) or an Admin can approve, correct, override, or claim it. The server enforces the lock and answers anyone else with a 403. An API key carries no client role, so a complex field cannot be decided through the public API either; it waits for a senior reviewer in the app.

A Member who reaches a complex-locked field is not stuck. Instead of the decision form they see Recommend {action}: they pick the value and action they would take and leave it as a recommendation. The item then shows a Recommended chip and "Recommended by" the reviewer, and the senior reviewer who opens it can choose Use recommendation, which pre-fills the decision and its justification. When the senior confirms, the decision row links to the recommendation, so the person who did the groundwork is credited in the log.

The decision log identifies reviewers by email. The Who column shows the decider's email (falling back to the stored name), and GET /v1/field-reviews/decisions returns decidedByEmail and recommendedByEmail alongside the names. The CSV export keeps its existing columns.

Review Mode: the workbench

Review Mode is the full-screen workbench a reviewer works in: the source document in the center and the decision rail on the right with the value, verdicts, candidates, and the decision form. The rail is resizable between 320 and 720 pixels and remembers its width. A toggle reveals the read-only reference comparison rails, showing Schema fields beside the matched Reference data with the matcher verdict. Scanned PDFs open immediately behind a non-blocking "Locating source…" pill, and the next items are prefetched so advancing is instant. Compare, pinned fields, document search, and non-PDF originals are covered in Review Mode.

Working the queue via API

List the queue and filter by pipeline (pipeline_id), trigger (gate for a blocking-gate block, declarative for a requires-review hold), and item status. Each item identifies the document and field key you act on. The richer reason and assignee filters drive the in-app queue UI.

List the review queue
curl "https://api.talonic.com/v1/field-reviews?trigger=gate" \
  -H "Authorization: Bearer $TALONIC_API_KEY"

Resolve an item by posting a decision for its document and field. Approve accepts the value; correct supplies a replacement; override supplies a value and a reason.

Resolve a field in review
curl -X POST https://api.talonic.com/v1/field-reviews/doc_7f3a1b2c/total_amount/resolve \
  -H "Authorization: Bearer $TALONIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "action": "correct", "corrected_value": "1480.00" }'

Pull the decision log for an audit view, or export it as CSV for handover. With no filter the log is workspace-wide; filter by pipeline or data product to scope it to one deliverable.

Export the decision log
curl "https://api.talonic.com/v1/field-reviews/decisions/export?pipeline_id=pl_x8k2m9" \
  -H "Authorization: Bearer $TALONIC_API_KEY" -o decisions.csv
A field marked requires_review never reaches completed without a decision row. The promotion cell is written before the field state flips, so the canonical value a data product reads can never lead the workflow state. The queue itself is a query over field states, so there is no separate queue table to drift out of sync.

Frequently asked questions

Where do I review held fields in the app?+
On Products. The Products list shows a Status column (Needs review or Complete), the sidebar marks Products with a dot when fields are waiting, and each product opens in Review Mode. The Decision log tab lists every decision. The cross-pipeline list is still reachable at /review/queue by direct URL, but it is no longer in the sidebar.
Who can decide a field tagged complex?+
Only a Senior Member (Senior Contract Management) or an Admin. Anyone else, including any API key, receives a 403 when trying to decide or claim it. A Member can leave a recommendation instead, which the senior reviewer can adopt with Use recommendation; the confirmed decision credits the recommender.
Can a review decision be changed later?+
Yes. Use Edit on a validated field to revise the decision. The revision appends a new decision row and promotion cell and keeps the earlier ones, so the log shows both the original decision and the change.
What lands in the review queue?+
Fields blocked by a blocking validation gate, and fields marked requires_review that survive a run without a decision. The queue is central and cross-pipeline: it aggregates every awaiting field across all your runs into one list, each item carrying its current value, confidence, and the verdicts that flagged it.
What are the ways to resolve a review item?+
Approve (accept the current value), correct (replace it with a fixed value), or override (accept a value with a required reason). Each writes a promotion cell as a new canonical version with full confidence and a human-review source, and appends a row to the append-only decision log.
How do I handle review at volume?+
Items are classified by reason for triage, and identical values cluster for one-click bulk approval. POST /v1/field-reviews/bulk-resolve clears up to 500 items in one call, each running the same single-field decision path, so one failure never aborts the batch. Items can also be claimed for ownership.
Is there an audit trail for review decisions?+
Yes. Every decision appends to an append-only log recording who decided, when, the prior value, the action, and the final value. Pull it as JSON or export CSV via /v1/field-reviews/decisions, filtered by pipeline or data product or workspace-wide. The log exports with the data product for customer handover.

Related

Validation Checkpoints
Running a Pipeline
Review Gates
Review Mode
Field Review
Field Deprioritization