Sex Offender Search API · v1.0.0

Regular & Live modes, and source coverage

Two modes — Regular (continuously updated) and Live — per-record lastCheckedAt, and the live coverage catalog.

Livehttps://api.offendersearch.appSandboxhttps://sandbox.offendersearch.app

Two modes: Regular, and Live verification

There is one search endpoint, and which mode you get is decided by the request body. Omit the live block and you get the Regular answer — the continuously-updated data we hold, close to live, returned in one round trip. Send a live block and the API re-verifies the named jurisdiction(s) in real time. Both modes run every result through the same match logic and return the same response envelope, so a Regular record and a Live record agree about identity and rank together — the choice is about how the answer is obtained, not about a different product.

Regular (default)Live verification
How you askOmit liveSend a live block
What you getThe continuously-updated answer, assembled into one ranked result. Close to live, and returned in one round trip.Re-verifies the named jurisdiction(s) at query time, then merges the fresh results with the Regular answer through the same matcher.
SpeedOne round trip≤2 sources may run inline; more → asynchronous
PriceBase per-call rate onlyBase rate plus $0.02 per completed live source, to a $2.00 ceiling per search

Regular — the default, and what almost every caller wants

The Regular answer reads the continuously-updated data we hold, assembled into one ranked result, and returns in a single round trip. It is close to live — current enough for the great majority of screening decisions — and it is the mode you get when you say nothing. Every record still carries its own lastCheckedAt, so currency is a value you read off the answer rather than an assumption about the service.

  • No live block, no usage block — a Regular search is billed as a single call at the base per-call rate.
  • status is "complete" when every jurisdiction finished. Every jurisdiction the request touched reports its own row in sourceStatus[], so an incomplete search is labelled, never returned as a silently short list.
  • Each record carries sources[].lastCheckedAt — when we last confirmed that person at that jurisdiction. There is no separate freshness flag; the timestamp is the answer.

Live verification — checked at the source, right now

A live check is interactive and real-time — the mode to reach for when a decision needs a current, moment-of-decision verification of a specific person. Send a live block and the API re-verifies at the named jurisdiction(s) as part of your request, then merges the fresh results with the Regular answer:

Ask for a live re-verification
{
  "query": { "firstName": "John", "lastName": "Doe", "dob": "1980-04-12" },
  "live": { "jurisdictions": ["TX"] }
}
  • jurisdictions: [codes] — an explicit list of jurisdiction codes to re-verify live.
  • scope: "matched" — re-verify every jurisdiction that produced a Regular hit for this query.

Send one of the two. A two-letter code names that state’s own registry.

A live-verified record carries a fresh lastCheckedAt; the merge lets a live result supersede the Regular copy of the same person, and the whole set is re-ranked. A person only the live pull found is added; a person only the Regular answer held stays — nothing is lost.

Records the live check did not return — liveResult

Every record of a live search carries liveResult, so a record the registry did not return is never mistaken for one it confirmed:

  • confirmed_live — the live answer included this record.
  • not_found_live — the record's registry was checked live in this search and the check completed, but its answer did not include this record. It is returned from our records. It may have been removed, sealed or expunged, or it may fall outside what the registry's live search returns.
  • not_checked — the record's registry was not checked live in this search, or its check could not complete.

The sourceStatus row of each registry whose live check completed carries notFoundLive — how many of its records the live answer did not include — and when that is above zero warnings[] carries one sentence beginning NOT FOUND IN LIVE CHECK: that names the registries and the date of our records. It does not change status. A Regular search has neither field.

An empty live result is not, on its own, evidence of absence. Before treating an empty records array as “not found”, check counts.sourcesIncomplete == 0 first — > 0 means at least one source could not be searched to the end. Full discipline in Result completeness.

Sync vs async — a latency rule, not a product difference

A live check of ≤2 sources, each of which supports a synchronous check, runs synchronously — one 200, results inline. More than two sources, or any source without a synchronous check, runs asynchronously: a 200 whose body is a job acknowledgement (status: "pending", mode: "async") with a searchId and a poll path. Both paths run the same live checks and return the same envelope — the only difference is whether you hold the connection open or collect the result later. Regular searches and synchronous live searches never produce a job to poll. See Async search & webhooks for the poll handshake.

What a live check costs

  • +$0.02 per live source that completes. A Regular search has no such charge — it is the base per-call rate only.
  • The live charge for one search never exceeds $2.00. This is a price ceiling, not a source limit: every source you request runs, and the usage block reports how many completed.
  • A live check that fails is not billed. Only sources that complete are metered, and the usage block always reports the true count even when the charge is capped.
  • Need the registry’s own page, not only its records? Add "evidence": "pdf" to the live block and the same search also prints it to a PDF — live evidence, $0.25 per registry document.
usage — reported on live searches
"usage": { "liveChecks": 2, "liveChargeUsd": 0.04, "capped": false,
           "display": "2 live checks · $0.04" }

Currency is answered per request, not per claim

It is carried on every record. sources[].lastCheckedAt is when that jurisdiction’s copy of the record was last confirmed, and source.lastCheckedAt is the same for the jurisdiction that supplied the record’s top-level values. Read it rather than a general statement about the dataset: it is a contract field, and it answers the question for the exact record in front of you. For a jurisdiction as a whole, GET /v1/sources publishes health.lastSuccessAt.

Provenance on a record
{
  "source": {
    "jurisdiction": "NJ",
    "registryName": "State Sex Offender Registry",
    "recordUrl": "https://…",
    "recordedAt": "2026-08-13T04:12:00Z",
    "lastCheckedAt": "2026-08-13T04:12:00Z",
    "sourceUpdatedAt": "2026-08-11T00:00:00Z"
  },
  "sources": [ /* one entry per corroborating jurisdiction */ ]
}

sourceUpdatedAt is the date the jurisdiction itself states it last changed the record; it is null where a jurisdiction publishes no such date. Running at volume? POST /v1/searches lets you submit searches and collect them later instead of holding a connection open.

GET/v1/sources

List sources

The coverage catalog: every jurisdiction we cover, by code, name, and live health.

The live coverage catalog: every jurisdiction the API covers, with its code, display name, and health signals such as typical latency and when its data last updated. Use it to render your own coverage UI or to decide which jurisdictions to name.

No API key is required. A key sent with the request is ignored.

What you can do
  • Coverage. Every jurisdiction with its code and name.
  • Health. Typical latency and the time of the last successful update, per jurisdiction.
Request
curl https://api.offendersearch.app/v1/sources \
  -H "X-API-Key: $OFFENDERSEARCH_KEY"
Response
200 OK
[
  {
    "id": "NJ",
    "name": "New Jersey Sex Offender Internet Registry",
    "covers": ["NJ"],
    "registries": 1,
    "scope": "state",
    "status": "live",
    "legal": { "commercialUse": "unknown" },
    "health": { "lastSuccessAt": "2026-07-25T09:14:00Z", "typicalLatencyMs": 380,
                "ageSeconds": 3600, "freshFor": ["daily", "weekly"] }
  },
  {
    "id": "TX",
    "name": "Texas DPS Sex Offender Registry",
    "covers": ["TX"],
    "registries": 1,
    "scope": "state",
    "status": "live",
    "legal": { "commercialUse": "unknown" },
    "health": { "lastSuccessAt": "2026-07-25T09:14:00Z", "typicalLatencyMs": 410,
                "ageSeconds": 3600, "freshFor": ["daily", "weekly"] }
  }
  /* … one entry per registry … */
]

Registry coverage API: GET /v1/sources response fields

GET/v1/sourcesNo API key

The coverage catalog: every registry the API searches, by code, with its coverage and health. No API key required.

Request

No parameters.

Response

200 · application/json

A JSON array with one SourceInfo entry per registry:

FieldTypeDescription
id
stringThe registry code. Send it in jurisdictions.
Example "IL"
name
stringThe registry's name.
Example "Illinois Sex Offender Registry"
covers
array of stringState and territory codes this registry covers.
registries
integerHow many registries this entry represents: 1 for a state registry, more for an entry that groups the tribal registries.
Example 1
scope
string
one of "state", "national"
state or national.
status
string
one of "building", "live"
live when the registry is searchable.
legal
objectThe registry's terms of use for commercial purposes.
legal.commercialUse
string
one of "allowed", "restricted", "prohibited", "unknown"
allowed, restricted, prohibited or unknown: what the registry's terms say about commercial use. Records from every US registry are returned in search results whatever this says.
health
objectCurrent health of this registry.
health.lastSuccessAt
string (date-time) or nullWhen this registry's data last updated successfully, ISO-8601; null if it never has.
health.typicalLatencyMs
integer or nullTypical response time in milliseconds; null when not measured.
health.ageSeconds
number or nullSeconds since lastSuccessAt; null when lastSuccessAt is null.
health.freshFor
array of string
one of "daily", "weekly"
Labels for how recent the registry's data is (daily, weekly). Informational: each registry contributes to every search whatever this says.

The LiveBlock object — live verification request fields

Asks for named registries to be re-checked at query time (Live verification). Omit it for the Regular answer. Send jurisdictions or scope, not both. Add evidence: "pdf" to also receive each named registry's own page as a PDF.

Returned or accepted by POST /v1/search, POST /v1/search.

FieldTypeDescription
jurisdictions
optional
array of string or nullRegistry ids or two-letter codes to re-check live. A two-letter code names that state's or territory's own registry; any other id GET /v1/sources lists names that registry.
Example ["TX"]
scope
optional
string or null
one of "matched"
"matched" re-checks the registries that produced the Regular matches, instead of naming them.
evidence
optional
string or null
one of "none", "pdf"
"pdf": besides the live check, print each registry named in jurisdictions (up to 20) — its own public website, every result page and each matching registrant's detail page — to one PDF per registry behind a cover page, and return the documents with the records. The search then always answers 202 and is returned by GET /v1/searches/{searchId}, whose body carries evidence[]. $0.25 per completed registry document, $5.00 ceiling per search, on top of the live search's normal charge; an incomplete document bills nothing. Omit it, or send "none", for today's search, byte for byte. See Live evidence.

The LiveUsage object — live check charge fields

The live-check charge summary. Present only on the result of a search that carried a live block — the inline response, or the polled result of a live job; its presence is the signal that the answer was re-verified live.

Returned or accepted by POST /v1/search, GET /v1/searches/{searchId}, POST /v1/search.

FieldTypeDescription
liveChecks
integerRegistries re-checked live that completed. The true count, even when the charge reached its ceiling.
Example 1
liveChargeUsd
numberThe live charge for this search, in US dollars: $0.02 per completed registry, at most $2.00.
Example 0.02
capped
booleantrue when the charge reached the $2.00 per-search ceiling.
Example false
display
stringA one-line summary for display.
Example "1 live checks · $0.02"

The MeterEvent object — billable units on a live result

One billable unit behind a live result. Present only on a live result, in meterEvents[].

Returned or accepted by POST /v1/search, GET /v1/searches/{searchId}, POST /v1/search.

FieldTypeDescription
kind
stringThe unit's kind. live_source is one completed live registry check.
Example "live_source"
quantity
integerHow many units.
Example 1
chargeCeilingUsd
number or nullThe per-search ceiling that applies to these units, in US dollars; null when none applies.
Example 2

Product overview