Skip to main content

Label Review and Expert Questions

Start the agentic review of the label mappings of a target structure, poll its status, and answer the few open questions that remain for the client experts.

Mapping a workbook depends on how its labels are read. A label such as "Net Incurred" has to land on a metric of the target structure. The label review decides these mappings so that people only answer what a rule and an agent cannot settle. Mappings a rule made are confirmed without a model call. The review agent confirms, fixes or asks about the rest. Asks that share a question wording form one group; only the heaviest groups become open questions, and every other ask takes the agent's first option as a best guess.

A review never overwrites a mapping a person made. When it finishes, every mapped submission under the structure is re-projected, because stored facts do not follow mappings by themselves. The review runs in the background of the API instance that answered. A review already running for the structure is not started twice; its status is returned instead.

POST/v1/submissions/review

Body fields

spec_id*uuidThe target structure whose label mappings are reviewed.
GET/v1/submissions/review

Query parameters

spec_id*uuidThe target structure.

Response fields (data)

runobject | nullThe review run of the instance that answered; null when no review has run on that instance since it started. Holds started_at, done, total, phase (reviewing, remapping, finished or failed), stats once finished, and error when failed.
run.statsobjectreviewed, confirmed, fixed, best_guess, questions, question_groups, undecided.
decisionsobjectCounts of the stored label mappings by state and by who decided: total, proposed, questions, confirmed, fixed, best_guess, answered, approved_by_person.

Response: Review in progress

{
  "data": {
    "run": { "started_at": "2026-10-21T08:02:11.000Z", "done": 140, "total": 212, "phase": "reviewing" },
    "decisions": { "total": 212, "proposed": 72, "questions": 0, "confirmed": 118, "fixed": 22, "best_guess": 0, "answered": 0, "approved_by_person": 4 }
  }
}
run is held in memory by one API instance. A second instance answers run: null for a review that is running elsewhere. The decisions counts come from the database and are the reliable signal: poll until run.phase is finished, or until decisions.proposed stops falling.

Expert Questions

GET /v1/submissions/questions returns one entry per open question group, heaviest first by the values the labels of the group name. Each entry has the question, plain-words options, and the labels the question settles with where each label was seen in the workbook and a few sample values. Show these to the client's expert; the index of the chosen option is the answer.

GET/v1/submissions/questions

Query parameters

spec_id*uuidThe target structure.

Response fields (data[])

groupstringIdentifier to pass to the answer call.
questionstringThe question in plain words.
optionsstring[]Plain-words answers; the index is the option of the answer call.
labels[]arrayThe labels the question settles, heaviest first: label_key, text, where, samples.
POST/v1/submissions/questions/answer

Body fields

spec_id*uuidThe target structure.
group*stringThe group of a question from GET /v1/submissions/questions. Up to 400 characters.
option*integerIndex into the question's options, 0 to 5.

cURL: Answer the first option

curl -X POST "https://api.talonic.com/v1/submissions/questions/answer" \
  -H "Authorization: Bearer $TALONIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"spec_id": "5d1c0a52-0c1e-4b64-9d2e-7a3c4f1e9b10", "group": "net-or-gross-incurred", "option": 0}'

Response: 201 Labels settled

{ "data": { "settled": 7 } }

An answer settles a whole group: each label of the group takes the mapping that the chosen option means for it, recorded as a person's decision, so later reviews never overwrite it. The structure's mapped submissions are re-projected in the background, so the answer shows in their facts shortly after the call returns.

Frequently asked questions

Does the review overwrite mappings my team made?+
No. A mapping a person made, either directly or by answering a question, is never overwritten by a review. The review confirms rule-made mappings, fixes or asks about the rest, and records each decision with its verdict and reason.
Why is only a handful of questions open?+
Asks that share a question wording form one group, and only the heaviest groups by values labelled become open questions. Every other ask takes the first option as a best guess, which the counts report as best_guess. This keeps the expert's work to the questions that move the most figures.
Why does the status show run null?+
The review run lives in the memory of the API instance that started it. A different instance answers null for it. The decisions counts are read from the database and are the same on every instance.

Related

Reinsurance Submission Overview
Processing and Stated Fields
Submission Figures
Checks and Export