Monitoring API · v1.0.0

Monitoring API

Create a standing watch on a person or a place, and receive an alert whenever a matching record appears, changes, or is removed — by email, or by webhook. Same account, same key, same dashboard as the Sex Offender and Criminal Search APIs.

Livehttps://api.offendersearch.appSandboxhttps://sandbox.offendersearch.app

View as MarkdownCopy the whole reference for an LLM

Introduction

The Monitoring API is a REST API for standing watches. It lives under /v1/monitors, is authenticated with the same API key as the Sex Offender and Criminal Search APIs, and returns the same JSON envelope — a caller who knows one API knows all three. You create a monitor, and it delivers an alert whenever a matching record appears, changes, or is removed.

Person or location. A person monitor watches one name and date of birth; a location monitor watches a radius around an address. Each monitor watches exactly one dataset — sex-offender or criminal.
Evaluated once per day. Each monitor is evaluated daily against the continuously updated dataset, and emits one alert per change — new, changed or removed.
Delivered by email or webhook. Alerts arrive by email, and by webhook when you configure one — one JSON POST per alert. An alert that no channel delivered is sent again on the next day’s run.
One predicate, one charge. Person monitoring is $3/mo and location monitoring is $10/mo. Criminal and sex-offender monitoring are separate monitors, so watching one person across both datasets is two monitors ($6/mo).

Monitoring alerts are not a consumer report, and monitoring is not part of FCRA Partner Access. You may not use monitoring for employment, tenant screening, credit, insurance, or any other purpose covered by the FCRA — a restriction that matters most here, because a monitor runs unattended. Every alert email states it in its footer.

How we track a person

A monitor watches people, not listings. Each alert is keyed on the matching record’s personRef within one registry or source, so a resident, visitor or volunteer you watch stays one alert thread even when a registry republishes the listing under a new number. A new address, a changed status or a new booking is a changed event on that thread; a renumbered listing is no event at all.

Access

Monitoring is available on every account automatically — there is nothing to enable and no entitlement to request. Any valid /v1/monitors call works immediately, with the same keys you already use for the Sex Offender and Criminal Search APIs. Full detail is on Access & keys.

Your first monitor

Create a key in your dashboard, export it, and create a monitor. product, type, the predicate and at least one channel are required. The full walkthrough — with an alert payload — is on Quickstart.

POST /v1/monitors

curl -X POST https://api.offendersearch.app/v1/monitors \
  -H "X-API-Key: $OFFENDERSEARCH_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "product": "sex-offender",
        "type": "person",
        "person": { "firstName": "Jordan", "lastName": "Rivera", "dob": "1988-04-12" },
        "channels": { "email": "alerts@example.com" }
      }'

What is live today

Person monitoring is live on both datasets — sex-offender and criminal. Sex-offender location monitoring is live. Criminal location monitoring is coming soon: it will arrive as location coverage across criminal records expands, and until then a request for it returns a not_yet_available acknowledgement rather than an error. See Location monitoring.

Documentation

Each section below is its own page, with its own worked examples, and its own markdown alternate at /docs/monitoring/{section}.md.

Getting started

Quickstart

Your first monitor in three languages, and the alert it delivers when a record matches.

POST /v1/monitors Access, keys & data handling

The X-API-Key header, the security posture, and how monitored criteria and an address are stored.

Monitoring API sandbox & test keys

A test key, the sandbox base URL, person and location monitor scenarios, and a webhook test event. Never billed.

Core concepts

The Monitor object

One object per watch — its predicate, its channels, its status — and how to read every field.

Person monitoring

Watch a person by name and DOB, why the DOB matters, and the confidence floor an alert clears.

Location monitoring

Watch a radius around an address, with sex-offender coverage live and criminal records coming.

Alerts, events & cadence

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

GET /v1/monitors/{id}/alerts Delivery — email & webhooks

Email to every recipient, an optional webhook, the monitor.alert payload, and the retry rule.

Billing & reference

Billing — one predicate, one charge

The price matrix, the one-predicate-one-charge rule, and when cancelling ends the charge.

Endpoint & error reference

All five endpoints in one place — create, list, retrieve, cancel, alerts — and the error shape.

POST /v1/monitors · GET /v1/monitors · GET /v1/monitors/{id} · DELETE /v1/monitors/{id} · GET /v1/monitors/{id}/alerts Monitoring API reference

Every monitoring endpoint and object, each linked to its Request and Response tables.

POST /v1/monitors · GET /v1/monitors · GET /v1/monitors/{id} · DELETE /v1/monitors/{id} · GET /v1/monitors/{id}/alerts

Endpoint index

The public Monitoring surface, and the page that documents each in full. Every path is prefixed with the base URL.

Method	Path	What it does
POST	/v1/monitors	Create a monitor — a person or a location watch. Returns the monitor object.
GET	/v1/monitors	List this account’s active monitors; add includeCanceled=true for cancelled ones too.
GET	/v1/monitors/{id}	Retrieve one monitor together with its recent alerts.
DELETE	/v1/monitors/{id}	Cancel a monitor. It stops being evaluated at once and is not charged on any later invoice.
GET	/v1/monitors/{id}/alerts	The alert history for one monitor, up to 200 per call, most recently observed first.

Alongside this: search on demand

Monitoring is the standing-watch companion to the search products. The Sex Offender and Criminal Search APIs answer a query right now; a monitor watches for you and alerts on a change. All three share one account and one key.

Read the Sex Offender API reference →