# Alerts, events & cadence

> The alert object and its three event types — new, changed and removed — plus the once-daily evaluation cadence and how repeat alerts are de-duplicated for you.

- **HTML:** https://offendersearch.app/docs/monitoring/alerts
- **Base URL:** https://api.offendersearch.app
- **Authentication:** `X-API-Key` request header
- **OpenAPI:** https://offendersearch.app/openapi.json · https://offendersearch.app/openapi.yaml
- **Monitoring reference as markdown:** https://offendersearch.app/docs/monitoring.md

## The alert object

An alert is one event on one monitor. The same shape is POSTed to a webhook and returned by `GET /v1/monitors/{id}/alerts`.

```json
{
  "id": "alrt_a1b2c3d4e5f6",
  "monitorId": "mon_7f2a1c9e0b4d",
  "eventType": "new",
  "matchLabel": "dob_match",
  "record": {
    "name": { "first": "JORDAN", "last": "RIVERA" },
    "dob": "1988-04-12",
    "state": "TX",
    "jurisdiction": "TX-REGISTRY",
    "recordUrl": "https://…"
  },
  "occurredAt": "2026-09-06T05:12:00+00:00"
}
```

| Field | Type | Notes |
| --- | --- | --- |
| `id` | string | The alert identifier, `alrt_` + 12 hex. |
| `monitorId` | string | The monitor that fired — so one endpoint can serve many monitors. |
| `eventType` | string | `new`, `changed` or `removed`. See below. |
| `matchLabel` | string | The identity match strength that fired: `dob_match` or `year_match`. |
| `record` | object | A summary of the matching record — identity, a neutral jurisdiction code, and a link back to the source page. |
| `occurredAt` | string | ISO-8601 timestamp of when the evaluation observed the event. |

## The three event types

| `eventType` | Meaning |
| --- | --- |
| `new` | A matching record **newly appeared** — a match that was not present at the previous evaluation. On a location monitor, a match moved into the radius. |
| `changed` | A record you are already matching had its **details change** — for example an address, an offense field, or a status. |
| `removed` | A record that was matching **came off a registry** — or, on a location monitor, moved out of the radius. Disappearance is data, so it is reported. |

## Cadence

Each monitor is evaluated **once per day**, against the continuously-updated dataset. An evaluation compares today’s matching records with the previous state and emits one alert per change. There is no faster tier and no way to force an off-cycle evaluation; a monitor is a daily watch by design.

## De-duplication

A monitor will not alert you twice for the same event. Once an alert has fired for a given record and `eventType`, the next day’s evaluation does not re-fire it — a record that stays present and unchanged is silent after its first `new`. A genuinely new event on the same record (its details `changed`, or it was `removed`) is a distinct alert. Because delivery is at-least-once, still treat `alert.id` as an idempotency key on your side.

## GET /v1/monitors/{id}/alerts

The full alert history for one monitor, most recent first. A monitor is visible only to the account that created it — another account’s `id` returns `404`.

```bash
curl "https://api.offendersearch.app/v1/monitors/mon_7f2a1c9e0b4d/alerts" \
  -H "X-API-Key: $OFFENDERSEARCH_KEY"
```

```json
{
  "monitorId": "mon_7f2a1c9e0b4d",
  "alerts": [
    { "id": "alrt_a1b2c3d4e5f6", "monitorId": "mon_7f2a1c9e0b4d",
      "eventType": "new", "matchLabel": "dob_match",
      "record": { "name": { "first": "JORDAN", "last": "RIVERA" }, "dob": "1988-04-12",
                  "state": "TX", "jurisdiction": "TX-REGISTRY", "recordUrl": "https://…" },
      "occurredAt": "2026-09-06T05:12:00+00:00" }
  ],
  "count": 1
}
```

> This history is not a consumer report. The notice — *Not a consumer report. This information may not be used for any purpose under the Fair Credit Reporting Act (15 U.S.C. § 1681 et seq.).* — accompanies it.

---

## Related

- Previous: [Location monitoring](https://offendersearch.app/docs/monitoring/location-monitoring.md)
- Next: [Delivery — email & webhooks](https://offendersearch.app/docs/monitoring/delivery.md)
- Index: [Monitoring API reference](https://offendersearch.app/docs/monitoring.md)