# Quickstart

> Create your first person monitor in cURL, Node or Python, receive the alert a matching record triggers, and read the five fields on every alert payload.

- **HTML:** https://offendersearch.app/docs/monitoring/quickstart
- **Base URL:** https://api.offendersearch.app
- **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

## Authenticate

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

```bash
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.

```bash
curl -X POST "$OFFENDERSEARCH_BASE/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.

```json
{
  "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.

```json
{
  "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.
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](https://offendersearch.app/docs/monitoring/person-monitoring.md) — name + DOB, and why a DOB matters.
- [Location monitoring](https://offendersearch.app/docs/monitoring/location-monitoring.md) — watch a radius around an address.
- [Alerts](https://offendersearch.app/docs/monitoring/alerts.md) — the event types, the daily cadence and de-duplication.
- [Delivery](https://offendersearch.app/docs/monitoring/delivery.md) — email, signed webhooks and the retry contract.
- [Billing](https://offendersearch.app/docs/monitoring/billing.md) — the price matrix and the one-predicate-one-charge rule.

---

## Related

- Next: [Access, keys & data handling](https://offendersearch.app/docs/monitoring/authentication.md)
- Index: [Monitoring API reference](https://offendersearch.app/docs/monitoring.md)