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.appTwo 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 ask | Omit live | Send a live block |
| What you get | The 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. |
| Speed | One round trip | ≤2 sources may run inline; more → asynchronous |
| Price | Base per-call rate only | Base 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
liveblock, nousageblock — a Regular search is billed as a single call at the base per-call rate. statusis"complete"when every jurisdiction finished. Every jurisdiction the request touched reports its own row insourceStatus[], 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:
{
"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.
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
usageblock reports how many completed. - A live check that fails is not billed. Only sources that complete are metered, and the
usageblock 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 theliveblock and the same search also prints it to a PDF — live evidence, $0.25 per registry document.
"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.
{
"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.
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.
- Coverage. Every jurisdiction with its code and name.
- Health. Typical latency and the time of the last successful update, per jurisdiction.
curl https://api.offendersearch.app/v1/sources \
-H "X-API-Key: $OFFENDERSEARCH_KEY"[
{
"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
The coverage catalog: every registry the API searches, by code, with its coverage and health. No API key required.
Request
No parameters.
Response
A JSON array with one SourceInfo entry per registry:
| Field | Type | Description |
|---|---|---|
| id | string | The registry code. Send it in jurisdictions.Example "IL" |
| name | string | The registry's name. Example "Illinois Sex Offender Registry" |
| covers | array of string | State and territory codes this registry covers. |
| registries | integer | How 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 | object | The 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 | object | Current health of this registry. |
| health.lastSuccessAt | string (date-time) or null | When this registry's data last updated successfully, ISO-8601; null if it never has. |
| health.typicalLatencyMs | integer or null | Typical response time in milliseconds; null when not measured. |
| health.ageSeconds | number or null | Seconds 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.
| Field | Type | Description |
|---|---|---|
| jurisdictions optional | array of string or null | Registry 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.
| Field | Type | Description |
|---|---|---|
| liveChecks | integer | Registries re-checked live that completed. The true count, even when the charge reached its ceiling. Example 1 |
| liveChargeUsd | number | The live charge for this search, in US dollars: $0.02 per completed registry, at most $2.00. Example 0.02 |
| capped | boolean | true when the charge reached the $2.00 per-search ceiling.Example false |
| display | string | A 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.
| Field | Type | Description |
|---|---|---|
| kind | string | The unit's kind. live_source is one completed live registry check.Example "live_source" |
| quantity | integer | How many units. Example 1 |
| chargeCeilingUsd | number or null | The per-search ceiling that applies to these units, in US dollars; null when none applies.Example 2 |