> Toden documentation. For the full index fetch /llms.txt. Every page is available as Markdown by appending .md to its URL. Identity verification uses /api/kyc, Risk Intelligence uses /api/v1; they are separate contracts with different error shapes. Never invent an endpoint, field or enum value: read the API reference page for the operation first.

# Alerts & Investigations

> Integrate alert and investigation lifecycle events without exposing analyst evidence.

Alerts group risk occurrences that need attention. Investigations are the owned
human-review records opened from one or more alerts. The product and API use the
name Investigation. Webhook event names retain the established `case.*` prefix
so existing receivers do not break.

## Alert events

| Event           | When it fires                                        | Recommended handling                   |
| --------------- | ---------------------------------------------------- | -------------------------------------- |
| `alert.created` | A new actionable alert opens.                        | Create a linked review item.           |
| `alert.updated` | Decision, score, occurrence count or status changes. | Update the existing item by `alertId`. |

```json
{
  "version": "2026-08-11",
  "id": "evt_alert_01",
  "type": "alert.created",
  "createdAt": "2026-08-15T17:32:00.000Z",
  "deliveryId": "del_alert_01",
  "data": { "alertId": "alt_01", "entityId": "ent_01", "status": "OPEN", "decision": "REVIEW", "riskScore": 86, "occurrences": 1, "resolution": null }
}
```

```json
[
  { "type": "alert.updated", "data": { "alertId": "alt_01", "entityId": "ent_01", "status": "IN_REVIEW", "decision": "REVIEW", "riskScore": 89, "occurrences": 3, "resolution": null } },
  { "type": "alert.updated", "data": { "alertId": "alt_01", "entityId": "ent_01", "status": "RESOLVED", "decision": "ALLOW", "riskScore": 22, "occurrences": 3, "resolution": "FALSE_POSITIVE" } }
]
```

## Investigation events

| Event                 | When it fires                                 |
| --------------------- | --------------------------------------------- |
| `case.created`        | An investigation opens from related evidence. |
| `case.assigned`       | An owner is assigned.                         |
| `case.review_started` | Human review begins.                          |
| `case.escalated`      | Priority or review tier is escalated.         |
| `case.resolved`       | An analyst records a disposition.             |
| `case.closed`         | Operational work closes.                      |
| `case.reopened`       | A closed investigation returns to review.     |
| `case.sla_at_risk`    | The due time is approaching.                  |
| `case.overdue`        | The due time has passed.                      |

Every event uses the standard webhook envelope. Route it by `data.caseId`, then
retrieve `/api/v1/investigations/{caseId}` when your workflow needs the complete
current Investigation. `caseId` is retained inside webhook payloads as a stable
compatibility field.

```json
{
  "version": "2026-08-11",
  "id": "evt_investigation_01",
  "type": "case.assigned",
  "createdAt": "2026-08-15T17:35:00.000Z",
  "deliveryId": "del_investigation_01",
  "data": {
    "id": "evt_case_assigned_inv_01_current",
    "caseId": "inv_01",
    "entityId": "ent_01",
    "subject": { "type": "entity", "id": "ent_01" },
    "assigneeId": "usr_reviewer_01",
    "occurredAt": "2026-08-15T17:35:00.000Z"
  }
}
```

## Field reference

| Field                           | Type            |         Nullable | Meaning                                              |
| ------------------------------- | --------------- | ---------------: | ---------------------------------------------------- |
| `alertId`, `caseId`, `entityId` | string          | No where present | Stable alert, investigation and subject IDs.         |
| `status`                        | string          |               No | Current lifecycle status shown in the examples.      |
| `decision`                      | string          |              Yes | Alert decision such as `ALLOW`, `REVIEW` or `BLOCK`. |
| `riskScore`                     | number          |              Yes | Alert risk score.                                    |
| `occurrences`, `alertCount`     | integer         |               No | Grouped evidence or linked alert counts.             |
| `resolution`, `disposition`     | string          |              Yes | Recorded alert resolution or investigation outcome.  |
| `priority`                      | string          |               No | For example `LOW`, `MEDIUM`, `HIGH` or `CRITICAL`.   |
| `assigneeId`                    | string          |              Yes | Assigned user ID.                                    |
| `dueAt`                         | ISO 8601 string |              Yes | SLA deadline.                                        |

Private notes, attachments, analyst evidence and SAR filing state are not included. There are no customer-facing `sar.*` events in the current catalogue.