Alerts, events & cadence

The alert object, the new / changed / removed events, the daily cadence, and de-duplication.

Base URL https://api.offendersearch.app

View as MarkdownCopy the whole reference for an LLM

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.

An alert

{
  "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. See Delivery.

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.

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

200 OK

{
  "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 legal notice accompanies it.