Offendersearch
Get API key
API Reference · v1.0.0

Quickstart

Your first authenticated search in three languages, and the four fields to read off every response.

Base URL https://api.offendersearch.appThis page as Markdown/docs/quickstart.md

Your first search

Create a key in your dashboard, export it, and make your first search. One authenticated call covers every jurisdiction: passing jurisdictions: null — or omitting it — searches the full dataset, and the response comes back as one scored, de-duplicated, source-tagged result set.

curl https://api.offendersearch.app/v1/search \
  -H "X-API-Key: $OFFENDERSEARCH_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": {
      "firstName": "John",
      "lastName": "Doe",
      "dob": "1980-04-12"
    },
    "jurisdictions": null,
    "freshness": "daily",
    "match": "balanced",
    "include": ["stateData"]
  }'

Read four things off every response

The response envelope is designed so that an integration can be correct without reading prose. Four fields carry everything you need to decide what to do with a result:

  1. status — "complete" or "partial". "partial" means a deadlineMs bound you set was reached before every source completed.
  2. counts.sourcesComplete vs counts.sourcesQueried — how much of the search finished. An equal pair is a closed answer. See Result completeness.
  3. counts.records — the total number of matches before any page slice, so it does not change as you page.
  4. matchState and matchedName, per record — the labelled strength of the identity match, and whether the registered name or an alias produced the hit. See Searching by date of birth.
Every response labels its own coverage. sourceStatus[] reports every jurisdiction the request touched, individually, with its own status and freshness — so an incomplete search is always labelled as one and never returns as a silently short list.
The four fields, on a complete search
{
  "status": "complete",
  "counts": {
    "records": 3,
    "sourcesQueried": 58,
    "sourcesComplete": 58,
    "sourcesIncomplete": 0,
    "sourcesSkippedByScope": 0
  },
  "records": [
    {
      "matchState": "dob_match",
      "matchedName": { "value": "John A. Doe", "type": "legal" },
      "matchConfidence": 1.0
    }
  ]
}

Where to go next