offenders.io drop-in compatibility (POST)

Accepts offenders.io's exact parameters and returns their exact envelope ({offenders, page, totalPages[, error]}). Existing offenders.io integrations switch by changing only the base URL and key. Accepts the key via X-API-Key, Authorization: Bearer, or ?key=. Echoes/mints the offenders.io correlation headers (X-Request-Id, X-Offenders-Request-Id, X-Offendersearch-Request-Id). Errors use the offenders.io {code, message} shape.

Combination-validation (400 with {code:400, message}): q cannot be combined with firstName/lastName, nor with lat/lng; address cannot be combined with q, nor with lat/lng.

GIS search (lat+lng supplied): results are paged 50 per page (regular searches page 20), and the query defaults to the last 90 days of source updates (updatedAtStart = now − 90d) unless the caller supplies an explicit updatedAtStart. A missing radius defaults to 1 mile (capped at 100).

post/v1/compat/sexoffender

Request

  • Base URL: https://api.offendersearch.app
  • URL: https://api.offendersearch.app/v1/compat/sexoffender
  • Auth: one of:
    • API key in header X-API-Key
    • HTTP bearer
    • API key in query parameter key

Headers

X-Request-Idstring

Optional client correlation id; echoed back when valid.

Request body

firstNamestring
lastNamestring
dobstring date
ageinteger
citystring
statestring
zipcodestring
addressstring

Cannot be combined with q or lat/lng (400).

latnumber
lngnumber
radiusnumber

Miles; defaults to 1 when a point is given, capped at 100. GIS pages are 50/page.

qstring

Cannot be combined with firstName/lastName or lat/lng (400).

fuzzyboolean
mode'extensive'
faceIdstring

Not supported — returns 422.

createdAtStartstring date-time
createdAtEndstring date-time
updatedAtStartstring date-time

GIS searches default to the last 90 days of updates unless this is set.

updatedAtEndstring date-time
uuidstring

Direct record lookup (parity), database-backed since 2026-08-04. Pass the uuid a search returned. BEFORE that date this accepted only our internal rec_… id, so feeding back the uuid this same endpoint publishes returned an empty offenders array 100% of the time. An empty result means the id is not CURRENT (registries re-issue ids in bulk), not that the person is unregistered — re-search by name and state. Combine with state when the id may be shared across jurisdictions; without it every match is returned.

personUuidstring

Alias of uuid for direct record lookup (parity). Same semantics.

pageinteger
perPageinteger

Response

offenders.io-shaped response

pageinteger
totalPagesinteger
errorinteger nullable

offenders.io convention: present (e.g. 503) when the result set may be incomplete (deadline-partial or a source errored).

Example response

{
  "offenders": [
    {
      "firstName_nicknames": [
        "john",
        "johnny"
      ],
      "stateData": {
        "shoeSize": "10½",
        "build": "Large",
        "shoeWidth": "D"
      }
    }
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.