Handling false positives
Common names produce candidates. The API gives you the tools to review them and to remember the outcome.
Why they happen
- The surname must match exactly or as a prefix and the first name is scored after; there is no fuzzy surname matching, so misses are rarer than extra candidates — but a common name in a large state still yields several people.
- Many sources publish no date of birth. Those records are kept and labelled (
matchState: "no_dob_age_year",unverified: true) rather than dropped, because dropping them would hide real records. A record whose published birth date contradicts yours is dropped.
Reviewing a candidate
| Signal | Where | Read as |
|---|---|---|
| Birth date agreement | matchState (dob_match, year_match, age_match, no_dob_age_year); dob.dobPrecision (full, month_year, year, age, none) | Strongest disambiguator. null only on an unscored record fetch. |
| Source confirmation | dobVerification (record, source_confirmed, source_not_confirmed, unverified) | Whether the birth date came from the record or was confirmed at the source on a live check. |
| Why it matched | matchBasis (lastName:exact|prefix, firstName:exact|prefix|absent|mismatch|notQueried, dob:match|year|monthYear|age|…), matchDetail | Exact vs. prefix, missing first name, nickname folding. |
| Place | state, county, address, normalized.residence | Does the geography fit the person's history? locations[] on the request narrows to it. |
| Age and descriptors | dob.age, sex, race, physical, mugshotUrl where published | Supporting, never deciding. |
| Identifiers | identifiers (inmateNumber, stateId, fbiNumber, …), externalId | Confirm against a document the subject provided, where you hold one. |
| The source's own page | sources[].recordUrl | Always open before a decision. |
Remembering the outcome: clearances
When a reviewer decides a candidate is not the subject, record it: POST /v1/clearances with the subject, the record's personRef, verdict: "not_this_person" and product: "criminal" (the Sex Offender value here is sex_offender with an underscore, unlike a monitor's sex-offender). Send subjectId (and clientId for a multi-tenant platform) on later searches and the record is suppressed and listed in cleared[], or annotated with clearanceMode: "annotate". A personRef is scoped to one source, so a clearance hides that source's records for the person and no other's. Clearances apply to the synchronous POST /v1/criminal/search answer; a polled async result, a batch row or a report is not filtered by them. Clearances.