> 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.

# Investigations and reporting

> Triage alerts, investigate evidence, and file suspicious-activity reports.

This is where flagged activity becomes an owned, evidence-backed decision. [Events](/risk-intelligence/monitoring/events) that score high raise **alerts**; your team opens an **investigation**, assigns an owner, reviews the evidence and records an outcome. Where activity is reportable, the investigation can produce a **SAR** or **STR**. Every action is audited server-side.

## Alert or investigation?

An **alert** is a signal that needs triage. It shows what happened, why Toden raised it and the rules or screening evidence involved.

An **investigation** is the casework record. Use it when the alert needs an accountable owner, more evidence, remediation, escalation or a formal outcome. This separation keeps the alert queue fast without losing the deeper audit trail required for material decisions.

## Alerts

An **alert** is opened automatically when an event scores at or above your [review threshold](/risk-intelligence/monitoring/rules#decision-thresholds). Review alerts under **Compliance → Alerts** (`alerts:read`).

| Field          | Notes                                                                                            |
| -------------- | ------------------------------------------------------------------------------------------------ |
| **Decision**   | The event's decision: typically `REVIEW` or `BLOCK`.                                             |
| **Risk score** | The score that triggered it (0–100).                                                             |
| **Status**     | `OPEN`, `RESOLVED`, or `DISMISSED`.                                                              |
| **Reasons**    | The rules that contributed, each with a score and a detail string (e.g. `amount 48000 > 10000`). |

The list shows each alert's entity, decision, risk score, status, and how many investigations it belongs to.

> **Note**
>
> Alerts appear here when monitoring flags an event for review or block.

## Opening and assigning an investigation

Open an alert to review its decision evidence. If more work is needed, choose an investigator from your organisation and select **Open investigation**. You can also select multiple alerts from one entity and open a grouped investigation. All linked alerts must belong to the same entity so the investigation remains scoped to one customer.

## Investigation workspace

The investigation workspace puts the decision controls first:

1. **State** shows where the investigation is in its lifecycle.
2. **Why** summarises the strongest reasons that raised the linked alerts.
3. **Evidence** keeps rule explanations, linked records and uploaded attachments together.
4. **Owner** assigns accountability to a member of your organisation.
5. **Next action** starts review, escalates, records an outcome, closes or reopens the investigation.

| Attribute    | Values                                                                                                 |
| ------------ | ------------------------------------------------------------------------------------------------------ |
| **Status**   | `OPEN` → `IN_REVIEW` → `ESCALATED` or `RESOLVED` → `CLOSED`, with reopening when new evidence appears. |
| **Outcome**  | `CLEARED`, `CONFIRMED`, `ESCALATED` or `INCONCLUSIVE`, supported by an analyst rationale.              |
| **Assignee** | A team member, or unassigned.                                                                          |
| **Alerts**   | The grouped alerts; add more of the entity's alerts at any time.                                       |

Resolving and closing are separate. **Resolve** records the evidence-backed outcome; **close** completes the operational work. The rationale, actor, timestamps and later reopening remain in the immutable timeline.

> **Note**
>
> Open an investigation from the Alerts view when the evidence needs an owner or outcome.

## Server-side SDK

The public SDK calls this resource `investigations`:

```js
const investigation = await toden.investigations.retrieve(investigationId);
const evidence = await toden.investigations.evidence.list(investigationId);
const timeline = await toden.investigations.timeline(investigationId);
```

The canonical HTTP paths are `/api/v1/investigations`. The deprecated
`/api/v1/cases` paths and `toden.cases` SDK resource remain available for
existing integrations; new integrations should use
`toden.investigations` and the primary `Investigation` SDK types.

## SARs & STRs

When an investigation is reportable, draft a regulatory filing from it. The
existing permission key for these actions is `cases:manage`.

| Attribute       | Values                                                                         |
| --------------- | ------------------------------------------------------------------------------ |
| **Report type** | `SAR` (Suspicious Activity Report) or `STR` (Suspicious Transaction Report).   |
| **Status**      | `DRAFT` → `FILED`, or `CANCELLED`.                                             |
| **Reference**   | Your external filing reference (e.g. the regulator's number), set when filing. |

The lifecycle:

1. **Draft**: choose `SAR` or `STR` and a reason. The report is generated server-side in **goAML** format.
2. **Review & export**: inspect the goAML payload on the SAR detail view and **export it as XML** for submission to your FIU/regulator.
3. **File**: record the external reference and file path; the SAR moves to `FILED`.
4. **Cancel**: a `DRAFT` can be cancelled if it's no longer needed.

## Audit

Every investigation and SAR write (open, assign, add evidence, transition, resolve, close, reopen, draft, file, cancel) is recorded in your organisation's audit log (**Dashboard → Audit logs**), with the actor and timestamp.

## Related

* [Event monitoring](/risk-intelligence/monitoring/events): how alerts get raised.
* [Monitoring rules](/risk-intelligence/monitoring/rules): the thresholds that decide `REVIEW` vs `BLOCK`.
* [Compliance overview](/risk-intelligence/screening/compliance): the end-to-end lifecycle.