Batch & CSV search

One row in, one result out

Bulk cached lookups: each row runs through the same cached engine as POST /v1/criminal/search, so results are identical to running them individually, and every result carries the same Record schema and the same envelope — counts, warnings, pagination, labelled status. Live verification is not offered in batch — there is no live block on a batch row, and a batch never fans out to a live source, so every row is cache-only and every status is complete or error, never partial.

• Three accepted body shapes. A bare JSON array of query objects, a JSON envelope { "queries": [...], ...defaults } 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 validation is returned with status: "error" in place and never aborts the rest of the batch — and is not billed.
• 1000 rows per call. A larger batch returns 413 batch_too_large; a batch of zero rows is a 422 empty_batch.

The JSON form

Post either a bare array of query objects, or an envelope { "queries": [...], ...defaults } whose non-queries keys are batch-wide defaults applied to every row. A per-row value overrides the default for that row — so nameStrategy: "prefix" at the envelope level applies to all rows unless a row sets its own. Each query object is flat — the fields from a query, not wrapped in { "query": … }.

curl -X POST https://api.offendersearch.app/v1/criminal/batch \
  -H "X-API-Key: $OFFENDERSEARCH_KEY" \
  -H "Content-Type: application/json" \
  -d '[
        { "lastName": "Hamilton", "state": "TX" },
        { "firstName": "Alex", "state": "TX" }
      ]'

{
  "queries": [
    { "lastName": "Hamilton", "state": "TX" },
    { "lastName": "Example",  "state": "IL", "firstName": "Chris" }
  ],
  "include": ["sourceData"],
  "nameStrategy": "prefix"
}

The CSV form

Post a text/csv body whose header row names query fields, one query per line. Empty cells are dropped (they do not override a batch-wide default), and a UTF-8 BOM is handled. Unknown columns are ignored, so you can post a CSV export unchanged — a caseRef or note column is dropped rather than rejected. The endpoint still requires lastName per row.

curl -X POST https://api.offendersearch.app/v1/criminal/batch \
  -H "X-API-Key: $OFFENDERSEARCH_KEY" \
  -H "Content-Type: text/csv" \
  --data-binary $'firstName,lastName,state,caseRef\nAlex,Hamilton,TX,FILE-0142\nJordan,,IL,FILE-0143\n'

{
  "count": 2,
  "results": [
    { "index": 0, "status": "complete",
      "counts": { "records": 12, "recordsReturned": 12, "sourcesQueried": 0,
                  "sourcesComplete": 0, "sourcesIncomplete": 0 },
      "warnings": [], "page": 1, "perPage": 50, "totalPages": 1,
      "sourceStatus": [], "cappedOmittedSources": [], "omittedFields": ["sourceData"],
      "records": [],
      "legal": { "notice": "Not a consumer report. …" } },
    { "index": 1, "status": "error",
      "error": "a lastName predicate is required — an unbounded query returns a lottery, not an answer",
      "counts": { "records": 0, "recordsReturned": 0, "sourcesQueried": 0,
                  "sourcesComplete": 0, "sourcesIncomplete": 0 },
      "records": [] }
  ],
  "meterEvents": [ { "kind": "criminal_call", "quantity": 1, "chargeCeilingUsd": null } ]
}

Guardrails & unbounded rows

A batch is one HTTP call, but each row is a full search and each row is validated on its own. The whole-batch guardrails are size limits; the per-row guardrail is the same surname requirement as a single search.