Alerts, events & cadence

The alert object

One person's latest event on one monitor, as the alert history and recentAlerts return it. There is one alert per monitor and person per registry: when a matched person's record changes again, or a registry republishes it under a new number, the alert keeps the same id and (on a change) takes the new eventType.

Returned or accepted by POST /v1/monitors, GET /v1/monitors, GET /v1/monitors/{monitorId}, GET /v1/monitors/{monitorId}/alerts, POST /v1/monitors/{monitorId}/webhook-secret.

The AlertRecord object — the matched record in an alert

The matched record, summarised: record on an alert, detail on a webhook delivery. It names the person and a city, never a street address, and carries the personRef to recognise the person by. On a removed event it carries event and jurisdiction; reconcile a removal by the alert's id, which does not change. Run a search with the monitor's criteria, or fetch recordId, for the full record.

Returned or accepted by POST /v1/monitors, GET /v1/monitors, GET /v1/monitors/{monitorId}, GET /v1/monitors/{monitorId}/alerts, POST /v1/monitors/{monitorId}/webhook-secret.

The three event types

Exclusion-list alerts on a criminal monitor

A criminal person monitor also watches the exclusion-list records the criminal search carries — the HHS-OIG, SAM.gov and state Medicaid exclusion lists. Nothing changes on the request. On a criminal monitor record.recordType names the kind of record that matched, and when it is healthcare_exclusion the alert carries record.exclusion with the list’s authority, convictionBased and excludedOn. The event reads accordingly: new is a person added to an exclusion list, changed an exclusion updated on the list (a waiver or reinstatement date added, an authority corrected), and removed a person removed from the list — reinstated, or the exclusion term ended.

Only conviction-based exclusions alert, matching what a default search returns; administrative exclusions (license actions, debarments, loan defaults) never produce an alert. Because a person monitor is keyed on a date of birth, list entries that publish none — most SAM.gov and state entries — do not alert either.

{
  "id": "hit_2c84e1f09a6b7d31",
  "eventType": "new",
  "matchLabel": "dob_match",
  "record": {
    "name": "ALEX Q HAMILTON",
    "jurisdiction": "OH",
    "locality": "Columbus",
    "matchLabel": "dob_match",
    "matchConfidence": 0.99,
    "personRef": "prs_6d0c2a9e4b1f7e3a8c5d",
    "recordId": null,
    "recordType": "healthcare_exclusion",
    "exclusion": { "authority": "1128(a)(1)", "convictionBased": true, "excludedOn": "2026-10-01" }
  },
  "firstSeenAt": "2026-10-11T06:00:12+00:00",
  "occurredAt": "2026-10-11T06:00:12+00:00",
  "notifiedAt": "2026-10-11T06:01:04+00:00"
}

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.

One alert per person

A monitor keys its alerts on the person, not the listing. Within one registry — or, on a criminal monitor, one source — the person is identified by personRef, the same value the matching record carries in search results, and that value stays the same when the registry republishes the listing under a new number. The consequences:

• One thread per person per registry. Someone listed in two registries is two alerts, one per registry; someone whose listing a registry renumbered is still one alert, with the same id.
• A renumbered listing is not an event. It produces no new, no changed and no removed. new means a person newly matches, changed means a fact about them changed, and removed means they are no longer listed in that registry.
• The alert carries the identifiers. record.personRef is what to reconcile your own files on, with jurisdiction. On a sex-offender monitor record.recordId is the matching record as it stood at the event, for GET /v1/records/{recordId}; read it as a pointer to that record, not as the person’s key.

De-duplication

A monitor keeps one alert per person per registry. A person who stays matched and unchanged is silent after their first new. When a fact about a matched person changes, or they stop matching, the same alert — same id — takes the new eventType (changed or removed), its notifiedAt resets to null, and the event is delivered again.