# Handling false positives

> Common names produce candidates. The API gives you the tools to review them and to remember the outcome.

- **HTML:** https://offendersearch.app/docs/guides/criminal/false-positives
- **Base URL (live):** https://api.offendersearch.app — live keys (`os_live_…`)
- **Base URL (sandbox):** https://sandbox.offendersearch.app — test keys (`os_test_…`), never billed
- **Authentication:** `X-API-Key` request header
- **OpenAPI:** https://offendersearch.app/openapi.json · https://offendersearch.app/openapi.yaml
- **Docs index for agents:** https://offendersearch.app/llms.txt

## 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](/docs/criminal/clearances).

## Related

- [Matching & confidence](https://offendersearch.app/docs/criminal/matching)
- [Date of birth](https://offendersearch.app/docs/criminal/date-of-birth)
- [Clearances](https://offendersearch.app/docs/criminal/clearances)