Sex Offender Search API · v1.0.0

Batch & CSV search

Up to 1000 lookups per call, JSON or CSV, row in and row out, with per-row fault isolation.

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

One row in, one result out

The batch endpoint is the shape to reach for when you already hold a list: a roster to screen, a CSV export to reconcile, a scheduled re-check of a population. Each row runs through the same engine as POST /v1/search, so every row result carries the search’s status, counts and warnings, and records in the same Record schema with their labelled matchState. A row carries no sourceStatus: its counts.sourcesIncomplete and warnings say whether it was searched to the end.

  • Three accepted body shapes. A bare JSON array of Query objects, a JSON envelope { "queries": [...], ...options } whose non-queries keys apply to every row, or a text/csv body whose header row names Query fields.
  • Input order is preserved. Each result carries its 0-based index, so you can zip results back onto your own rows without matching on identity.
  • Rows are fault-isolated. A row that fails when it is searched is reported with status: "error" in place and never aborts the rest of the batch. A JSON row carrying an unknown field rejects the whole request with 422 before any row runs — CSV columns that are not query fields are ignored instead.
  • 1000 rows per call. A larger batch returns 413.
Billing is per search, not per request. A batch is one HTTP call, but each search in it is metered as one search — a batch of 100 rows is 100 metered searches, each at the graduated per-call rate. A batch runs in Regular mode: it reads the continuously-updated corpus, so there is no per-source live charge. Live re-verification is not offered in a batch.
POST/v1/batchAuth: X-API-Key

Batch / CSV search

Run many lookups in one call — row in, row out. Send a JSON array of queries, a JSON envelope with batch-wide options, or a text/csv body. Each row runs through the same engine as /v1/search and results come back in input order.

The batch endpoint provides legacy CSV-batch parity: one row = one call in, one result out. Post a JSON array of Query objects, a JSON envelope { "queries": [...], ...options } where the non-queries keys (jurisdictions, match, recordTypes, locationScoped, include, deadlineMs, onDeadline) apply to every row, or a text/csv body whose header row names Query fields (firstName,lastName,state,dob,city,zipcode,address,age,q).

Rows run with bounded server-side concurrency and results return in the same order you sent them. A row that fails when it is searched is reported with status: "error" in place — it never aborts the rest of the batch. A JSON row carrying an unknown field is different: the whole request is a 422 before any row runs, exactly as the same row would be on /v1/search. The maximum is 1000 rows per call (a larger batch returns 413).

Billing is per search, not per request. A batch is one HTTP call but each search in it is billed as one search — a batch of 100 rows = 100 metered searches, each at the graduated per-call rate. A batch runs in Regular mode: it reads the continuously-updated corpus, so there is no per-source live charge, and live re-verification is not offered in a batch.

For very large or long-running workloads, the asynchronous endpoint is the other batch-shaped option: submit each search and collect it later, without holding a connection open.

What you can do
  • JSON or CSV. Post a JSON array, a JSON envelope with batch-wide options, or a text/csv body — whatever your pipeline already produces.
  • Row-in / row-out. Results return in input order, each tagged with its 0-based index.
  • Fault-isolated. A row that errors when searched is reported with status:"error" in place and never aborts the batch. A JSON row with an unknown field rejects the whole request with 422.
  • Up to 1000 rows. One call handles up to 1000 queries; larger batches return 413.
Request
# JSON envelope: batch-wide options apply to every row
curl https://api.offendersearch.app/v1/batch \
  -H "X-API-Key: $OFFENDERSEARCH_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "queries": [
      { "firstName": "John", "lastName": "Smith", "state": "FL" },
      { "firstName": "Jane", "lastName": "Doe",   "state": "TX" }
    ],
    "match": "balanced"
  }'

# …or upload a CSV whose header row names Query fields
curl https://api.offendersearch.app/v1/batch \
  -H "X-API-Key: $OFFENDERSEARCH_KEY" \
  -H "Content-Type: text/csv" \
  --data-binary $'firstName,lastName,state\nJohn,Smith,FL\nJane,Doe,TX'
Response
200 OK
{
  "count": 2,
  "results": [
    { "index": 0, "status": "complete",
      "counts": { "records": 1, "sourcesQueried": 58 /* … */ },
      "warnings": [],
      "records": [ /* … scored, de-duplicated records … */ ] },
    { "index": 1, "status": "complete",
      "counts": { "records": 0, "sourcesQueried": 58 /* … */ },
      "warnings": [], "records": [] }
  ]
}

Results are in input order. A failed row is { "index": n, "status": "error", "error": "…" } in place. Returns 413 if the batch exceeds 1000 rows.

Batch sex offender search API request and response fields

POST/v1/batchAuth: X-API-Key or session

Run up to 1000 searches in one call, one result per input row, in input order. Each row is billed as one search.

Request

Body · application/json

Three forms. A JSON array of Query objects; the JSON envelope below, whose options apply to every row; or a text/csv body whose header row names Query fields (firstName,lastName,state,dob,city,zipcode,address,age,q). An unknown key in a JSON row is a 422; an unknown CSV column is ignored. A row may also carry subjectId, clientId and clearanceMode beside its Query fields — each row is one subject being screened, and the row's result then honours that subject's clearances exactly as POST /v1/search does.

FieldTypeDescription
queries
required
array of QueryThe rows, one Query each, at most 1000.
jurisdictions
optional
array of stringRegistry codes to search for every row. Omit to search every US registry.
match
optional
string
one of "strict", "balanced", "broad"
Name matching for every row; same values as SearchRequest.match (default balanced).
recordTypes
optional
array of stringRecord types for every row; ["sex_offender"] is the only value.
locationScoped
optional
booleanSame meaning as SearchRequest.locationScoped, for every row.
include
optional
array of stringAccepted for compatibility; stateData is on every row's records by default. exclude: ["stateData"] drops it batch-wide.
deadlineMs
optional · default 120000
integerPer-row time bound in milliseconds, 1000 to 600000.
onDeadline
optional · default "partial"
string
one of "partial", "error"
What a row does at deadlineMs; same values as SearchRequest.onDeadline.

Response

200 · application/json

Every row was attempted. A row that failed carries status: "error" in place and does not stop the others.

FieldTypeDescription
count
integerRows processed.
results
array of objectOne entry per input row, in input order.
results[].index
integerThe row's 0-based position in the input.
results[].status
stringcomplete, partial or error, with the same meaning as the search response's status.
results[].counts
objectThe same counts a search response carries, for this row.
results[].counts.records
integerTotal matched records for this row.
results[].counts.sourcesQueried
integerRegistries queried for this row.
results[].counts.sourcesIncomplete
integerRegistries not searched to the end for this row. Check it per row.
results[].counts.sourcesComplete
integerRegistries searched to the end for this row.
results[].counts.sourcesSkippedByScope
integerRegistries skipped because locationScoped narrowed the search. 0 unless locationScoped was sent.
results[].counts.recordsReturned
integerRecords this row carries. Equal to records unless the row was capped.
results[].counts.clearedSuppressed
integerRecords a not_this_person clearance removed from this row. Present only when the row sent subjectId.
results[].warnings
array of stringSentences naming anything that shortened this row. [] when nothing did. A batch row has no sourceStatus, so this is its completeness signal with counts.sourcesIncomplete.
results[].records
array of RecordThe row's matched records. [] on an error row.
results[].cleared
array of ClearedEntryPresent only when the row sent subjectId: the people a not_this_person clearance removed from this row. [] when none were.
results[].error
stringPresent only when status is error: why the row failed — the same detail that search returns on its own.
Errors
StatusCodeWhen
401—The X-API-Key header is missing or the key is not valid.
402—The account has no active subscription and no free-trial searches left. detail says which.
402—A free-trial account sent more rows than it has searches left.
413—More than 1000 rows.
422—The body is not a JSON array, a JSON envelope with a queries array, or a CSV with a header row; a JSON row carries an unknown key or a value of the wrong type (detail names the row index and the field); or the batch is empty.

The CSV form

Post a text/csv body whose header row names Query fields — firstName, lastName, state, dob, city, zipcode, address, age, q. Every row is a query, and the response is the same JSON envelope as the JSON form, so a pipeline that already produces a CSV needs no transformation step.

Request
text/csv body
curl https://api.offendersearch.app/v1/batch \
  -H "X-API-Key: $OFFENDERSEARCH_KEY" \
  -H "Content-Type: text/csv" \
  --data-binary @roster.csv

# roster.csv
# firstName,lastName,state,dob
# John,Smith,FL,1980-04-12
# Jane,Doe,TX,
Response
200 OK
{
  "count": 2,
  "results": [
    { "index": 0, "status": "complete",
      "counts": { "records": 1, "sourcesQueried": 58,
                  "sourcesComplete": 58, "sourcesIncomplete": 0 },
      "warnings": [],
      "records": [ /* … */ ] },
    { "index": 1, "status": "partial",
      "counts": { "records": 0, "sourcesQueried": 58,
                  "sourcesComplete": 57, "sourcesIncomplete": 1 },
      "warnings": [ "INCOMPLETE SEARCH: 1 of 58 registries could not be searched to completion — …" ],
      "records": [] }
  ]
}
Read each row’s own counts. Row-level completeness is reported per row, exactly as it is on a single search — row 1 above returned no records, but one jurisdiction did not complete, so it is not determined rather than no match. See Result completeness.

Batch or async?

Both are volume shapes and they compose. Batch is synchronous and row-oriented: you hold the connection, and you get every row back in one response, in order. Async (POST /v1/searches) is one search submitted and collected later — the right shape for a single very broad search, or when you would rather be called back than wait.

BatchAsync
UnitMany queries, one callOne query, collected later
DeliveryIn the response, in input orderPoll (or a one-attempt webhook)
Ceiling1000 rows per callOne search per job; nothing waits on an open connection
Use it forRosters, CSV reconciliation, scheduled re-screensVery broad single searches, unattended jobs

Test batch search in the API sandbox

POST /v1/batch runs on the sandbox with a test key (os_test_…). Send the sex offender test names as rows: each row gets the same answer it gets from POST /v1/search, in input order, 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/batch
curl -X POST "https://sandbox.offendersearch.app/v1/batch" \
  -H "X-API-Key: $OFFENDERSEARCH_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '[
      {
        "firstName": "Clear",
        "lastName": "Visitor"
      },
      {
        "firstName": "Exact",
        "lastName": "Match",
        "dob": "1980-01-01"
      },
      {
        "firstName": "Exact",
        "lastName": "Match"
      }
    ]'

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/batch \
  -H "X-API-Key: $OFFENDERSEARCH_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '[ { "firstName": "Clear", "lastName": "Visitor" }, { "firstName": "Exact", "lastName": "Match", "dob": "1980-01-01" }, { "firstName": "Exact", "lastName": "Match" } ]'

Product overview