Offendersearch

Search US sex-offender registries for one person and/or location. Fans out across all 58 registries (or the ones named in `jurisdictions`), de-duplicates people across registries, scores each match, and returns the normalized records. Supply whatever identifiers you have — all args are optional but at least a name, location, or free-text `q` should be given. Returns a SearchResponse object (docs/openapi.yaml / FIELD-DICTIONARY.md): - status: 'complete' | 'partial' (partial = a source errored, or a source could not be searched to completion) - counts: { records, sourcesQueried, sourcesIncomplete } - warnings: [str] — ALWAYS present, `[]` when the search ran clean - sourceStatus: [ { source, status, matched, fromCache, note, incomplete, incompleteReason } ] per-registry outcome ★ READ `counts.sourcesIncomplete` BEFORE REPORTING A RESULT. Above 0, `records` is a LOWER BOUND: those registries could not be searched to the end, and an empty or short result is NOT evidence that a person is unregistered. Say so. `warnings[0]` states it in plain language; relay it rather than summarising it away. - records: [ Record ], each with: recordId, matchConfidence, matchBasis[], name {first, middle, last, suffix, full}, aliases[], nicknames[], dob, dobPrecision, age, sex, race, ethnicity, height, weight, eyeColor, hairColor, marks, addresses[{type,line1,city,county,state,zipcode,lat,lng}], offense {crime,statute,riskLevel,tier,convictionDate,...}, flags{absconder,predator}, source {jurisdiction,registryName,recordUrl,scrapedAt,sourceUpdatedAt}, sources[], dobVerification, unverified (offenses[], stateData, images[] are populated only when extensive=true) Auth: uses the caller's X-API-Key (request header or OFFENDERSEARCH_API_KEY env).

{
  "type": "object",
  "properties": {
    "first_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Given name, e.g. 'John'.",
      "title": "First Name"
    },
    "last_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Surname — the primary match key, e.g. 'Smith'.",
      "title": "Last Name"
    },
    "dob": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Date of birth 'YYYY-MM-DD'. Improves match precision; drives dobVerification (dob_match / year_match).",
      "title": "Dob"
    },
    "age": {
      "anyOf": [
        {
          "maximum": 130,
          "minimum": 0,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Age filter, used when DOB is unknown. Matched +/-1 year for birthday drift.",
      "title": "Age"
    },
    "city": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Residence city filter.",
      "title": "City"
    },
    "state": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "2-letter state/territory code (e.g. 'IL', 'PR'), or the full name. A residence FILTER — it does NOT change which registries run; all 58 are still searched. It filters as a UNION: a record is kept when it has an address in that state OR that state's registry is the one holding it. Each record carries `registrationState` and `addressStates` so you can tell which half matched; for the registration half alone, pass `jurisdictions` instead.",
      "title": "State"
    },
    "zipcode": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Residence ZIP (first 5 digits used).",
      "title": "Zipcode"
    },
    "address": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Fuzzy street-address filter (every token must appear in some record address).",
      "title": "Address"
    },
    "lat": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Latitude for a GIS radius search (pair with lng).",
      "title": "Lat"
    },
    "lng": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Longitude for a GIS radius search (pair with lat).",
      "title": "Lng"
    },
    "radius_miles": {
      "anyOf": [
        {
          "exclusiveMinimum": 0,
          "maximum": 100,
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "GIS radius in miles around lat/lng. Defaults to 1 when a point is given; capped at 100.",
      "title": "Radius Miles"
    },
    "q": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Free-text search across name/alias/address/city/state/zip (all tokens must appear).",
      "title": "Q"
    },
    "jurisdictions": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Registry codes to query (e.g. ['IL','TX']). Omit/null = ALL 58 registries. See get_registry_coverage for codes.",
      "title": "Jurisdictions"
    },
    "match": {
      "default": "balanced",
      "description": "Fuzzy tolerance: strict=exact; balanced=nicknames/variants/initials/typos on first name, exact last; broad=also prefix/typo on last name.",
      "enum": [
        "strict",
        "balanced",
        "broad"
      ],
      "title": "Match",
      "type": "string"
    },
    "freshness": {
      "default": "daily",
      "description": "Cache/pricing tier: daily=<=24h (default), weekly=<=7d.",
      "enum": [
        "daily",
        "weekly"
      ],
      "title": "Freshness",
      "type": "string"
    },
    "location_scoped": {
      "default": false,
      "description": "OPT-IN ONLY, and never inferred from `state`. If true AND a state is set, run only the registries covering that state instead of all 58. It is a cost knob that COSTS RECALL: anyone registered by another state's registry while residing in the requested state is excluded (7.0% of records). The response reports counts.sourcesSkippedByScope and a NARROWED SEARCH warning when it applies. Leave it false unless the caller explicitly wants the cheaper, narrower search.",
      "title": "Location Scoped",
      "type": "boolean"
    },
    "extensive": {
      "default": false,
      "description": "If true, request extensive detail (retains offenses[], stateData, images). A light call drops them.",
      "title": "Extensive",
      "type": "boolean"
    },
    "deadline_ms": {
      "default": 120000,
      "description": "Max time to wait, in ms (default 120000 / 2 min). Lower for a faster bounded response; partial results return status='partial'.",
      "exclusiveMinimum": 0,
      "title": "Deadline Ms",
      "type": "integer"
    }
  },
  "title": "search_offendersArguments"
}

Run many person/location lookups in one call (row-in / row-out). Each row goes through the SAME engine as search_offenders, so a row's records are identical to what a single search would return. A row that fails is reported with status='error' in place and never aborts the batch. Max 1000 rows. Returns: { count, results: [ { index, status, counts{records,sourcesQueried, sourcesIncomplete}, warnings: [str], records: [Record], error? } ] } in input order. ★ A row with `counts.sourcesIncomplete > 0` could not be searched to the end — its `records` are a LOWER BOUND, not a clean 'no match'. Auth: uses the caller's X-API-Key (request header or OFFENDERSEARCH_API_KEY env).

{
  "type": "object",
  "properties": {
    "queries": {
      "description": "List of query objects (max 1000). Each may set any of: firstName, lastName, dob (YYYY-MM-DD), age, city, state, zipcode, address, lat, lng, radiusMiles, q. One row in = one result out, in input order.",
      "items": {
        "additionalProperties": true,
        "type": "object"
      },
      "title": "Queries",
      "type": "array"
    },
    "jurisdictions": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Registry codes applied to EVERY row (e.g. ['FL','TX']). Omit = all 58 registries.",
      "title": "Jurisdictions"
    },
    "match": {
      "default": "balanced",
      "description": "Fuzzy tolerance applied to every row (see search_offenders).",
      "enum": [
        "strict",
        "balanced",
        "broad"
      ],
      "title": "Match",
      "type": "string"
    },
    "freshness": {
      "default": "daily",
      "description": "Cache/pricing tier applied to every row: daily=<=24h (default), weekly=<=7d.",
      "enum": [
        "daily",
        "weekly"
      ],
      "title": "Freshness",
      "type": "string"
    },
    "location_scoped": {
      "default": false,
      "description": "Apply per-state scoping to every row (see search_offenders).",
      "title": "Location Scoped",
      "type": "boolean"
    },
    "extensive": {
      "default": false,
      "description": "Request extensive detail (offenses[], stateData, images) for every row.",
      "title": "Extensive",
      "type": "boolean"
    }
  },
  "required": [
    "queries"
  ],
  "title": "batch_searchArguments"
}

List every registry we cover plus its scope, legal status, and health. Public coverage catalog (no API key required). Use it to discover the `jurisdictions` codes accepted by search_offenders / batch_search and to check per-registry freshness/health before relying on a result. Returns: { count, registries: [ SourceInfo ] } where each SourceInfo is: - id: registry code (e.g. 'IL', 'TX', 'PR') - name: human-readable registry name - covers: [state codes] a registry covers ('*' = national / all) - scope: 'state' | 'national' - status: 'live' | 'building' - legal: { commercialUse: 'allowed'|'restricted'|'prohibited'|'unknown' } - health: { lastSuccessAt, typicalLatencyMs, ageSeconds, freshFor } `health` is OPERATIONAL COVERAGE METADATA about our ingest schedule, published for transparency. It is NOT a quality warning about a search result: a search serves every registry's best available data regardless of `freshFor`, so a registry listing only 'weekly' still contributes its records to a freshness='daily' search. Do NOT tell a user their search results are stale, unreliable or out of date on the basis of these fields — they are not. The only completeness signal that belongs in an answer is `counts.sourcesIncomplete` / `warnings[]` from the search response itself.

{
  "type": "object",
  "properties": {},
  "title": "get_registry_coverageArguments"
}

Search US criminal records — county jail bookings, state prison custody, court cases and warrants. Covers county jail rosters, statewide prison systems, court sources, warrant systems and statewide registries across the states, DC and the territories, plus the federal layer — which is a separate system holding offences no state search will surface. A surname is REQUIRED. Supply firstName and a DOB or birth year wherever you have them: a bare common surname returns thousands of people, and the scoring cannot tell you which one is yours. Each record carries `recordType`, and YOU MUST READ IT BEFORE CHARACTERISING ANYONE: - a jail booking is an ARREST-stage record — charges at booking are frequently reduced, dismissed, or never filed. It is NOT a conviction. - prison custody implies a sentence, and therefore a conviction. - a court record carries the DISPOSITION — the authoritative statement of how a case actually ended. - a warrant means the person is SOUGHT. Nothing has been tested. Never describe someone as convicted on the strength of a booking record. Records also carry: name, aliases, dob/birthYear/dobPrecision, sex, race, state, county, custody status and facility, sentence and parole detail, `cases`, `sources` (per-source citation), and `matchConfidence`/`matchBasis` explaining why it matched. `counts.records` is the total found and `counts.recordsReturned` the number in this page. Not a consumer report: results must not be used for FCRA-covered decisions (employment, tenancy, credit) without appropriate process.

{
  "type": "object",
  "properties": {
    "lastName": {
      "description": "REQUIRED surname. The criminal corpus refuses an unbounded query — a name is the field that cannot be enumerated.",
      "title": "Lastname",
      "type": "string"
    },
    "firstName": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Given name. Strongly recommended: a bare common surname returns thousands.",
      "title": "Firstname"
    },
    "dob": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Date of birth, YYYY-MM-DD. The single strongest disambiguator.",
      "title": "Dob"
    },
    "birthYear": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Birth year alone, when a full DOB is unknown.",
      "title": "Birthyear"
    },
    "age": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Approximate current age, when neither DOB nor birth year is known.",
      "title": "Age"
    },
    "state": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "2-letter state code (e.g. 'TX'). Narrows to that state's jurisdictions.",
      "title": "State"
    },
    "county": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "County name, to narrow within a state.",
      "title": "County"
    },
    "limit": {
      "anyOf": [
        {
          "maximum": 200,
          "minimum": 1,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Max records to return. Default 50.",
      "title": "Limit"
    }
  },
  "required": [
    "lastName"
  ],
  "title": "search_criminalArguments"
}

List the criminal-record jurisdictions searched, with kind and status. Use it to discover which states and counties are reachable and which are answering today, before relying on an empty result. Depth is uneven by design: counties publish independently, so a state with many county jurisdictions is not "better covered" than one that publishes a single statewide source — it is differently structured. Returns the jurisdiction roster; each entry carries its code, the state it belongs to, the kind of records it holds (jail / prison / court / warrant / registry) and whether it is currently answering.

{
  "type": "object",
  "properties": {},
  "title": "get_criminal_coverageArguments"
}