> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zenoo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Case Lifecycle

> Understand case types, status transitions, SLA calculation, and closure requirements in the Zenoo CLM platform.

# Case Lifecycle

Cases are the primary unit of work in the Zenoo AML platform. Each case represents an investigation into an entity (company or person) and aggregates alerts, risk assessments, checks, and reviewer workflows.

## Case types

| Type         | Purpose                                          | Typical SLA |
| ------------ | ------------------------------------------------ | ----------- |
| `Onboarding` | Initial customer due diligence during onboarding | 14 days     |
| `Review`     | Periodic re-review of existing customers         | 30 days     |
| `Perpetual`  | Ongoing monitoring and continuous screening      | Rolling     |

<Tip>
  Use `Onboarding` for new customers, `Review` for scheduled periodic re-assessments, and `Perpetual` for continuous monitoring triggered by screening alerts.
</Tip>

## Status transitions

Cases follow a defined state machine. Only valid transitions are permitted.

```mermaid theme={null}
stateDiagram-v2
    [*] --> New
    New --> In_Progress : Analyst begins work
    In_Progress --> Client_Input : Awaiting client response
    In_Progress --> Internal_Review : Escalated or sent for review
    In_Progress --> Closed : All alerts resolved
    Client_Input --> In_Progress : Client responds
    Client_Input --> Internal_Review : Escalate
    Client_Input --> Closed : Close after response
    Internal_Review --> In_Progress : Return to analyst
    Internal_Review --> Closed : Reviewer approves closure
    New --> Escalated : Auto-escalation (SLA breach)
    In_Progress --> Escalated : Manual escalation
```

| Status            | Description                                                |
| ----------------- | ---------------------------------------------------------- |
| `New`             | Case created, not yet assigned or started                  |
| `In Progress`     | Analyst actively working on the case                       |
| `In Review`       | Submitted for peer or senior review                        |
| `Internal Review` | Under internal compliance review or escalation             |
| `Client Input`    | Waiting for the client to provide documents or information |
| `Closed`          | Investigation complete, all alerts resolved                |
| `Escalated`       | Escalated to a manager due to complexity or SLA breach     |

### Invalid transitions

The API returns a `422 Unprocessable Entity` error for invalid transitions:

```json theme={null}
{
  "error": "invalid_transition",
  "message": "Cannot transition from 'Closed' to 'In Progress'. Closed is a terminal state.",
  "current_status": "Closed",
  "requested_status": "In Progress"
}
```

## SLA calculation

SLA due dates are automatically calculated from custom metadata based on case type and priority:

| Type / Priority       | Due Days | Warning Days | Auto-Escalate |
| --------------------- | -------- | ------------ | ------------- |
| Onboarding / Critical | 3        | 1            | Yes           |
| Onboarding / High     | 7        | 2            | Yes           |
| Onboarding / Medium   | 14       | 3            | No            |
| Onboarding / Low      | 21       | 5            | No            |
| Review / Critical     | 5        | 1            | Yes           |
| Review / High         | 14       | 3            | Yes           |
| Review / Medium       | 30       | 7            | No            |
| Review / Low          | 45       | 10           | No            |

### SLA status

| Status     | Condition                                    |
| ---------- | -------------------------------------------- |
| `On Track` | More than warning days remaining             |
| `Warning`  | Within warning threshold but before due date |
| `Critical` | Due date is today                            |
| `Breached` | Past due date                                |

### Auto-escalation

A nightly batch job checks for SLA breaches. Cases with auto-escalation enabled are automatically:

1. Set to `Internal Review` status
2. Assigned to the current analyst's manager
3. Flagged with an escalation reason ("SLA breach")
4. Logged in the audit trail

## Closure requirements

A case can only be closed when:

1. **All alerts are resolved** -- open alert count must be zero
2. **Resolution notes provided** -- a summary of the investigation outcome

```bash theme={null}
curl -X POST https://api.zenoo.com/v1/cases/cas_xyz789/close \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "resolution_notes": "All checks passed. PEP match on UBO reviewed and cleared."
  }'
```

If open alerts remain, the API returns:

```json theme={null}
{
  "error": "closure_blocked",
  "message": "Cannot close case with 2 open alerts. Resolve all alerts first.",
  "open_alerts_count": 2
}
```

## Escalation

Cases can be escalated manually or automatically.

### Manual escalation

```bash theme={null}
curl -X POST https://api.zenoo.com/v1/cases/cas_xyz789/escalate \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Complex corporate structure requires senior review.",
    "escalate_to": "user_manager01"
  }'
```

### What happens on escalation

1. Case status changes to `Internal Review`
2. Case is assigned to the specified manager
3. Email notification sent to the manager
4. Audit trail entry created (`CASE_ESCALATION`)
5. Escalation date and reason are recorded

## Risk score recalculation

Case risk scores are automatically recalculated when:

* An alert is resolved or created
* A risk assessment is approved
* An analyst applies a risk override

The system uses approved risk assessments as the primary source. If none exist, it falls back to an alert-based scoring algorithm.

## Next steps

* [Entity Lifecycle](/guides/entity-lifecycle). How entities relate to cases.
* [Alert Management](/guides/alert-management). Alert lifecycle within a case.
* [Audit Trail](/guides/audit-trail). Track every case event.
* [Cases Data Model](/data-model/cases). Full field reference.