Sex Offender Search API enums

What a `not_this_person` clearance does to the record it names. `suppress` (the default whenever `subjectId` is sent) removes the record from `records[]` and lists it in `cleared[]`. `annotate` keeps the record and attaches its `clearance` object, for an interface that shows cleared people greyed out. `ignore` answers as if no clearances existed. A `this_person` verdict, and a cleared person who has re-surfaced (`clearance.staleReason` set), are kept and annotated in every mode.

`"pdf"`: besides the live check, print each registry named in `jurisdictions` (up to 20) — its own public website, every result page and each matching registrant's detail page — to one PDF per registry behind a cover page, and return the documents with the records. The search then always answers `202` and is returned by `GET /v1/searches/{searchId}`, whose body carries `evidence[]`. $0.25 per completed registry document, $5.00 ceiling per search, on top of the live search's normal charge; an incomplete document bills nothing. Omit it, or send `"none"`, for today's search, byte for byte. See [Live evidence](/docs/live-evidence).

Record fields to leave out. The only value is `stateData` — the 36-field per-state block that is on every record by default. Send it for a lighter payload on large result sets; the response then lists it in `omittedFields`. Any other value is a `422`.

Document format: `pdf` or `html`.

Accepted for compatibility and has no effect: `stateData` is populated on every record by default. To drop it for a lighter payload send `exclude: ["stateData"]`.

Name matching for every row; same values as `SearchRequest.match` (default `balanced`).

How widely names match, applied the same way in every registry searched. `strict`: exact names only. `balanced`: exact surname, plus nicknames, initials, prefixes, middle names and one-letter typos on the first name. `broad`: also prefix and typo matches on the surname, and two-letter typos on the first name. `query.prefixMatch` (which runs the search at `broad`), `query.fuzzy` and `query.nameMatch` override it. An unrecognised value is a `422`. See [Matching & confidence](/docs/matching).

Strategies for the first name. `prefix` needs at least 3 characters; `middle` (your given name is the person's middle name) needs at least 2.

Strategies for the surname. `prefix` needs at least 3 characters.

A record that matches on name but whose published age contradicts your `dob` (or falls outside `ageTolerance` on an `age` search). `drop` omits it. `flag` returns it labelled `matchState: "age_mismatch"` and `unverified: true`.

What a row does at `deadlineMs`; same values as `SearchRequest.onDeadline`.

What happens at `deadlineMs`. `partial` returns what finished, with `status: "partial"` and every unfinished registry marked in `sourceStatus[]`. `error` returns `504` instead.

The dataset the verdict belongs to: `sex_offender` for a person returned by `POST /v1/search` or `POST /v1/batch`, `criminal` for one returned by `POST /v1/criminal/search`. A criminal `personRef` is scoped to one source, so a criminal clearance clears that source's records for the person — see [criminal clearances](/docs/criminal/clearances).

Record types to search. This endpoint searches sex offender registries only; criminal records are a separate product at `POST /v1/criminal/search`. Any other value is a `422`.

`"matched"` re-checks the registries that produced the Regular matches, instead of naming them.

`not_this_person` — the returned person is someone else; later searches for the subject suppress (or annotate) them. `this_person` — the returned person **is** the subject; later searches keep them and annotate the record so your interface can show the confirmed match.

The job's status.

`responseLimit` when `capped` is `true`; `null` otherwise.

`overloaded`: the service is at capacity; no result is implied about the person. `rate_limited`: a per-caller limit on the contact form and the consumer endpoints, never on search.

How much of the birth date the registry published. `exact`: a full date, in `dob`. `year`: a year only, in `birthYear`, and `dob` is `null`. `unknown`: neither; read `age`. `year_month` is reserved and not currently emitted.

The engine's raw DOB/age verification token. Read `matchState` instead — it is the clean vocabulary (`dob_match`, `year_match`, `age_match`, `no_dob_age_year`, `age_mismatch`, `dob_mismatch`, or `null` when nothing was scored). The `(filtered)` tokens surface only where the contract exposes rejected candidates; `""` = no DOB or age was sent.

`pdf` or `html`.

Labels for how recent the registry's data is (`daily`, `weekly`). Informational: each registry contributes to every search whatever this says.

Whether the registrant is housed, homeless or incarcerated, normalized from however the registry states it. `null` when the registry states none of these.

Why this registry did not finish; set exactly when `incomplete` is `true`. `deadline`: it did not answer in time — retry, or raise `deadlineMs` if you lowered it. `truncated`: the query matched more candidates than one search examines — narrow it (add a surname); retrying does not help. `excluded`: a retired option on your request dropped this registry; send the request without it and its records come back. `not_searched`: nothing was available to search for this registry — treat the answer as a lower bound and re-run later. `unavailable`: the registry could not be read for this request — retry. `error`: the registry failed — retry. See [Result completeness](/docs/result-completeness).

Why no document was produced; set exactly when `status` is `incomplete`. `no_recipe`: this registry cannot be printed yet. `renderer_unavailable`: the printing service was not available — retry. `source_unreachable`: the registry website did not answer — retry. `blocked`: the registry website refused the visit. `timed_out`: printing did not finish in time — retry. `no_results_page`: the registry website showed no results page for this query. `render_failed`: the pages were reached but could not be printed. `query_unsupported`: this registry's website cannot search on the fields the query supplied.

How the registry pages were produced. `text`: printed from the page, searchable. `image`: each page is a full-page capture rendered as an image (some registries only work this way). `mixed`: both in one document. Present only when `status` is `complete`.

`allowed`, `restricted`, `prohibited` or `unknown`: what the registry's terms say about commercial use. Records from every US registry are returned in search results whatever this says.

`legal` or `alias`; `null` when no name was queried.

Facts about the match as a whole: `matchedLegalName`, `matchedAlias`, `matchedMiddleName` (your given name is the person's middle name), `unverifiable` (no birth data to check). `linkedByRegistryId`: the record was pulled in through a registry id that links it to a matched record rather than by its own name.

`legal` for the registered name, `alias` for one of the record's aliases.

How this record was checked against the `dob` or `age` you sent, strongest first. `dob_match`: the registry's full date equals yours. `year_match`: the registry publishes only a year and it equals your date's year. `age_match`: the registry publishes only an age and it agrees with your date. `no_dob_age_year`: the registry publishes none of these, so nothing could be checked; the record matched on name and `unverified` is `true`. `age_mismatch`: the published age contradicts your date; returned only with `onAgeMismatch: "flag"`. `dob_mismatch`: excluded from results, documented for completeness. `null` when the query carried no `dob` or `age`. See [Searching by date of birth](/docs/date-of-birth).

Always `async`: a live evidence search never answers inline.

The dataset the verdict belongs to.

Always `sex_offender` on this endpoint.

`state` or `national`.

Why the person re-surfaced. `identity_changed` — their name or date of birth changed. `offenses_changed` — their offenses changed. `status_changed` — their registration status, tier or absconder/predator flag changed. `stronger_match` — this search matched the person more strongly than the search that was cleared (the subject's date of birth now matches where only the name did). `null` when the person has not re-surfaced.

`complete`: every registry searched was searched to the end. `partial`: at least one was not — read `counts.sourcesIncomplete` and `sourceStatus[]` before treating an empty `records` as an answer. `pending` and `running` appear only on an async job still in progress; `error` only on an async job that failed.

`ok`: the registry was searched (its records can still be `[]`). `error`: the registry failed for this request. `restricted`: reserved for a registry whose terms restrict this use; no registry returns it today. `no_coverage`: the registry does not cover this query. `ok` describes whether the registry answered, not whether the search finished — read `incomplete` for that. A row appended by a `live` re-check reads `complete` (finished) or `partial` (`incomplete: true`) instead.

Always `pending` on acceptance.

`complete`: the PDF was produced and can be downloaded. `incomplete`: it was not; read `incompleteReason`.

`pending` on acceptance.

`ready`: at least one document rendered. `none`: nothing was rendered. `rendering` is reserved and not returned today.

`live` when the registry is searchable.

`not_this_person` suppresses (or annotates) the person on later searches for the subject; `this_person` keeps and annotates them.

Always `not_this_person`; a `this_person` verdict never removes a record.

The verdict recorded for this person and subject.