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

# Alert Management

> Alert lifecycle, auto-triage, AI research, priority scoring, SLA monitoring, and bulk operations in the Zenoo CLM platform.

# Alert Management

Alerts are the primary work items for compliance analysts. They represent compliance issues -- PEP matches, sanctions hits, adverse media, identity discrepancies -- that require human review and resolution.

## Alert lifecycle

```mermaid theme={null}
stateDiagram-v2
    [*] --> Open : Alert created
    Open --> Acknowledged : Analyst claims
    Open --> Resolved : Direct resolution
    Open --> False_Positive : Confirmed FP
    Open --> Escalated : Escalate to manager
    Acknowledged --> Resolved : After review
    Acknowledged --> False_Positive : Confirmed FP
    Acknowledged --> Escalated : Escalate
    Resolved --> [*]
    False_Positive --> [*]
    Escalated --> [*]
```

| Status           | Description                                    |
| ---------------- | ---------------------------------------------- |
| `Open`           | Alert created, awaiting analyst review         |
| `Acknowledged`   | Analyst has claimed and is reviewing the alert |
| `Resolved`       | Alert reviewed and resolved with an action     |
| `False Positive` | Confirmed as a false positive match            |
| `Escalated`      | Escalated to a senior reviewer or manager      |

## Auto-triage

New alerts can be automatically triaged using AI research. The auto-triage system is configured via custom metadata:

1. **Alert insertion** triggers the auto-triage handler
2. The handler filters alerts by type and category against the triage configuration
3. Eligible alerts are dispatched to an async AI research queue
4. AI research analyzes the screening match against public sources
5. Results are written back to the alert (assessment, confidence, false positive probability)
6. If configured, the auto-disposition pipeline evaluates the results

<Info>
  Auto-triage is configurable per alert type and category. You can exclude specific categories (e.g., Sanctions) from auto-triage to ensure they always receive human review.
</Info>

## AI research

AI research provides automated analysis of screening matches. When triggered (manually or via auto-triage), the system:

1. Builds a research prompt with alert details, entity context, and screening data
2. Submits to a web research AI (Perplexity) for validation
3. Returns a structured assessment with:
   * **Assessment narrative** -- detailed analysis of the match
   * **Confidence score** -- AI confidence in its assessment (0-100%)
   * **False positive probability** -- likelihood the match is a false positive (0-100%)
   * **Recommended action** -- suggested resolution (Approve, Decline, Escalate)
   * **Sources** -- URLs of sources consulted

### Auto-disposition

Alerts with high-confidence false positive assessments can be automatically resolved:

| Condition                            | Action                                        |
| ------------------------------------ | --------------------------------------------- |
| FP probability >= category threshold | Auto-resolve as False Positive                |
| FP probability \< threshold          | Leave for human review                        |
| QA sampling enabled                  | Flag a percentage of auto-dispositions for QA |

Auto-disposition thresholds are configured per alert category. For example, `Adverse Media` might auto-dispose at 90% FP probability while `Sanctions Hit` is never auto-disposed.

## Priority scoring

Every alert receives a composite priority score (0-290 points) calculated from five components:

| Component       | Max Points | Calculation                                      |
| --------------- | ---------- | ------------------------------------------------ |
| SLA urgency     | 100        | Breached = 100, linear decay from due date       |
| Risk tier       | 100        | Critical = 100, High = 75, Medium = 50, Low = 25 |
| Category weight | 60         | Sanctions = 60, PEP = 45, Adverse Media = 30     |
| Match score     | 10         | Screening confidence / 10                        |
| Case risk       | 20         | Parent case risk score / 5                       |

The priority score drives the default sort order in the analyst inbox: highest-score alerts appear first.

### Priority labels

| Priority   | Score Range |
| ---------- | ----------- |
| `Critical` | 200+        |
| `High`     | 120-199     |
| `Medium`   | 60-119      |
| `Low`      | 0-59        |

## SLA monitoring

Each alert inherits an SLA due date based on its category and priority. A nightly batch job monitors SLA compliance:

| SLA Status | Condition                    | Action                        |
| ---------- | ---------------------------- | ----------------------------- |
| `On Track` | Due date > warning threshold | No action                     |
| `Warning`  | Within warning window        | Email notification to analyst |
| `Critical` | Due date is today            | Urgent notification           |
| `Breached` | Past due date                | Auto-escalate (if configured) |

## Resolution actions

When resolving an alert, specify one of the following actions:

| Action                    | Description                             | Use case                               |
| ------------------------- | --------------------------------------- | -------------------------------------- |
| `Approve`                 | Accept the entity despite the alert     | False positive or acceptable risk      |
| `Decline`                 | Reject the entity                       | Confirmed compliance issue             |
| `Escalate`                | Route to senior reviewer                | Complex or uncertain case              |
| `Request Document`        | Request additional evidence from client | Insufficient documentation             |
| `Approve with Conditions` | Accept with monitoring or restrictions  | Marginal risk, mitigated by conditions |

## Bulk operations

For high-volume processing, use the bulk endpoints:

```bash theme={null}
# Bulk acknowledge
curl -X POST https://api.zenoo.com/v1/alerts/bulk/acknowledge \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{ "alert_tokens": ["alt_001", "alt_002", "alt_003"] }'

# Bulk resolve
curl -X POST https://api.zenoo.com/v1/alerts/bulk/resolve \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "alert_tokens": ["alt_004", "alt_005"],
    "action": "Approve",
    "notes": "Batch: confirmed formatting differences."
  }'

# Bulk assign
curl -X POST https://api.zenoo.com/v1/alerts/bulk/assign \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "alert_tokens": ["alt_006", "alt_007"],
    "assignee": "user_analyst01"
  }'
```

See [Bulk Operations Guide](/guides/bulk-operations) for details on partial success handling and error responses.

## Next steps

* [AI Research Guide](/guides/ai-research). Deep dive into AI-powered alert analysis.
* [Risk Scoring Guide](/guides/risk-scoring). How alerts contribute to risk assessments.
* [Alerts Data Model](/data-model/alerts). Full field reference.
* [Bulk Operations Guide](/guides/bulk-operations). Processing alerts at scale.