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.appHow a search works
Every search moves through the same four stages, so the response is predictable and the same query returns the same answer:
- Dispatch. Your
queryis matched across the jurisdictions you targeted — all 58 by default, or the codes injurisdictions. - Match & verify. Each jurisdiction’s rows are filtered by your
matchmode, then checked against anydob/ageyou supplied to confirm identity. - 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 amatchConfidenceandmatchBasis. - Return. You get
records, a per-jurisdictionsourceStatus, andcounts— withstatus: "complete"or"partial".
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.
Synchronous search
The primary endpoint. One authenticated call searches the full dataset (or the jurisdictions you name), scores and de-duplicates the matches, and returns them in a single response.
Send a query describing the person you are checking. By default the search covers the full dataset at once; you can narrow it with jurisdictions, tune the fuzzy-match tolerance with match, re-verify named jurisdictions at query time with a live block, request extended detail with include, and cap how long you are willing to wait with deadlineMs.
Only know part of a name? Set prefixMatch to "firstName", "lastName" or "both" and the name you send is treated as the start of a name — thom returns Thomas, Thompson and Thomason — matched against aliases as well as the registered name. Minimum 3 characters. See Partial name search.
The synchronous endpoint answers in a single round trip, and every response reports its own elapsedMs so you can measure it against your own traffic. deadlineMs bounds how long the search waits for jurisdictions to answer: a jurisdiction still unanswered at that point is marked incompleteReason: "deadline" in sourceStatus, and the response comes back status: "partial" with the records from every jurisdiction that finished. It bounds that wait, not the response time — a jurisdiction already answering is given its own time limit to finish. If the search found no records at all and a jurisdiction did not finish, the call answers 504 (incomplete_no_results) instead, unless you sent onDeadline: "partial" explicitly.
Every record you get back carries a matchConfidence score, the matchBasis (why it matched, per field — e.g. lastName:prefix, alias:prefix), a matchedName saying whether the registered name or an alias matched, a dobVerification result, and full per-source provenance with a source citation and a lastCheckedAt timestamp.
- Search all or some jurisdictions. Omit jurisdictions to search every US registry, or pass codes like ["TX","NY"] to scope it.
- Name, DOB, age, or location. Match on any combination. Send at least one field that narrows the search — a surname, dob, age, city, county, ZIP, address, a lat/lng radius or q; a first name or a state on its own is declined with 422. A DOB or age confirms identity and lifts confidence.
- Nickname-aware name search. A firstName is expanded to its nicknames/variants (John ↔ Johnny ↔ Jack) for recall, and the expansion is echoed back in each record’s nicknames[].
- Partial (prefix) name search. Set prefixMatch to search on the start of a name — "thom" returns Thomas, Thompson and Thomason — on the first name, the last name, or both, and across aliases as well as the registered name.
- Geographic radius. Provide lat/lng + radiusMiles (defaults to 1, capped at 100) to find registrants near a point; each address carries its lat/lng, and each record its absconder/predator flags. Radius matching selects on address coordinates, so use a name search when you need selection that is independent of them.
- Free-text and fuzzy street match. Use q for a single free-text field, or address for a fuzzy street-address match.
- Tunable fuzzy matching. Choose strict, balanced, or broad to trade recall for precision uniformly across every jurisdiction.
- Full record by default. Every record carries offenses[], images[] and the 36-field stateData block (vehicles, extra photos, state-specific fields). Send exclude: ["stateData"] for a lighter payload on large result sets.
- De-duplicated people. The same person appearing in several sources is merged into one record with a sources[] array.
- Deadline control. Set deadlineMs to bound how long the search waits for jurisdictions, and onDeadline to choose a partial answer or an error when one does not finish.
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,
"match": "balanced"
}'{
"searchId": "srch_9f2a7c",
"status": "complete",
"elapsedMs": 142,
"counts": { "records": 1, "recordsReturned": 1, "sourcesQueried": 58,
"sourcesComplete": 58, "sourcesIncomplete": 0,
"sourcesSkippedByScope": 0 },
"capped": false,
"cappedReason": null,
"cappedLimit": null,
"cappedOmittedSources": [],
"omittedFields": [],
"page": 1,
"perPage": 1,
"totalPages": 1,
"warnings": [],
"proof": { "status": "none" },
"sourceStatus": [
{ "source": "NJ", "status": "ok", "matched": 1, "fromCache": true,
"note": null, "incomplete": false, "incompleteReason": null,
"cappedOmitted": false },
{ "source": "PA", "status": "ok", "matched": 1, "fromCache": true,
"note": null, "incomplete": false, "incompleteReason": null,
"cappedOmitted": false }counts summarizes the search; sourceStatus reports every jurisdiction touched (ok / error / restricted / no_coverage) with its own incomplete flag; records holds the scored, de-duplicated matches.
Only know part of a name? Set prefixMatch and the name you send is treated as the START of a name — "thom" returns Thomas, Thompson and Thomason. Use "firstName", "lastName", or "both". Minimum 3 characters (shorter returns 422). Prefixes are matched against every recorded alias as well as the registered name, and each record’s matchedName tells you which one matched. An exact match always ranks above a prefix match.
{
"query": {
"lastName": "thom",
"prefixMatch": "lastName",
"state": "TX"
}
}
// Returns Thomas, Thompson, Thomason, Thom, Hamilton-Thompson ...
// but NOT Bothomley - we anchor at the start of a name, never mid-word.
//
// Each record reports how it matched:
// "matchBasis": ["lastName:prefix", "name_match"]
// "matchedName": { "value": "Ana Thompson", "type": "legal" }
// "matchConfidence": 0.60 <- capped: a prefix hit is a CANDIDATEprefixMatch: "both" prefix-matches the first and last name together; a record must satisfy both. Add a dob or age to keep precision while widening recall — a confirmed DOB lifts the confidence cap that a partial-name match otherwise carries.
{
"query": {
"firstName": "thom",
"lastName": "and",
"prefixMatch": "both",
"dob": "1980-04-12"
}
}
// -> Thomas Anderson, Thompson Andrews, ...prefixMatch is the shorthand. Send nameMatch when you want to drive matching yourself: list exactly the strategies you want per field. Anything you leave out is OFF for that field; exact matching is always on and cannot be disabled. nameMatch overrides both prefixMatch and match. firstName accepts prefix, nickname, fuzzy and middle; lastName accepts prefix and fuzzy; aliases toggles alias matching (default true).
{
"query": {
"firstName": "Robert",
"lastName": "thom",
"nameMatch": {
"firstName": [],
"lastName": ["prefix"],
"aliases": true
}
}
}
// firstName: [] exact only - no nickname widening, so no "Bob"
// lastName: ["prefix"] Thompson, Thomas, Thomason ...
// aliases: true also match aliases (the default)
//
// -> Robert Thompson (not Bob Thompson)Pass jurisdiction codes in jurisdictions to limit the search. Naming ["TX"] searches the Texas registry, plus the tribal registries that cover Texas.
{
"query": { "firstName": "Maria", "lastName": "Lopez" },
"jurisdictions": ["TX"]
}Combine lat/lng with radiusMiles for a geographic search — useful for “who lives near this school / address”. A search that names no one is always paginated; see Pagination.
{
"query": {
"lat": 40.7357,
"lng": -74.1724,
"radiusMiles": 5
}
}Pass q to search across name, aliases, address, city, county, state and ZIP in a single field — the legacy-style catch-all. Every word must appear.
{
"query": { "q": "john doe newark nj" },
"match": "broad"
}Use match: "strict" for exact names only, a dob to exclude anyone whose published birth date contradicts it, and a live block to re-verify the matched jurisdictions at query time — a point-in-time answer you can defend. Up to two registries that support an in-request check run inline; otherwise the 200 is a job to poll.
{
"query": { "firstName": "John", "lastName": "Doe", "dob": "1980-04-12" },
"match": "strict",
"live": { "scope": "matched" }
}stateData (vehicles, extra photos, state-specific fields) is on every record by default. On a large result set, exclude it; the response lists it in omittedFields.
{
"query": { "firstName": "John", "lastName": "Doe" },
"exclude": ["stateData"]
}Lower deadlineMs and send onDeadline: "partial" to stop waiting on slow jurisdictions sooner: anything unanswered at the bound is marked deadline in sourceStatus and you get a partial answer, even an empty one, instead of a 504. A jurisdiction already answering still gets its own time limit, so this shortens the wait rather than guaranteeing a response time.
{
"query": { "lastName": "Doe" },
"deadlineMs": 4000,
"onDeadline": "partial"
}Sex offender search API request and response fields
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
| Field | Type | Description |
|---|---|---|
| query required | Query | Who or where to search for. See the Query object. |
| jurisdictions optional | array of string or null | Registry 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 | boolean | When 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 | LiveBlock | Re-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 null | Per-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 | string | Your 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 | string | Your 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 | integer | How 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
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}).
| Field | Type | Description |
|---|---|---|
| searchId | string | This 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 | integer | Server time spent finding the answer, in milliseconds. |
| usage | LiveUsage or null | Present only on a live result. See the LiveUsage object. Absent on a Regular answer. |
| meterEvents | array of MeterEvent or null | Present only on a live result: the billable units for this search. Absent on a Regular answer. |
| counts | object | Roll-up counts for this search. Present on every response. |
| counts.records | integer | Total matched records, before any page or cap. Not the length of records. |
| counts.recordsReturned | integer | Records in this response. Equal to records unless the response was capped or paginated. |
| counts.sourcesQueried | integer | Registries this search queried. All registries unless jurisdictions or locationScoped: true narrowed it. |
| counts.sourcesSkippedByScope | integer | Registries not queried because locationScoped: true narrowed the search. 0 on every default search. |
| counts.sourcesIncomplete | integer | Registries 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 | integer | Registries that were searched to the end. status is complete exactly when this equals sourcesQueried. |
| counts.clearedSuppressed | integer | Records 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 string | One 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 | integer | The page returned. 1 when the request did not paginate. |
| perPage | integer | The page size applied. When the request did not paginate, this equals the number of records returned. |
| totalPages | integer | Pages at this perPage. 1 when the request did not paginate. |
| sourceStatus | array of SourceStatus | One entry per registry this search touched. See the SourceStatus object. |
| records | array of Record | The matched registrants, de-duplicated across registries and ordered by match strength. The same query returns the same records in the same order. |
| proof | ProofBundle | The 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 null | Present only when an async job failed (status: "error"): the reason. |
| capped | boolean | true 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 null | The record ceiling applied when capped is true (4000); null otherwise. Read it from the response rather than hard-coding it. |
| cappedOmittedSources | array of string | Registries 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 string | Record 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 ClearedEntry | Present 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. |
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.
| Status | Code | When |
|---|---|---|
| 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. |
| 429 | overloaded | The 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". |
| 504 | incomplete_no_results | The 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. |
| 503 | unavailable | Only 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.
| Field | Type | Description |
|---|---|---|
| firstName optional | string | Given 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 | string | Surname, 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 | integer | Age 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 | string | Residence city. A record matches when one of its addresses is in that city. Example "Chicago" |
| county optional | string | Residence 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 | string | Two-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 | string | Residence ZIP code. The first five digits are compared. Example "60614" |
| address optional | string | Street 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 | number | Latitude of the centre of a radius search. Send with lng.Example 41.9 |
| lng optional | number | Longitude of the centre of a radius search. Send with lat.Example -87.65 |
| radiusMiles optional | number | Radius around lat/lng, in miles, up to 100. Defaults to 1 mile when lat and lng are sent without it. |
| q optional | string | Free text matched across name, aliases, address, city, state and ZIP. Every word must appear. |
| fuzzy optional | boolean | true matches as match: "balanced", false as match: "strict". Overrides match when sent. |
| prefixMatch optional | string or array of string | Partial-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 | object | Per-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 | boolean | Also match against every alias the registry publishes. |
| faceId optional | string | Not 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 | integer | 1-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 | integer | Records 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 | integer | Years 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 | integer | Birth-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,sourcesIncompleteandsourcesSkippedByScopeappear on every response, alongside asourceStatus[]entry per jurisdiction. - Match strength is labelled.
matchState,matchBasis,matchDetail,matchedNameandmatchConfidencelet 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.appNothttps://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 theX-API-Keyheader.
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.
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" } }'Every test name: Sex offender search test namesPostman collectionSex Offender API sandbox