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

# Smart Sentinel

> Continuous monitoring for the vendors you've verified.

Verification is a snapshot. Smart Sentinel is the camera that keeps rolling — it re-runs authoritative checks on a schedule and watches open-source feeds for material events about your vendors. When something changes, you get an alert with the evidence attached.

## What it watches

Sentinel runs as a fleet of small, single-purpose **agents**. Each agent owns one source.

| Agent         | Source                           | Cadence |
| ------------- | -------------------------------- | ------- |
| `cac-status`  | CAC company registry             | daily   |
| `firs-tin`    | FIRS / JTB taxpayer registry     | weekly  |
| `sanctions`   | OFAC, UN, EU consolidated list   | daily   |
| `gdelt`       | GDELT global news project        | hourly  |
| `cbn-rss`     | CBN circulars & advisories       | hourly  |
| `google-news` | Google News for the company name | daily   |

Each agent compares the latest payload to the last one we stored. If the hash differs, it produces a structured **monitoring event** rather than a raw blob — already classified by severity, with the changed fields called out.

## Event lifecycle

<Steps>
  <Step title="Detect">
    The agent runs, fetches data, and compares against the stored baseline.
  </Step>

  <Step title="Emit">
    A `MonitoringEvent` is written with `severity`, `title`, `description`, and `changedFields`.
  </Step>

  <Step title="Alert">
    An alert is fanned out to the customers who have this vendor under monitoring, respecting their notification preferences.
  </Step>

  <Step title="Resolve">
    The customer reads or acks the alert. If a sentinel finding warrants action, it may trigger a deeper [Investigation Report](/concepts/investigation-reports).
  </Step>
</Steps>

## Severities

| Severity   | Examples                                                                                         |
| ---------- | ------------------------------------------------------------------------------------------------ |
| **HIGH**   | CAC status flipped to `INACTIVE`, FIRS TIN deactivated, sanctions match, taxpayer name mismatch. |
| **MEDIUM** | Director added or removed, share-capital change, adverse news with strong topical match.         |
| **LOW**    | Address change, contact change, low-confidence news mention.                                     |

High-severity events can revoke a Trust Badge automatically; medium and low events are surfaced but never auto-revoke.

## Subscribing a vendor

You opt a company into monitoring from the dashboard or the API by adding it to your watchlist. Provide a `vendorId`, an `rcNumber`, or both — at least one is required:

```bash theme={null}
curl -X POST https://api.vouchmark.com/v1/monitoring/vendors/watchlist \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"rcNumber":"RC1234567"}'
```

Once added, the company appears in `GET /v1/monitoring/vendors` and an event stream becomes available at `GET /v1/monitoring/vendors/:vendorId/events`. Each vendor in the list carries `vendorName`, `riskTier` (`LOW`, `MEDIUM`, `HIGH`, or `CRITICAL`), and `hasAlerts`. Remove a vendor with `DELETE /v1/monitoring/vendors/watchlist/:vendorId`.

## Tuning the noise

Smart Sentinel is opinionated — it prefers signal over recall. Every agent has:

* A **payload digest** so unchanged data doesn't fire alerts.
* A **circuit breaker** that opens after repeated upstream failures (so an outage at FIRS doesn't drown the user in fake "TIN unavailable" events).
* A **rate limiter** with jitter so we don't hammer source systems.

You can mute individual agents per vendor from the dashboard if a particular feed is generating noise for that name.

## Where to go next

<CardGroup cols={2}>
  <Card title="Verification lifecycle" icon="route" href="/concepts/verification-lifecycle">
    Where Sentinel sits in the overall flow.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/webhooks">
    Receive monitoring events at your own endpoint.
  </Card>
</CardGroup>