Skip to main content

Case Operations

Update the lifecycle status of a case from discovered through confirmed and active to Closed. Transitions are forward-only and can carry resolution notes.

The case status endpoint manages the case lifecycle: PATCH /v1/cases/:key/status moves a case through discovered → confirmed → active → Closed as your team reviews it. Closed is the terminal state; the API payload value for it remains resolved. Any status update can carry optional resolution_notes documenting the decision.

The four states map to a review workflow. discovered is the initial state stamped when the synthesis build first materializes the case. confirmed records that a human verified the grouping is real, active marks the case as being worked, and resolved closes it. Transitions may skip states — moving discovered → resolved directly is valid — but never run backward, and setting the current status again is an allowed no-op.

Notes travel with the update: whenever resolution_notes is present in the body it overwrites the stored notes, at any status. To update the notes without advancing the lifecycle, send the case's current status together with the new notes. Sending an unknown status value — including validated, which is an internal audit stamp written by the platform validation surface, not a lifecycle state — returns a 400.

Closing a case has a side effect worth designing around: the transition into resolved publishes a case.resolved delivery event, which is the natural trigger for case-snapshot deliverables configured in Delivery. The event fires only on an actual transition — re-sending resolved on an already-Closed case is a no-op and does not re-trigger delivery.

The lifecycle is forward-only: a case can advance (e.g. discovered → active) or stay in place, but moving backward returns a 400. Closed (resolved) is terminal. Optional resolution_notes can be attached with any status update.
PATCH/v1/cases/:key/status

Body parameters

status*stringNew lifecycle status for the case: `discovered`, `confirmed`, `active`, or `resolved` (Closed).
resolution_notesstringOptional notes to record with the status update.

Request

curl -X PATCH https://api.talonic.com/v1/cases/5c7fa78c-4d92-4613-9f42-9fe74458d8a9/status \
  -H "Authorization: Bearer $TALONIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "resolved", "resolution_notes": "All invoices reconciled." }'

Response

The response is the updated case row.

Response fields

idstringCase UUID — the stable resource id.
case_keystringContent-derived case key (hex).
statusstringThe new case status.
display_namestring | nullUser-curated display name, if set.
resolution_notesstring | nullResolution notes, if provided.

Response

{
  "id": "5c7fa78c-4d92-4613-9f42-9fe74458d8a9",
  "case_key": "8c1ca050535e3ea3",
  "status": "resolved",
  "display_name": "Acme Corp Q4 Invoices",
  "resolution_notes": "All invoices reconciled."
}

A typical review integration advances the case as work progresses: confirm it when a reviewer accepts the grouping, mark it active when reconciliation starts, and resolve it with notes when the work completes.

Request — advance to active

curl -X PATCH https://api.talonic.com/v1/cases/5c7fa78c-4d92-4613-9f42-9fe74458d8a9/status \
  -H "Authorization: Bearer $TALONIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "active" }'

Errors

Error responses

400bad_requestInvalid case key format, unknown status value, or a backward lifecycle transition.
401unauthorizedMissing or invalid API key.
404not_foundCase not found.
429rate_limitedToo many requests. Retry after the period indicated in the Retry-After header.

Frequently asked questions

What are the valid case statuses?+
Four lifecycle statuses: discovered (initial), confirmed (verified as real), active (being worked), and Closed (complete; sent as resolved in the API). The typical flow is discovered -> confirmed -> active -> resolved.
Can I reopen a Closed case?+
No. The lifecycle is forward-only and Closed (the resolved status value) is terminal, so moving a case backward returns a 400 error. Setting the same status again is allowed and is a no-op.
Can I add resolution notes without changing the status?+
Notes are applied whenever the resolution_notes field is present in the body, so send the case's current status together with the new notes to update them in place.
Does closing a case trigger anything downstream?+
Yes. The transition into resolved publishes a case.resolved delivery event, which delivery bindings can use to ship a case snapshot. It fires only on the actual transition; re-sending resolved on an already-Closed case does not re-trigger it.

Related

Get Case
Case Merge & Split
List Cases