Person monitoring

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

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

View as MarkdownWhole product as one Markdown fileOpenAPI

Watch one person by name and date of birth

A person monitor stands watch over one identity — a name, and, when you supply it, a date of birth — across the dataset named in product. Each day it runs the same matcher the search endpoint uses, and when a matching record appears, changes, or stops matching, it delivers an alert.

A person monitor

{
  "product": "sex-offender",
  "type": "person",
  "person": { "firstName": "Jordan", "lastName": "Rivera", "dob": "1988-04-12" },
  "minConfidence": "dob_match",
  "channels": { "email": "alerts@example.com" }
}

Supply a date of birth

A name on its own matches many people, so a name-only monitor is noisy — it will alert on every same-named record in the dataset. A date of birth is the strongest identity verifier, and supplying it is the single most effective way to keep a monitor precise. The matcher uses the same match strength labels as search: a dob you provide can produce a dob_match (the full date agrees) or, where a record publishes only a birth year, a year_match.

Recommendation: always send a dob. Reserve a name-only monitor for the rare case where you genuinely want every same-named record and will triage the volume yourself.

Once a person matches, the monitor follows them, not the listing. Each alert is keyed on the record’s personRef within its registry, so a registry that republishes the listing under a new number leaves the alert thread — and its id — unchanged; only a fact about the person (an address, a status, a new booking on a criminal monitor) produces a changed event. See One alert per person.

minConfidence — the alert floor

A person monitor only fires when identity matches at or above its confidence floor. minConfidence sets that floor.

minConfidence	Fires on	Use it when
`dob_match`	The record’s full date of birth equals the one you registered.	You want the tightest, lowest-noise watch.
`year_match`	`dob_match`, plus records that publish only a birth year and agree on it. The default when you send a `dob`.	You want records that publish a year but no full date as well.
`age_match`	The above, plus records that publish only an age consistent with your date of birth.	You accept an age-only corroboration, at the cost of more alerts.
`name_match`	Every record that matches the name and does not contradict your `dob`. The default without a `dob`.	You will triage every same-named record yourself.
`any`	The default floor: `year_match` with a `dob`, `name_match` without.	You want the default and prefer to say so explicitly.

Leave minConfidence unset and the default applies. Any value outside these five is a 422.

The matchLabel on every alert tells you which strength actually fired, so under any floor you can tell a full-date confirmation from a year-only or age-only one. See Alerts.

The PersonCriteria object — person monitor request fields

Who a person monitor watches: person on POST /v1/monitors. Returned on the monitor as person.

Returned or accepted by POST /v1/monitors.

Field	Type	Description
firstName optional	string or null	Given name. Leading and trailing spaces are trimmed; an empty value is stored as `null` and the monitor matches on `lastName` (and `dob`) alone. Example `"Jordan"`
lastName required	string	Surname. Required: a person monitor without it is a `422`. Example `"Rivera"`
dob optional	string (date) or null	Date of birth, `YYYY-MM-DD`; any other format is a `422`. With a `dob` the default alert floor is `year_match`; without one it is `name_match`, which alerts on every same-named record. Example `"1988-04-12"`

What a person monitor watches

product: "sex-offender" — the sex-offender dataset. Live.
product: "criminal" — the criminal-records dataset. Live.

Watching one person across both datasets is two monitors, billed separately — each monitor is one product, one predicate, one charge. See Billing.

Not a consumer report

A person monitor runs unattended, which makes the FCRA restriction especially important: its alerts may not be used for employment, tenant screening, credit, insurance, or any other FCRA-covered decision. Every alert email carries that notice in its footer.