API Reference · Monitoring

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 signed webhook. Same account, same key, same dashboard as the Sex Offender and Criminal Search APIs.

Base URL https://api.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 signed webhook. Alerts arrive by email, and by webhook when you configure one — a signed JSON payload you verify, retried until your endpoint acknowledges it.
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).

The Monitoring API is not a consumer reporting agency and its alerts are not a consumer report. 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. It is stated in the legal notice that accompanies every monitor and every alert.

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.

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 by default, an optional signed webhook you verify, and the retry contract behind both.

Billing & reference

Billing — one predicate, one charge

The price matrix, the one-predicate-one-charge rule, and how cancelling prorates at period end.

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

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 monitors, active and cancelled.
GET	/v1/monitors/{id}	Retrieve one monitor together with its recent alerts.
DELETE	/v1/monitors/{id}	Cancel a monitor. Stops billing at the period end (prorated).
GET	/v1/monitors/{id}/alerts	The full alert history for one monitor, most recent 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 →