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.appOne 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
Queryobjects, a JSON envelope{ "queries": [...], ...options }whose non-querieskeys apply to every row, or atext/csvbody 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 with422before any row runs — CSV columns that are not query fields are ignored instead. - 1000 rows per call. A larger batch returns
413.
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.
- 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.
# 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'{
"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
Run up to 1000 searches in one call, one result per input row, in input order. Each row is billed as one search.
Request
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.
| Field | Type | Description |
|---|---|---|
| queries required | array of Query | The rows, one Query each, at most 1000. |
| jurisdictions optional | array of string | Registry 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 string | Record types for every row; ["sex_offender"] is the only value. |
| locationScoped optional | boolean | Same meaning as SearchRequest.locationScoped, for every row. |
| include optional | array of string | Accepted for compatibility; stateData is on every row's records by default. exclude: ["stateData"] drops it batch-wide. |
| deadlineMs optional · default 120000 | integer | Per-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
Every row was attempted. A row that failed carries status: "error" in place and does not stop the others.
| Field | Type | Description |
|---|---|---|
| count | integer | Rows processed. |
| results | array of object | One entry per input row, in input order. |
| results[].index | integer | The row's 0-based position in the input. |
| results[].status | string | complete, partial or error, with the same meaning as the search response's status. |
| results[].counts | object | The same counts a search response carries, for this row. |
| results[].counts.records | integer | Total matched records for this row. |
| results[].counts.sourcesQueried | integer | Registries queried for this row. |
| results[].counts.sourcesIncomplete | integer | Registries not searched to the end for this row. Check it per row. |
| results[].counts.sourcesComplete | integer | Registries searched to the end for this row. |
| results[].counts.sourcesSkippedByScope | integer | Registries skipped because locationScoped narrowed the search. 0 unless locationScoped was sent. |
| results[].counts.recordsReturned | integer | Records this row carries. Equal to records unless the row was capped. |
| results[].counts.clearedSuppressed | integer | Records a not_this_person clearance removed from this row. Present only when the row sent subjectId. |
| results[].warnings | array of string | Sentences 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 Record | The row's matched records. [] on an error row. |
| results[].cleared | array of ClearedEntry | Present only when the row sent subjectId: the people a not_this_person clearance removed from this row. [] when none were. |
| results[].error | string | Present only when status is error: why the row failed — the same detail that search returns on its own. |
| Status | Code | When |
|---|---|---|
| 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.
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,{
"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": [] }
]
}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.
| Batch | Async | |
|---|---|---|
| Unit | Many queries, one call | One query, collected later |
| Delivery | In the response, in input order | Poll (or a one-attempt webhook) |
| Ceiling | 1000 rows per call | One search per job; nothing waits on an open connection |
| Use it for | Rosters, CSV reconciliation, scheduled re-screens | Very 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.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/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.
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" } ]'Every test name: Sex offender search test namesPostman collectionSex Offender API sandbox