Search - POST /v1/criminal/search

The surname is the anchor; everything else narrows within it

A criminal search is a surname query, refined. lastName is the one predicate every search must carry — a first name, a date of birth, an age, or a location alone is refused with 422 guard_unbounded_query, because an unbounded query returns a lottery, not an answer. Every other field you send only narrows that surname query: it lowers confidence or drops records that conflict, and a record missing the field it would test is kept and flagged rather than dropped. This page is the complete list of the ways to narrow.

Two modes, decided by the request body

There is one search endpoint. Omit live for the cached answer — one indexed query across the continuously updated corpus, sub-second, no live source consulted. Send a live block for live verification — a real-time, moment-of-decision compliance check that re-verifies the actual jurisdiction(s) in-request and merges them with the cached answer through the same matcher, so a live record and a cached record agree about identity and rank together.

POST /v1/criminal/search

The primary endpoint. X-API-Key is required; the account must be entitled to the Criminal product, and to the live entitlement for a live request.

curl -X POST https://api.offendersearch.app/v1/criminal/search \
  -H "X-API-Key: $OFFENDERSEARCH_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "query": { "lastName": "Hamilton", "firstName": "Alex", "state": "TX" },
        "perPage": 50
      }'

Narrow by name

The surname is compared case-insensitively and is the only hard filter: a record whose surname neither equals nor starts with your lastName is dropped, and a record with no surname cannot satisfy a surname-mandatory query, so it is dropped too. Everything else about the name only adjusts confidence.

There is no fuzzy (typo) surname matching — Smyth never matches Smith. In this domain a false positive is the expensive error, so the matcher never introduces a surname it was not given. The full weighting is in Matching & confidence.

curl -X POST https://api.offendersearch.app/v1/criminal/search \
  -H "X-API-Key: $OFFENDERSEARCH_KEY" -H "Content-Type: application/json" \
  -d '{ "query": { "lastName": "Hamilton", "firstName": "Bob" } }'
# matches ROBERT HAMILTON too — the given name is folded through the nickname
# table before comparison, so matchBasis reads "firstName:exact".

The 3-character prefix floor

Prefix matching has a floor, and it fires only on a prefix you explicitly asked for. The rule decides 422-versus-fallback:

prefixMatch is the finer control: it selects prefix matching on a named field ("firstName", "lastName", "both", a list, or a delimited string; synonyms like "surname" / "given" are accepted). An unrecognised selector is ignored, not rejected — an unknown token must never widen a criminal search. The same 3-character floor applies to an explicit first-name prefix.

curl -X POST https://api.offendersearch.app/v1/criminal/search \
  -H "X-API-Key: $OFFENDERSEARCH_KEY" -H "Content-Type: application/json" \
  -d '{ "query": { "lastName": "Hamil", "firstName": "Al",
                   "prefixMatch": "lastName" } }'
# surname prefix-matches HAMIL* (HAMILTON, HAMILL, …); "Al" is compared
# exactly/by-nickname unless you also select it in prefixMatch.

// { "query": { "lastName": "ha", "prefixMatch": "lastName" } }  → HTTP 422
{ "error": { "code": "prefix_too_short",
             "message": "prefixMatch prefix matching on lastName requires at least 3 characters (got 'ha'). Send a longer prefix, or drop it for an exact match." } }

Narrow by date of birth or age

A date of birth is the strongest identity verifier available, and the one to send for anything consequential. Four fields carry birth evidence — but you rarely need more than one:

curl -X POST https://api.offendersearch.app/v1/criminal/search \
  -H "X-API-Key: $OFFENDERSEARCH_KEY" -H "Content-Type: application/json" \
  -d '{ "query": { "lastName": "Chen", "dob": "1979-11-03" } }'

That single query returns full-date records at dob_match, year-only records at year_match, age-only records at age_match, and records with no comparable birth evidence at no_dob_age_year — the last kept and flagged (unverified: true), present only because the surname matched. A response is therefore a mixture; branch on matchState for the full picture or unverified for the coarse one:

// ONE dob query, records honestly labelled by what each source published
[
  { "matchState": "dob_match",       "unverified": false,
    "dob": { "date": "1979-11-03", "birthYear": 1979, "dobPrecision": "full" } },
  { "matchState": "year_match",      "unverified": false,
    "dob": { "date": null, "birthYear": 1979, "dobPrecision": "year" } },
  { "matchState": "age_match",       "unverified": false,
    "dob": { "date": null, "birthYear": null, "age": 46, "dobPrecision": "age" } },
  { "matchState": "no_dob_age_year", "unverified": true,
    "dob": { "date": null, "birthYear": null, "dobPrecision": "none" } }
]

Only a genuine conflict (dob_mismatch) is excluded from records[]. A no_dob_age_year is an absence of comparable evidence, not a mismatch.

Narrow by place

Location filters keep records by where they are, not which corpus is searched. Two axes are the jurisdiction (state / county) the record lives in; three more — city, zipcode, address — filter on the person's residential address where the source publishes one (the registry and wanted records; incarcerated inmates have a facility, not a home address). These mirror the sex-offender product's location fields. There is no lat/lng radius yet — criminal records aren't geocoded.

A jurisdiction is always a neutral code — <ST>-<COUNTY> (a county, e.g. TX-DALLAS) or <ST>-<RECORD-KIND> (a statewide or federal system, e.g. TX-DOC, OK-COURT) — carrying a state and a place and nothing else. Enumerate the live values from Jurisdictions & codes rather than hard-coding them.

Driving a search from a website you already know

If you know the county roster or court portal for a place but not our code for it, hand us the URL and we resolve it. In a cached search, query.website scopes the answer to the resolved jurisdiction; the mapping comes back in a top-level resolution[] block so you can see which code it mapped to:

curl -X POST https://api.offendersearch.app/v1/criminal/search \
  -H "X-API-Key: $OFFENDERSEARCH_KEY" -H "Content-Type: application/json" \
  -d '{ "query": { "lastName": "Hamilton",
                   "website": "https://sheriff.examplecounty.gov/inmates" } }'

"resolution": [
  { "input": "https://sheriff.examplecounty.gov/inmates",
    "supported": true, "code": "TX-DALLAS",
    "note": "equivalent data available for this jurisdiction" }
]

In a live search, live.websites verifies the resolved jurisdictions exactly as if you had listed their codes in live.jurisdictions (the two are merged). An unsupported site does not fail the search — it is reported as its own sourceStatus[] row with incompleteReason: "unsupported_site". You can also resolve a URL up front, without searching, at Resolve a website → code.

curl -X POST https://api.offendersearch.app/v1/criminal/search \
  -H "X-API-Key: $OFFENDERSEARCH_KEY" -H "Content-Type: application/json" \
  -d '{ "query": { "lastName": "Hamilton", "state": "TX" },
        "live": { "websites": ["https://sheriff.examplecounty.gov/inmates"] } }'

Scoping a live check — the live block

Live verification is a real-time compliance re-check of a specific person at the actual jurisdiction(s). The live block is how you say where to re-check, in three combinable forms:

If none of these resolves to a source — an empty list, no cached matches under scope: "matched", or an unresolved code — the request is refused with 422 no_live_sources. The one exception is a live.websites list that was entirely unsupported: that is a resolution outcome, so you get the cached answer back with status: "partial" and the sites reported, not a 422.

Live verification: sync vs async

A live check of ≤2 sync-eligible sources runs synchronously (200, inline). More sources, or any source that needs heavier handling, fans out to an asynchronous job (202 + poll). Because one public county code can expand to several internal systems we cover for that county, a single live.jurisdictions: ["TX-DALLAS"] may resolve to more than two and run async — liveSourcesRequested in the 202 body reports the true count.

curl -X POST https://api.offendersearch.app/v1/criminal/search \
  -H "X-API-Key: $OFFENDERSEARCH_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "query": { "lastName": "Hamilton", "state": "TX", "dob": "1989-04-23" },
        "live": { "jurisdictions": ["TX-DALLAS"] }
      }'

Paging a result set

page and perPage are top-level request fields, not inside query — a deliberate difference from the Sex Offender API. Sending them inside query silently gives you the defaults (page: 1, perPage: 50). perPage is clamped to 1–200, and counts.records is the total before the slice. Full walk-through in Pagination.

The response envelope

Every top-level key is always present — test the value, never for key existence. On a cached search you get every key except usage and resolution (sourceStatus is []). On a live search you additionally get usage, a populated sourceStatus, and resolution if a website drove the request. A live-verified record carries liveChecked: true and a fresh lastCheckedAt.

{
  "status": "complete",
  "counts": { "records": 1, "recordsReturned": 1,
              "sourcesQueried": 1, "sourcesComplete": 1, "sourcesIncomplete": 0 },
  "warnings": [],
  "page": 1, "perPage": 50, "totalPages": 1,
  "sourceStatus": [
    { "code": "TX-DALLAS", "source": "TX-DALLAS", "ok": true, "incomplete": false,
      "incompleteReason": null, "records": 1,
      "lastCheckedAt": "2026-08-25T15:04:11+00:00", "live": true }
  ],
  "omittedFields": ["sourceData"],
  "records": [
    { "externalId": "TX-DALLAS:booking:889201",
      "name": { "first": "ALEX", "middle": "Q", "last": "HAMILTON", "suffix": "" },
      "matchConfidence": 0.95, "matchBasis": "lastName:exact firstName:notQueried dob:match",
      "matchState": "dob_match", "unverified": false, "liveChecked": true }
  ],
  "usage": { "liveChecks": 1, "liveChargeUsd": 0.02, "capped": false,
             "display": "1 live checks · $0.02" },
  "searchId": "crs_7f2a1c9e0b4d6a8f1e23",
  "legal": { "notice": "Not a consumer report. …" }
}

The 202 async body

When a live search must run asynchronously, you get a 202 with a searchId and a relative poll URL. Poll it until it returns 200 — both paths run the same live checks and return the same envelope.

{
  "searchId": "crs_9a3b71c0e28d4f6a5b12",
  "status": "pending",
  "mode": "async",
  "liveSourcesRequested": 4,
  "poll": "/v1/criminal/searches/crs_9a3b71c0e28d4f6a5b12",
  "reason": "4 live sources (> 2 or not sync-eligible) — running asynchronously"
}

The unbounded-query guard

A query with no surname is refused. A first name, a date of birth, and a state together are still refused — none of them is a surname, and the surname is the one predicate every search must carry:

// { "query": { "firstName": "Alex", "state": "TX", "dob": "1989-04-23" } }  → 422
{ "error": { "code": "guard_unbounded_query",
             "message": "a lastName predicate is required — an unbounded query returns a lottery, not an answer" } }