Quickstart

Authenticate

Every request carries your secret key in the X-API-Key header — the same key you already use for the Sex Offender API and the Criminal Search API. Monitoring is a product on your existing account, not a separate credential. Create a key in your dashboard and export it.

export OFFENDERSEARCH_BASE=https://api.offendersearch.app
export OFFENDERSEARCH_KEY="os_live_…"

Create your first monitor

A monitor is a standing watch. This one watches the sex-offender dataset for one person by name and date of birth, and delivers an alert whenever a matching record appears, changes, or comes off a registry. product, type, the predicate and at least one channel are required.

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" },
        "minConfidence": "dob_match",
        "label": "Jordan Rivera — SO watch",
        "channels": { "email": "alerts@example.com" }
      }'

The response is the monitor object. It is active immediately and evaluated once per day from then on.

{
  "id": "mon_7f2a1c9e0b4d",
  "product": "sex-offender",
  "type": "person",
  "person": { "firstName": "Jordan", "lastName": "Rivera", "dob": "1988-04-12" },
  "minConfidence": "dob_match",
  "label": "Jordan Rivera — SO watch",
  "status": "active",
  "channels": { "email": "alerts@example.com" },
  "createdAt": "2026-09-05T14:02:11+00:00",
  "legal": { "notice": "Not a consumer report. This information may not be used for any purpose under the Fair Credit Reporting Act (15 U.S.C. § 1681 et seq.)." }
}

Receive an alert

When the daily evaluation finds a matching record, an alert is delivered to every channel on the monitor. This is the JSON body POSTed to a webhook — the same shape you read back from the alert-history endpoint.

{
  "id": "alrt_a1b2c3d4e5f6",
  "monitorId": "mon_7f2a1c9e0b4d",
  "eventType": "new",
  "matchLabel": "dob_match",
  "record": {
    "name": { "first": "JORDAN", "last": "RIVERA" },
    "dob": "1988-04-12",
    "state": "TX",
    "jurisdiction": "TX-REGISTRY",
    "recordUrl": "https://…"
  },
  "occurredAt": "2026-09-06T05:12:00+00:00"
}

Read the alert, in this order, every time

1. eventType — new (a matching record newly appeared), changed (a monitored record’s details changed), or removed (it came off a registry). It tells you what happened before you read the record.
2. matchLabel — how strongly identity matched: dob_match is the full date of birth, year_match the birth year only. A monitor only alerts at or above its minConfidence floor. See Person monitoring.
3. record — a summary of the matching record, with a neutral jurisdiction code and a link back to the source page.
4. monitorId — which monitor fired, so one webhook endpoint can serve many monitors.
5. occurredAt — when the evaluation observed the event, in ISO-8601.

Where to go next

• Person monitoring — name + DOB, and why a DOB matters.
• Location monitoring — watch a radius around an address.
• Alerts — the event types, the daily cadence and de-duplication.
• Billing — the price matrix and the one-predicate-one-charge rule.