Jurisdictions & codes

A code names a state and a jurisdiction, and nothing else

A jurisdiction code is the neutral handle for one place the product covers. It is what sources[].code reports on a record, what you pass as live.jurisdictions to verify at a source, and what the website resolver returns. There is deliberately no token for how the data is obtained — no portal, platform or vendor ever appears in a code, a source name, a coverage total, or an error. A code is a jurisdiction handle, and it is vendor-neutral by construction.

The two shapes

<ST> is the two-letter USPS state code (US for a federal system). <COUNTY> is the county name, upper-cased, non-alphanumerics dropped and spaces hyphenated — Palm Beach → PALM-BEACH — and it is the county name only: it never carries the word “County”. A county code never takes a record-kind suffix, because a county line already names one place.

The record-kind vocabulary

For a statewide or federal system the suffix is the kind of record the system publishes — one token from a fixed set. So TX-DOC is the Texas state prison system, OK-COURT is Oklahoma statewide court records, and US-WARRANT is a federal warrant system.

GET /v1/criminal/jurisdictions

The coverage catalog as codes — every jurisdiction the product covers, plus an honest per-product coverage summary. This is where you enumerate the codes you will send in a search; do not build them by hand. Requires an API key. Three query parameters filter it, and they combine (AND):

curl -s -G "https://api.offendersearch.app/v1/criminal/jurisdictions" \
  -H "X-API-Key: $OFFENDERSEARCH_KEY" \
  --data-urlencode "state=TX" \
  --data-urlencode "live=true"

{
  "coverage": { "jurisdictions_total": 1410, "jurisdictions_live_connector": 727,
                "jurisdictions_pending_connector": 683, "states_covered": 50 },
  "jurisdictions": [
    { "code": "TX-DALLAS", "state": "TX", "county": "Dallas",
      "recordKind": "jail-roster", "level": "county", "live": true },
    { "code": "TX-DOC", "state": "TX", "county": null,
      "recordKind": "doc-inmate", "level": "state", "live": true }
  ],
  "count": 41
}

Each row is { code, state, county, recordKind, level, live }. An unmatched state simply yields an empty jurisdictions[] with the coverage summary intact — never an error. The recordKind values are the ones below:

How a code is used

A code shows up in two places, and they are different controls. A cached search is scoped by query.state and query.county — the location filter — while a live verification names the exact jurisdictions to re-check by their public codes in live.jurisdictions.

{
  "query": { "lastName": "Hamilton", "state": "TX", "county": "Dallas" }
}

{
  "query": { "lastName": "Hamilton", "state": "TX" },
  "live": { "jurisdictions": ["TX-DALLAS", "TX-DOC"] }
}

query.county is matched case-insensitively (and is also accepted as query.jurisdiction). State and county filter the record's jurisdiction; city, ZIP and street address filter the residence where a source publishes one; there is no lat/lng radius yet. live.jurisdictions takes the public codes; one public county code may cover more than one system, and each reports its own row in sourceStatus[].