# The Monitor object

> Every field on a monitor: the id, product, type, the person or location predicate, minConfidence, label, status, channels and createdAt, each one explained.

- **HTML:** https://offendersearch.app/docs/monitoring/monitor-object
- **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

## One object per watch

A monitor is the durable record of a standing watch. The same object is returned by `POST /v1/monitors`, by `GET /v1/monitors` (in a list), and by `GET /v1/monitors/{id}` (with its recent alerts attached). Every top-level key is always present — test the value, never for key existence.

```json
{
  "id": "mon_7f2a1c9e0b4d",
  "product": "sex-offender",
  "type": "person",
  "person": { "firstName": "Jordan", "lastName": "Rivera", "dob": "1988-04-12" },
  "location": null,
  "minConfidence": "dob_match",
  "label": "Jordan Rivera — SO watch",
  "status": "active",
  "channels": { "email": "alerts@example.com", "webhookUrl": null },
  "createdAt": "2026-09-05T14:02:11+00:00"
}
```

## Fields

| Field | Type | Notes |
| --- | --- | --- |
| `id` | string | The monitor identifier, `mon_` + 12 hex. Use it on every `/v1/monitors/{id}` call. |
| `product` | string | `sex-offender` or `criminal` — the dataset this monitor watches. One product per monitor. |
| `type` | string | `person` (watch a name + DOB) or `location` (watch a radius around an address). |
| `person` | object \\| null | Present on a person monitor: `firstName`, `lastName`, `dob`. `null` on a location monitor. |
| `location` | object \\| null | Present on a location monitor: `address` (or `lat`/`lng`) and `radiusMiles`. `null` on a person monitor. |
| `minConfidence` | string | The confidence floor an alert must clear: `dob_match` or `year_match`. Defaults to `dob_match`. |
| `label` | string | Your own label for the monitor, echoed back on the object and on the dashboard. Optional. |
| `status` | string | `active` (evaluated daily, billing) or `canceled` (stopped; billing ends at the period end). |
| `channels` | object | Where alerts are delivered: `email` and/or `webhookUrl`. At least one is required at creation. |
| `createdAt` | string | ISO-8601 timestamp of when the monitor was created. |

## person and location are mutually exclusive

A monitor carries exactly one predicate. On a `type: "person"` monitor, `person` is populated and `location` is `null`; on a `type: "location"` monitor it is the reverse. Read `type` to know which to expect, then read the matching object.

## status and the monitor lifecycle

| `status` | Meaning |
| --- | --- |
| `active` | The monitor is evaluated once per day and is billed on your monthly invoice. |
| `canceled` | You cancelled it. It is no longer evaluated; billing stops at the end of the current period (prorated). It stays readable so its alert history is not lost. |

> A `canceled` monitor is not deleted — `GET /v1/monitors/{id}` still returns it and its alerts. Cancelling is how you stop a watch; there is no separate delete.

## GET /v1/monitors/{id}

Retrieve one monitor together with its recent alerts. A monitor is visible only to the account that created it — another account’s `id` returns `404`.

```bash
curl "https://api.offendersearch.app/v1/monitors/mon_7f2a1c9e0b4d" \
  -H "X-API-Key: $OFFENDERSEARCH_KEY"
```

```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", "webhookUrl": null },
  "createdAt": "2026-09-05T14:02:11+00:00",
  "recentAlerts": [
    { "id": "alrt_a1b2c3d4e5f6", "eventType": "new", "matchLabel": "dob_match",
      "occurredAt": "2026-09-06T05:12:00+00:00" }
  ]
}
```

---

## Related

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