# Orders

> Create an FCRA order covering a sex offender search, a criminal search or both, with an idempotency key, then track it through received, partial and complete.

- **HTML:** https://offendersearch.app/docs/fcra/orders
- **Base URL:** https://api.offendersearch.app
- **Authentication:** `X-API-Key` request header, on an account with FCRA Partner Access
- **FCRA API reference as markdown:** https://offendersearch.app/docs/fcra.md

## 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

```bash
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}

```json
{
  "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`.

---

## Related

- Previous: [Access & end users](https://offendersearch.app/docs/fcra/access.md)
- Next: [Results & records](https://offendersearch.app/docs/fcra/results.md)
- Index: [FCRA API reference](https://offendersearch.app/docs/fcra.md)