Sex Offender Search API · v1.0.0

Search — POST /v1/search

The primary endpoint. Every parameter, the four stages of a search, and nine worked query shapes.

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

How a search works

Every search moves through the same four stages, so the response is predictable and the same query returns the same answer:

  1. Dispatch. Your query is matched across the jurisdictions you targeted — all 58 by default, or the codes in jurisdictions.
  2. Match & verify. Each jurisdiction’s rows are filtered by your match mode, then checked against any dob/age you supplied to confirm identity.
  3. De-duplicate & score. The same person present in multiple jurisdictions is merged into one record whose sources[] lists every corroborating jurisdiction, and each record gets a matchConfidence and matchBasis.
  4. Return. You get records, a per-jurisdiction sourceStatus, and counts — with status: "complete" or "partial".
Stage four is the one to build on. Every jurisdiction the search touched appears in sourceStatus[] with its own status and completeness flag, so coverage is reported per response rather than assumed. See Result completeness & per-source status.

Three companion pages carry the detail this endpoint reference assumes: Matching & confidence for the match modes and the closed strategy vocabulary, Searching by date of birth for matchState, and Jurisdictions for the difference between scoping a search and filtering a result.

Sex offender search API request and response fields

POST/v1/searchAuth: X-API-Key

Search every US sex offender registry in one call. Send a SearchRequest; get back one de-duplicated, scored result set with a status for every registry searched.

Request

Body · application/json
FieldTypeDescription
query
required
QueryWho or where to search for. See the Query object.
jurisdictions
optional
array of string or nullRegistry codes to search, in any case (["TX"], ["tx", "ok"]): a two-letter state or territory code, CNMI, USVI, TRIBAL, or any other id GET /v1/sources lists. A state code also runs the tribal registries that cover that state. Omit it or send null to search every US registry. An unrecognised code is a 422, never an empty result. GET /v1/sources lists every code.
Example ["IL","IN"]
locationScoped
optional · default false
booleanWhen true and query.state is set, search only the registries that cover that state instead of every US registry. query.state alone never narrows which registries are searched. When this narrows the search, counts.sourcesSkippedByScope reports how many registries were skipped.
recordTypes
optional · default ["sex_offender"]
array of string
one of "sex_offender"
Record types to search. This endpoint searches sex offender registries only; criminal records are a separate product at POST /v1/criminal/search. Any other value is a 422.
live
optional
LiveBlockRe-check named registries at query time (Live verification). Omit for the Regular answer. With evidence: "pdf", the same search also prints each named registry's own page to a PDF and always answers 202. See the LiveBlock object.
match
optional · default "balanced"
string
one of "strict", "balanced", "broad"
How widely names match, applied the same way in every registry searched. strict: exact names only. balanced: exact surname, plus nicknames, initials, prefixes, middle names and one-letter typos on the first name. broad: also prefix and typo matches on the surname, and two-letter typos on the first name. query.prefixMatch (which runs the search at broad), query.fuzzy and query.nameMatch override it. An unrecognised value is a 422. See Matching & confidence.
include
optional
array of string
one of "stateData", "raw", "extensive"
Accepted for compatibility and has no effect: stateData is populated on every record by default. To drop it for a lighter payload send exclude: ["stateData"].
exclude
optional
array of string
one of "stateData"
Record fields to leave out. The only value is stateData — the 36-field per-state block that is on every record by default. Send it for a lighter payload on large result sets; the response then lists it in omittedFields. Any other value is a 422.
Example ["stateData"]
proof
optional
ProofRequest or nullPer-registry proof documents, rendered with the search: for each matched record, a document of that registry's own listing as it stood when the search ran, one per registry, so a reviewer can see the entry itself and not only our record of it. An add-on that needs billing on the account: without an active subscription the call answers 402. Leave it unset for a normal search. This is not the verification report: POST /v1/report is the one consolidated PDF of a whole search, available to every key.
subjectId
optional
stringYour id for the person being screened — the resident, visitor, applicant or employee id from your own system, 1–128 characters. Sending it turns clearances on for this search: a person a reviewer marked not_this_person for this subject leaves records[] (or is annotated — see clearanceMode), the response carries cleared[] and counts.clearedSuppressed, and a kept record a clearance names carries a clearance object. Omit it and the response is exactly what it was before clearances existed. Stored only as a per-account hash, never as the id you sent.
Example "resident-48213"
clientId
optional
stringYour id for the facility, tenant or client this subject belongs to, 1–128 characters. A platform that screens for many facilities sends it so that one facility's clearances never reach another facility's results; a direct customer omits it. Meaningful only with subjectId. Stored only as a per-account hash.
Example "facility-07"
clearanceMode
optional · default "suppress"
string
one of "suppress", "annotate", "ignore"
What a not_this_person clearance does to the record it names. suppress (the default whenever subjectId is sent) removes the record from records[] and lists it in cleared[]. annotate keeps the record and attaches its clearance object, for an interface that shows cleared people greyed out. ignore answers as if no clearances existed. A this_person verdict, and a cleared person who has re-surfaced (clearance.staleReason set), are kept and annotated in every mode.
deadlineMs
optional · default 120000
integerHow long the search waits for registries to answer, in milliseconds, from 1000 to 600000. Outside that range is a 422. A registry still unanswered at the bound is marked incompleteReason: "deadline". It bounds the wait, not the response time: a registry already answering is given its own time limit to finish.
onDeadline
optional · default "partial"
string
one of "partial", "error"
What happens at deadlineMs. partial returns what finished, with status: "partial" and every unfinished registry marked in sourceStatus[]. error returns 504 instead.

Response

200 · application/json

The search finished, completely or partially; status says which. When the request's live block resolves to more than two registries, or to a registry whose live check cannot run in-request, the 200 body is instead a live-job acknowledgement — {"searchId", "status": "pending", "mode": "async", "liveSourcesRequested", "poll", "reason"} — and you poll the poll path for the result (GET /v1/searches/{searchId}).

FieldTypeDescription
searchId
stringThis search's id. Pass it to POST /v1/report within 7 days for a verification report.
Example "srch_9f2c1a7b"
status
string
one of "complete", "partial", "running", "pending", "error"
complete: every registry searched was searched to the end. partial: at least one was not — read counts.sourcesIncomplete and sourceStatus[] before treating an empty records as an answer. pending and running appear only on an async job still in progress; error only on an async job that failed.
elapsedMs
integerServer time spent finding the answer, in milliseconds.
usage
LiveUsage or nullPresent only on a live result. See the LiveUsage object. Absent on a Regular answer.
meterEvents
array of MeterEvent or nullPresent only on a live result: the billable units for this search. Absent on a Regular answer.
counts
objectRoll-up counts for this search. Present on every response.
counts.records
integerTotal matched records, before any page or cap. Not the length of records.
counts.recordsReturned
integerRecords in this response. Equal to records unless the response was capped or paginated.
counts.sourcesQueried
integerRegistries this search queried. All registries unless jurisdictions or locationScoped: true narrowed it.
counts.sourcesSkippedByScope
integerRegistries not queried because locationScoped: true narrowed the search. 0 on every default search.
counts.sourcesIncomplete
integerRegistries that were not searched to the end. Above 0, an empty result is not proof of no match; sourceStatus[] names them and says why.
counts.sourcesComplete
integerRegistries that were searched to the end. status is complete exactly when this equals sourcesQueried.
counts.clearedSuppressed
integerRecords a not_this_person clearance removed from records[]. Present only when the request carried subjectId; 0 in annotate and ignore modes. records already excludes them, so records + clearedSuppressed is the count before clearances. Each one is listed in cleared[].
warnings
array of stringOne plain sentence per condition that shortened this answer, naming the registries. Always present; [] means nothing shortened it. An entry starting INCOMPLETE SEARCH: means at least one registry was not searched to the end.
page
integerThe page returned. 1 when the request did not paginate.
perPage
integerThe page size applied. When the request did not paginate, this equals the number of records returned.
totalPages
integerPages at this perPage. 1 when the request did not paginate.
sourceStatus
array of SourceStatusOne entry per registry this search touched. See the SourceStatus object.
records
array of RecordThe matched registrants, de-duplicated across registries and ordered by match strength. The same query returns the same records in the same order.
proof
ProofBundleThe proof documents, when the request asked for them with proof: their status and, when rendered, the fetch tokens. {"status": "none"} on every search that did not ask, which is the normal case.
error
string or nullPresent only when an async job failed (status: "error"): the reason.
capped
booleantrue when the match set was larger than one response carries and was cut to cappedLimit records. Always present. Branch on this field. When true, counts.records is still the full match count; paginate (query.perPage) to reach every record.
cappedReason
string or null
one of "responseLimit"
responseLimit when capped is true; null otherwise.
cappedLimit
integer or nullThe record ceiling applied when capped is true (4000); null otherwise. Read it from the response rather than hard-coding it.
cappedOmittedSources
array of stringRegistries whose records are entirely absent from this response because of the cap. Always present; [] on every uncapped search. Narrow the search or paginate to reach them.
omittedFields
array of stringRecord fields this response leaves out because the request excluded them: [] on a default search (the full record is the default), ["stateData"] when the request sent exclude: ["stateData"]. Always present. It is what tells "not requested" apart from "the registry publishes none" when stateData is null.
cleared
array of ClearedEntryPresent only when the request carried subjectId. One entry per record a not_this_person clearance removed from records[], so an interface can say "2 previously cleared people hidden" and link each to its clearance. [] when nothing was suppressed, including every search in annotate or ignore mode.
202 · application/json

Only when live.evidence is "pdf": the live evidence search was accepted and runs asynchronously. Poll pollUrl — GET /v1/searches/{searchId} — for the records and evidence[]. See Live evidence.

The body is the EvidenceAccepted object. The 202 body of POST /v1/search when the request sent live.evidence: "pdf": a job handle to poll.

Errors
StatusCodeWhen
401—The X-API-Key header is missing or the key is not valid, and no valid dashboard session was sent.
402—The account has no active subscription and no free-trial searches left, or a free-trial search names no one (a trial search needs a first or last name). detail says which.
402—The request sent proof and billing is not enabled on the account.
422—A field is malformed or unrecognised (an unknown jurisdiction code, an unknown match value, a filter placed outside query), or the query narrows on nothing (a first name or a state on its own does not narrow). detail says which.
429overloadedThe service is at capacity. Wait Retry-After seconds and retry. The body is a RateLimitError.
504—deadlineMs was reached and the request sent onDeadline: "error".
504incomplete_no_resultsThe search found no records and at least one registry did not finish (deadline or truncated), so the empty result is not an answer. detail.unfinishedSources names them. Retry, or narrow the query. Sending onDeadline: "partial" explicitly returns a 200 with status: "partial" instead.
503unavailableOnly with live.evidence: "pdf": live evidence is temporarily unavailable. The search was not run and nothing was billed; retry, or omit live.evidence.

The Query object — sex offender search request fields

Who or where to search for. Every field is optional; send what you know. A name, a date of birth or age, or a location narrows the search, and a query that narrows on nothing is refused with a 422 rather than answered with a partial list.

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

FieldTypeDescription
firstName
optional
stringGiven name. Matched exactly, or more widely under the match mode you choose. A first name on its own does not narrow a search; pair it with a surname, a date of birth or a location.
Example "John"
lastName
optional
stringSurname, the primary match key.
Example "Smith"
dob
optional
string (date)Date of birth, YYYY-MM-DD. It narrows: a record whose published birth date, birth year or age contradicts it is excluded. A record that publishes none of those still comes back on the name, labelled matchState: "no_dob_age_year" and unverified: true. Every returned record states how it was checked in matchState. See Searching by date of birth.
Example "1985-06-14"
age
optional
integerAge in years, for when you do not have a date of birth. Matched within ageTolerance years (default ±1) to absorb birthday drift.
Example 39
city
optional
stringResidence city. A record matches when one of its addresses is in that city.
Example "Chicago"
county
optional
stringResidence county. Compared after the words County, Co, Parish and Borough are removed from both sides, so Harris, Harris County and HARRIS CO are the same filter. A record matches when one of its addresses is in that county; a record with no address on file does not match a county filter.
Example "Harris"
state
optional
stringTwo-letter state or territory code (FL) or the full name (Florida), any case. A record matches when it has an address in that state OR that state's registry holds it — addressStates and registrationState on each record tell you which. A value that resolves to no state is a 422. It filters the result; to narrow which registries are searched, add locationScoped: true.
Example "IL"
zipcode
optional
stringResidence ZIP code. The first five digits are compared.
Example "60614"
address
optional
stringStreet address text. Every word must appear in one of the record's addresses. A record with no published address is not excluded by it.
lat
optional
numberLatitude of the centre of a radius search. Send with lng.
Example 41.9
lng
optional
numberLongitude of the centre of a radius search. Send with lat.
Example -87.65
radiusMiles
optional
numberRadius around lat/lng, in miles, up to 100. Defaults to 1 mile when lat and lng are sent without it.
q
optional
stringFree text matched across name, aliases, address, city, state and ZIP. Every word must appear.
fuzzy
optional
booleantrue matches as match: "balanced", false as match: "strict". Overrides match when sent.
prefixMatch
optional
string or array of stringPartial-name search: treat the name you sent as the start of a name, so thom finds Thomas, Thompson and Thomason. "firstName", "lastName", "both", or a list of field names. Matched against aliases as well as the registered name. The prefix must be at least 3 characters (422 otherwise). An exact match always ranks above a prefix match. Sending it runs the rest of the name match at match: "broad".
nameMatch
optional
objectPer-field control of name matching, the fine-grained form of match and prefixMatch (and it overrides both). A strategy you leave out of a field's list is off for that field; exact matching is always on.
nameMatch.firstName
optional
array of string
one of "exact", "prefix", "nickname", "fuzzy", "middle"
Strategies for the first name. prefix needs at least 3 characters; middle (your given name is the person's middle name) needs at least 2.
nameMatch.lastName
optional
array of string
one of "exact", "prefix", "fuzzy"
Strategies for the surname. prefix needs at least 3 characters.
nameMatch.aliases
optional · default true
booleanAlso match against every alias the registry publishes.
faceId
optional
stringNot supported on this endpoint. Sending it is a 422.
createdAtStart
optional
string (date-time)Return only records first recorded at or after this time (source.recordedAt).
createdAtEnd
optional
string (date-time)Return only records first recorded at or before this time (source.recordedAt).
updatedAtStart
optional
string (date-time)Return only records the registry last changed at or after this time (source.sourceUpdatedAt). A record whose registry publishes no such date is kept.
updatedAtEnd
optional
string (date-time)Return only records the registry last changed at or before this time (source.sourceUpdatedAt). A record whose registry publishes no such date is kept.
page
optional
integer1-based page number. Omit page and perPage to get the whole match set in one response, up to cappedLimit records. A page past totalPages returns an empty records array. See Pagination.
perPage
optional
integerRecords per page. Sending it turns pagination on (default 20 when page is sent without it). It is clamped to cappedLimit. A paginated request reaches every match, however many there are.
ageTolerance
optional · default 1
integerYears of slack, 0 to 10, when an age is compared: a searched dob against a published age, or a searched age against a record. On an age search the slack is never less than 1.
onAgeMismatch
optional · default "drop"
string
one of "drop", "flag"
A record that matches on name but whose published age contradicts your dob (or falls outside ageTolerance on an age search). drop omits it. flag returns it labelled matchState: "age_mismatch" and unverified: true.
dobTolerance
optional · default 0
integerBirth-date typo tolerance, 0 to 2, for registries that publish a full date of birth. 0 keeps the exact rule. 1 or 2 returns a record whose date has the same month and day with the year off by up to that many years, or the day and month swapped, labelled matchState: "dob_near_match" and unverified: true; matchBasis says how it differed (dob:near:year+1 means the registry's year is one later than yours; dob:near:dayMonthSwapped). A different month and day is still dropped.

What the envelope guarantees

  • Every top-level key is always present. Test the value, never for key existence. See The Record object.
  • Coverage is reported, not implied. counts.sourcesQueried, sourcesComplete, sourcesIncomplete and sourcesSkippedByScope appear on every response, alongside a sourceStatus[] entry per jurisdiction.
  • Match strength is labelled. matchState, matchBasis, matchDetail, matchedName and matchConfidence let you set your own auto-accept threshold rather than inherit one.
  • The contract is additive. New data lands as a new recordType; existing keys and their meanings do not change under you.
  • Ordering is total and stable. The same query returns the same records in the same order, so paging never reshuffles. See Pagination.

FCRA-regulated use

Results from POST /v1/search are not a consumer report and may not be used for FCRA-covered decisions. Approved consumer reporting agencies and screening platforms under a written FCRA agreement place FCRA orders instead — one order covers a sex offender search, a criminal search or both, with its own controls — see the FCRA API.

Hiring or renting to someone? FCRA workflows are meant primarily for tenant screening and hiring decisions. If a result could help decide whether a person gets a job or a home, run it through the FCRA API, not this endpoint.

Test the sex offender search API in the sandbox

Run POST /v1/search against the sandbox with a test key (os_test_…): fixed test names return a clear answer, a date-of-birth-verified match, possible matches, alias, out-of-state, two-registry and homeless records, the same every time and never billed.

Base URL
https://sandbox.offendersearch.app Not https://api.offendersearch.app, which takes live keys only.
Test key
In the dashboard, Developers → API keys → Create test key. Test keys begin os_test_; send yours in the X-API-Key header.
POST /v1/search
curl -X POST "https://sandbox.offendersearch.app/v1/search" \
  -H "X-API-Key: $OFFENDERSEARCH_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "query": {
        "firstName": "Exact",
        "lastName": "Match",
        "dob": "1980-01-01"
      }
    }'

Try it here

Pick a scenario, edit the request, and run it against the sandbox from this page. The explorer accepts os_test_ keys only and never reaches the live host, so nothing here is billed; the “production” code it copies is for your own backend with a live key.

Create a test key under Dashboard → API keys. Live keys are refused here.
Copy this request as code

Sandbox code uses your test key. Production code calls the live host and is billed per call; run it from your backend with an os_live_… key.

curl -X POST https://sandbox.offendersearch.app/v1/search \
  -H "X-API-Key: $OFFENDERSEARCH_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": { "firstName": "Clear", "lastName": "Visitor" } }'

Product overview