# Monitoring API reference

> Every Monitoring API endpoint and object in one index — create, list, retrieve, cancel, alert history, the Monitor, the alert and the webhook payload.

- **HTML:** https://offendersearch.app/docs/monitoring/api-reference
- **Base URL (live):** https://api.offendersearch.app — live keys (`os_live_…`)
- **Base URL (sandbox):** https://sandbox.offendersearch.app — test keys (`os_test_…`), never billed; see https://offendersearch.app/docs/monitoring/sandbox.md
- **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

## Sex 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`](https://offendersearch.app/docs/monitoring/endpoints#reference-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`](https://offendersearch.app/docs/monitoring/endpoints#reference-get-v1-monitors) | **List monitors.** Every monitor on the account, newest first. Active monitors only unless you pass `includeCanceled=true`. |
| [`GET /v1/monitors/{monitorId}`](https://offendersearch.app/docs/monitoring/endpoints#reference-get-v1-monitors-id) | **Retrieve a monitor.** One monitor with `recentAlerts`, its ten most recently observed alerts. Works on `active` and `canceled` monitors. |
| [`DELETE /v1/monitors/{monitorId}`](https://offendersearch.app/docs/monitoring/endpoints#reference-delete-v1-monitors-id) | **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`](https://offendersearch.app/docs/monitoring/alerts#alert-history) | **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. |
| [`POST /v1/monitors/{monitorId}/webhook-secret`](https://offendersearch.app/docs/monitoring/endpoints#reference-post-v1-monitors-id-webhook-secret) | **Rotate the webhook secret.** Issue a new signing secret for the monitor's webhook. The previous secret stops verifying at once. The new `whsec_…` value is returned in this response only. |

## 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`](https://offendersearch.app/docs/monitoring/person-monitoring#object-personcriteria) | Who a person monitor watches: `person` on `POST /v1/monitors`. Returned on the monitor as `person`. |
| [`LocationCriteria`](https://offendersearch.app/docs/monitoring/location-monitoring#object-locationcriteria) | The centre and radius a location monitor watches: `location` on `POST /v1/monitors`. Returned on the monitor as `location`. |
| [`Channels`](https://offendersearch.app/docs/monitoring/delivery#object-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`](https://offendersearch.app/docs/monitoring/monitor-object#fields) | 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`](https://offendersearch.app/docs/monitoring/alerts#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`. |
| [`AlertRecord`](https://offendersearch.app/docs/monitoring/alerts#object-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`](https://offendersearch.app/docs/monitoring/delivery#object-webhookdelivery) | The JSON body POSTed to `channels.webhookUrl`, one request per alert, with `Content-Type: application/json`, `User-Agent: Offendersearch-Monitor/1` and `X-Offendersearch-Signature: t=<unix seconds>,v1=<hex>` — the HMAC-SHA256, with the monitor's `webhookSecret`, of `<t>.<raw body>`. Verify it before acting (see Delivery). |

---

## Related

- Previous: [Endpoint & error reference](https://offendersearch.app/docs/monitoring/endpoints.md)
- Index: [Monitoring API reference](https://offendersearch.app/docs/monitoring.md)