Skip to main content

Review Action

Approve or reject a review record with POST /v1/review/:id/action. The optional reason is stored as review_comment and the decision timestamp is recorded.

POST /v1/review/:id/action records a Record Review decision — a record-level human judgment — on a review item. approve marks the record accepted; reject marks it refused. These are the only two accepted actions; any other value fails validation with a 400 naming the allowed values. Include an optional reason for audit purposes; it is stored on the record as review_comment and returned by [GET /v1/review/:id](get-review-item).

The action writes three things: status becomes approved or rejected, reviewed_at is stamped with the decision time, and review_comment is set to your reason (or cleared to null when omitted). reviewed_by stays null for API decisions — an API key carries no user identity — so decisions made here are distinguishable from platform-UI decisions, which record the acting user. If your compliance process needs an actor trail for API decisions, encode it in reason.

Repeat calls are allowed and overwrite: actioning an already-actioned record replaces its status, timestamp, and comment, so you can flip an accidental approve to reject by calling again. What you cannot do is return a record to pending — there is no "undecide" action. Each call is also independent per record; for clearing many items with one decision, [POST /v1/review/batch](review-batch) is the bulk form of the same write.

The decision is a record-keeping write: it does not delete extracted data, trigger re-extraction, or by itself push anything to a destination. Export staging after approval is driven by the schema's configured approval behavior in the platform review flow, and delivery signals for approved results are emitted by the structuring approvals surface — see [Approve / Reject a Result](approve-reject-result) for the gate-driven path that feeds delivery bindings. Use this endpoint when your source of truth for accept/reject lives outside Talonic and you sync verdicts back.

A decision can be overwritten by a later action call — approve then reject is legal and replaces the earlier verdict — but a record can never be returned to pending through the API. Treat the queue as append-only from the perspective of your pending-count metrics.
POST/v1/review/:id/action

Path parameters

id*uuidThe review record id.

Body parameters

action*stringAction to take: `approve` or `reject`. No other values are accepted.
reasonstringOptional comment explaining the decision. Stored on the record as `review_comment`; omitting it clears any previous comment.

curl

curl -s -X POST https://api.talonic.com/v1/review/a1b2c3d4-e5f6-7890-abcd-ef1234567890/action \
  -H "Authorization: Bearer tlnc_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"action": "approve", "reason": "Verified against the PO in NetSuite"}'

Response

Response fields

idstringReview record UUID.
run_idstringUUID of the run (Job or Pipeline run).
document_idstringUUID of the associated document.
schema_idstring | nullUUID of the schema used.
statusstringUpdated record status: approved or rejected.
overall_confidencenumber | nullAggregate confidence score (0–1).
assigned_tostring | nullUUID of the assigned reviewer.
reviewed_bystring | nullNull for API decisions; set only when the action was taken by a user in the platform.
reviewed_atstring | nullISO 8601 timestamp of this review action.
created_atstringISO 8601 creation timestamp.
linksobjectRelated resource URLs (self, action).

Response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "run_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "document_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "schema_id": "d4e5f6a7-b8c9-0123-defa-234567890123",
  "status": "approved",
  "overall_confidence": 0.72,
  "assigned_to": null,
  "reviewed_by": null,
  "reviewed_at": "2026-08-12T10:30:00.000Z",
  "created_at": "2026-08-12T09:00:00.000Z",
  "links": {
    "self": "/v1/review/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "action": "/v1/review/a1b2c3d4-e5f6-7890-abcd-ef1234567890/action"
  }
}

Errors

Error responses

400validation_errorThe action value is not approve/reject, or the id is not a well-formed UUID. The message names the allowed values.
401unauthorizedMissing or invalid API key.
403insufficient_scopeThe key lacks the write scope.
404not_foundReview record not found, not in your workspace, or its source document is hidden from your key. Hidden records cannot be actioned.
429rate_limitedToo many requests. Retry after the period indicated in the Retry-After header.

Error (400 — invalid action)

{
  "statusCode": 400,
  "code": "VALIDATION_ERROR",
  "error": "Bad Request",
  "message": "action must be one of the following values: approve, reject",
  "retryable": false,
  "request_id": "req_cc64b4fba5524acf",
  "path": "/v1/review/a1b2c3d4-e5f6-7890-abcd-ef1234567890/action"
}

A robust sync loop treats the response status as the confirmation of the write and re-reads nothing. Pair this with GET /v1/review/stats to verify the pending count dropped as expected, and with [POST /v1/review/batch](review-batch) when the same verdict applies to many records at once.

Frequently asked questions

What happens after approval?+
The record's status, reviewed_at, and review_comment are updated — nothing else fires from this endpoint. Downstream export staging and delivery signals for approved results are governed by the schema's approval configuration and the structuring approvals surface, so approving here is a verdict of record, not a delivery trigger.
Is the reason field stored for audit purposes?+
Yes. The reason is stored as review_comment on the record and is visible in GET /v1/review/:id. Note that omitting reason on a repeat action clears the previous comment, and API decisions leave reviewed_by null — include your actor identity inside reason if you need it.
Can I change a decision after making it?+
Yes — calling the endpoint again overwrites the previous decision, timestamp, and comment, so approve-then-reject is a legal correction. You cannot, however, move a record back to pending; there is no undecide operation.
Is reason required when rejecting?+
No — via the API, reason is optional for both actions. The platform UI requires a comment for rejections, so API-rejected records without a reason will show an empty comment where UI users expect an explanation; supplying one keeps the audit trail consistent.
Can I approve many review items at once?+
Yes. Use POST /v1/review/batch with an array of record IDs and a single action. Each item is processed independently, so a missing ID does not abort the rest of the batch.

Related

Get Review Item Detail
Batch Review Actions
Review Queue Statistics
Approve / Reject a Structuring Result