Orders

One order, one or both searches: create it, track its status, cancel it.

Base URL https://api.offendersearch.app

View as MarkdownCopy the whole reference for an LLM

Create an order

POST /v1/fcra/orders returns 202 with the order at status received, and the work starts in the background. Send an Idempotency-Key header: the same key with the same body returns the original order (with the response header Idempotent-Replayed: true); the same key with a different body is 409 idempotency_conflict.

POST /v1/fcra/orders

curl -X POST https://api.offendersearch.app/v1/fcra/orders \
  -H "X-API-Key: $OFFENDERSEARCH_KEY" \
  -H "Idempotency-Key: 8f1c2a7e-order-889" \
  -H "Content-Type: application/json" \
  -d '{
    "endUserId": "eu_3b9d71c2",
    "permissiblePurpose": "employment",
    "consent": { "obtainedAt": "2026-10-02T13:55:00Z", "method": "esign", "documentRef": "auth-55120" },
    "subject": {
      "firstName": "Jordan", "lastName": "Example", "dob": "1984-02-11",
      "aliases": [{ "firstName": "Jordan", "lastName": "Sample" }],
      "addresses": [{ "state": "IL", "city": "Springfield", "from": "2019-01", "to": null }]
    },
    "useLocation": { "state": "IL" },
    "liveScope": "relevant",
    "searches": [{ "type": "sex_offender" }, { "type": "criminal" }],
    "clientReference": "cra-order-889",
    "callbackUrl": "https://your-cra.example/hooks/offendersearch"
  }'

Field	Required	Description
`endUserId`	yes	A registered, active end user.
`permissiblePurpose`	yes	One of the end user’s purposes.
`consent.obtainedAt`	yes	When you obtained the consumer’s authorization — not in the future.
`consent.method`	yes	`esign`, `wet_signature`, `electronic_click`, `recorded_verbal` or `other`.
`consent.documentRef`	no	Your reference to the signed authorization.
`subject.firstName`, `subject.lastName`	yes	The consumer’s name.
`subject.dob`	yes	A full date of birth (`YYYY-MM-DD`). A year or an age is a `422`.
`subject.middleName`	no	Recorded in the evidence record.
`subject.aliases`	no	Up to 5 other names (`firstName`, `lastName`); each is searched.
`subject.addresses`	no	Up to 20 addresses: `state` (required, two letters), `city`, `from`, `to`. States listed here bring their reporting limits to the criminal search.
`useLocation.state`	no	Where the job or housing is. When it is one of the states with a reporting limit, that limit applies.
`annualSalary`	no	Employment only: $75,000 or more lifts the federal seven-year limit on criminal records.
`liveScope`	no	`relevant` (default): every search is run live in each state in `subject.addresses` plus `useLocation.state`, and in any jurisdiction that produced a candidate. `all`: live in every source that supports a live search for that search type. Every other source is searched from our data, with its as-of date in `coverage`.
`searches`	yes	`[{"type":"sex_offender"}]`, `[{"type":"criminal"}]`, or both — each type at most once.
`clientReference`	no	Your order reference, echoed back and filterable.
`callbackUrl`	no	An `https://` URL that receives this order’s events instead of your webhook endpoint. Requires a configured webhook endpoint, whose secret signs the events (`422 webhook_endpoint_required`).

The order object

GET /v1/fcra/orders/{id}

{
  "id": "fo_7c1e9b2a4d3f",
  "status": "in_progress",
  "createdAt": "2026-10-02T14:01:07Z",
  "updatedAt": "2026-10-02T14:01:51Z",
  "completedAt": null,
  "cancelledAt": null,
  "clientReference": "cra-order-889",
  "endUserId": "eu_3b9d71c2",
  "permissiblePurpose": "employment",
  "useLocation": { "state": "IL" },
  "liveScope": "relevant",
  "controlVersion": "fcra-controls-2026-10-02.1",
  "sandbox": false,
  "eta": { "p50": "2026-10-02T14:03:00Z", "p90": "2026-10-02T14:09:00Z" },
  "searches": [
    { "id": "fs_a14c", "type": "sex_offender", "status": "complete", "result": "clear",
      "recordCount": 0, "withheld": { "insufficient_identifiers": 2 },
      "createdAt": "2026-10-02T14:01:07Z", "startedAt": "2026-10-02T14:01:08Z",
      "completedAt": "2026-10-02T14:01:51Z", "supersededBy": null },
    { "id": "fs_b52e", "type": "criminal", "status": "in_progress", "result": null,
      "recordCount": 0, "withheld": {},
      "createdAt": "2026-10-02T14:01:07Z", "startedAt": "2026-10-02T14:01:09Z",
      "completedAt": null, "supersededBy": null }
  ],
  "consumerPortal": {
    "url": "https://offendersearch.app/consumer/report",
    "accessCode": "K7QF-2MXP-9RDA"
  }
}

Order status	Meaning
`received`	Accepted; nothing has run yet.
`in_progress`	At least one search is running.
`partial`	Some searches are complete and others are not.
`complete`	Every search has finished. Read each search’s `result`.
`cancelled`	Cancelled before it completed.
`error`	Every search in the order errored. Nothing was furnished; place a new order.

eta gives the 50th and 90th percentile completion times for the searches still running, from the last seven days of completions of each search type (with a fixed estimate until there are enough). It is null once the order is complete, cancelled or error.

List and cancel

GET /v1/fcra/orders?status=&clientReference=&cursor= lists your orders, newest first; pass the response’s nextCursor as cursor for the next page. POST /v1/fcra/orders/{id}/cancel cancels an order that has not finished — its queued searches become cancelled — and returns 409 not_cancellable for an order that is already complete, error or cancelled.