Monitoring API reference
Every monitoring endpoint and object, each linked to its Request and Response tables.
Livehttps://api.offendersearch.appSandboxhttps://sandbox.offendersearch.appSex offender monitoring API endpoints
Every monitoring endpoint, each linked to its Request and Response tables. All five authenticate with the X-API-Key header and live under https://api.offendersearch.app.
| Endpoint | What it does |
|---|---|
| POST /v1/monitors | Create a monitor. Create a person or location monitor on the sex offender or criminal dataset. Returns the new monitor with 201. |
| GET /v1/monitors | List monitors. Every monitor on the account, newest first. Active monitors only unless you pass includeCanceled=true. |
| GET /v1/monitors/{monitorId} | Retrieve a monitor. One monitor with recentAlerts, its ten most recently observed alerts. Works on active and canceled monitors. |
| DELETE /v1/monitors/{monitorId} | Cancel a monitor. Cancel a monitor. It stops being evaluated at once and is not charged on any invoice prepared after the cancel. The monitor and its alerts stay readable with GET /v1/monitors/{monitorId}. |
| GET /v1/monitors/{monitorId}/alerts | Alert history. One monitor's alerts, most recently observed first — the system of record for every alert the monitor has raised, whether or not a delivery reached you. |
Monitoring API objects
Every object the monitoring endpoints accept or return, and the webhook payload they deliver. Each one is defined once, on the page linked here, and every other mention links back to it.
| Object | What it is |
|---|---|
| PersonCriteria | Who a person monitor watches: person on POST /v1/monitors. Returned on the monitor as person. |
| LocationCriteria | The centre and radius a location monitor watches: location on POST /v1/monitors. Returned on the monitor as location. |
| Channels | Where a monitor's alerts are delivered: channels on POST /v1/monitors. The account owner's email always receives the alert email as well. |
| Monitor | One standing watch, as POST /v1/monitors, GET /v1/monitors and GET /v1/monitors/{monitorId} return it. A person monitor carries person and no location key; a location monitor carries location and no person key — read type, then the matching object. |
| Alert | 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. |
| AlertRecord | 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. |
| WebhookDelivery | The JSON body POSTed to channels.webhookUrl, one request per alert, with Content-Type: application/json and User-Agent: Offendersearch-Monitor/1. A signed delivery also carries X-Offendersearch-Signature: sha256=<hex>, the HMAC-SHA256 of the raw body; deliveries are not signed today, so authenticate them with a secret token in your webhookUrl. |
Errors on every monitoring endpoint share one shape, described in the error envelope.