Human review API

Find waiting document targets, approve translations, and submit edits as an authorized reviewer.

A review covers one document in one target language. It becomes available when the configured human-review stage has eligible units ready for a decision. Configure decision-pool routing before starting the job.

Review requests require access to the organization and permission to review the engine's translations. Decision requests also require a person: authenticate with a reviewer's session access token or personal API key. An organization service key cannot submit human decisions.

Find reviews #

http
GET /v2/organizations/:orgId/localization/reviews?statuses=open&limit=50

The response is { "data": [...], "meta": { "nextCursor": "..." } }. Follow cursors until nextCursor is null.

Query fieldValues and default
statusesopen, completed, timedOut, cancelled; defaults to open. Repeat the parameter for several values.
orderoldest (default) or newest.
limit1–100; defaults to 50.
cursorOpaque cursor from the previous page. Keep filters and order unchanged.

Requesting decided statuses requires permission to manage organization reviews. Each summary identifies documentId, locale, jobId, engineId, engineName, documentKey, sourceLocale, provider, vendorStartedAt, status, readyAt, expiresAt, closedAt, totalUnits, and pendingUnits.

Read one review #

http
GET /v2/localization/documents/:documentId/targets/:locale/review

The response contains the same target and engine context, plus units, takeover information, and any recorded external order. takeover is null until a person takes over; externalOrder can be absent or null when no order was recorded. Each unit includes unitId, key, position, source, value, reference, quality, eligibility, result, decision, reviewerId, and decidedAt.

Use sourceText to display the source and valueText to initialize an edit. After a decision, display settledText: it contains the accepted edit or other settled result, while valueText keeps the translation from before review. Until a result is available, settledText equals valueText.

quality is the quality gate's output for the unit, { "findings": [...] } as the pipeline reference describes, or null when the gate did not check it. eligibility is required, qualityPassed, localeNotCovered, or reused. Only undecided, required units need a human decision. Other units provide context. A non-null settled result can represent a timeout or fallback; inspect decision to establish whether a person approved or edited the unit.

value is the translation at the review boundary. It can be a string or an array of structured text, variable, and markup segments. Preserve placeholder identities and nesting when editing.

Approve or edit #

Approve all remaining required units without changes:

http
POST /v2/localization/documents/:documentId/targets/:locale/review/approve-all

This request has no body. To make explicit decisions, post to /decisions with a nonempty array and unique unit IDs:

json
{
  "decisions": [
    { "unitId": "YOUR_FIRST_UNIT_ID", "decision": { "_tag": "Approved" } },
    { "unitId": "YOUR_SECOND_UNIT_ID", "decision": { "_tag": "Edited", "value": "Guardar cambios" } }
  ]
}

Use IDs from the retrieved review. To edit a structured value, start with its valueText and send the edited text as Edited.value. For example, Hello {name}<C1>world</C1><C2/> can become Bonjour {name}<C1>tout le monde</C1><C2/>. Keep the placeholder tokens, their counts, and markup nesting; sibling placeholders may move. Literal delimiters in structured text are entity-escaped. The API parses this text back into structured segments. You can also submit a structured segment array directly. Plain-string ICU edits must preserve the translation's localized cases and counts.

A successful response returns the refreshed review. Internal reviewers can submit a subset of required units. Decisions are final. While the target still accepts decisions, an identical submission by the same reviewer reuses the saved decision; a conflicting decision is rejected. The whole submitted set is validated before any of its decisions are written.

LocalizationReviewInvalid (422) identifies invalid submissions, including changed placeholders. LocalizationReviewClosed (409) means the review or a unit can no longer accept that decision. A retry after target completion can return 409 even if the first submission succeeded. After a lost response, retrieve the review and compare its saved decisions and reviewer IDs before deciding what remains to do.

External review and takeover #

Read GET /v2/localization/documents/:documentId/targets/:locale/review/vendor-status for the external provider's current state: unstarted, inProgress, completed, or unknown.

Taking over an external review requires decisions for every remaining required unit in one submission. This closes the external review and attempts to cancel the provider's order. Work already started may still be charged. Vendor status can change between reading and submitting; it does not guarantee free cancellation.

Wait for the final file #

The review deadline is expiresAt, calculated from readyAt. Polling and retries do not extend it. At timeout, undecided units retain their preceding translations with warnings; accepted decisions remain in place.

After review, later pipeline stages may change the text. Retrieve the job and download its completed target to obtain the final file. A completed review is not itself the download result.