# Adverse action & revisions

> Run adverse action through the API as the consumer reporting agency: the pre-adverse notice, the waiting period by use location, the post-adverse notice, pauses on disputes, and report revisions.

- **HTML:** https://offendersearch.app/docs/fcra/adverse-action
- **Base URL (live):** https://api.offendersearch.app — live keys (`os_live_…`)
- **Base URL (sandbox):** https://sandbox.offendersearch.app — test keys (`os_test_…`), never billed; see https://offendersearch.app/docs/fcra/sandbox.md
- **Authentication:** `X-API-Key` request header, on an account with FCRA Partner Access
- **FCRA API reference as markdown:** https://offendersearch.app/docs/fcra.md

## How it works

When a direct or platform partner’s end user is considering a decision against the consumer because of the report, the API runs the two-step adverse-action process as the consumer reporting agency. You name the records the decision rests on; we send the consumer the pre-adverse notice with the report access code and the summary of rights, wait the period the use location requires, and send the post-adverse notice. A dispute pauses the clock; a correction cancels the action and revises the report. The end user still makes the decision — the API never decides for it.

1. Read the adverse items: every record the current report furnishes, in plain language, plus the rule the use location adds (`GET …/adverse-items`).
2. Start the adverse action with the item ids and, where the rule requires it, your written individualized assessment. The pre-adverse notice goes to the consumer’s e-mail on the order; the order’s `adjudication` becomes `pre_adverse_action`. If the mail provider does not accept the notice (`failed` or `skipped`), nothing starts: the request answers 502 `pre_notice_not_delivered` and the action is cancelled with `cancelReason: "pre_notice_not_delivered"`. Fix the address and start again.
3. The waiting period runs from the moment the pre-adverse notice is delivered: the latest of your `waitingDays` (default 7 calendar days), the rule’s business days, and a floor of five business days that applies everywhere. A `waitingDays` below 7 is refused with 422 `waiting_period_too_short`. The consumer may respond to the end user, dispute with us, or do nothing.
4. When it has run, the post-adverse notice goes and `adjudication` becomes `post_adverse_action`. If you change your mind, cancel it; `adjudication` clears.

## What a decision could rest on — GET /v1/fcra/orders/{order_id}/adverse-items

`GET /v1/fcra/orders/{order_id}/adverse-items` · auth: `X-API-Key`

Every record the current report furnishes, as items a decision could rest on, and the rule the use location adds.

### Request

**Path parameters**

| Field | Type | Required / default | Description |
| --- | --- | --- | --- |
| `order_id` | `string` | required | Example `"fo_ee0b34c5b52fd35b"`. |

### Response

**200** (application/json) — 

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `orderId` | `string` |  |  |
| `items` | array of [AdverseItem](https://offendersearch.app/docs/fcra/adverse-action#object-adverseitem) |  |  |
| `rule` | [AdverseRule](https://offendersearch.app/docs/fcra/adverse-action#object-adverserule) or null |  |  |

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 401 | — | No valid `X-API-Key` (the body is `{ "detail": "…" }`, a string). |
| 403 | `fcra_not_enabled` | This account has no active FCRA partner agreement. |
| 403 | `fcra_not_on_trial` | FCRA orders are not available on a trial account. |
| 404 | `not_found` | No such order or adverse action on this account. |

## The AdverseItem object — a record a decision could rest on

One record the current report furnishes, in plain language, with the record id you name on the adverse action.

Returned or accepted by [`GET /v1/fcra/orders/{order_id}/adverse-items`](https://offendersearch.app/docs/fcra/adverse-action#reference-get-v1-fcra-orders-order-id-adverse-items).

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  | The record id (`recordId` on the furnished record). Example `"crim:OH-COURT:1234"`. |
| `type` | `string` — one of `"sex_offender"`, `"criminal"`, `"healthcare"` |  | `sex_offender` or `criminal`: which search the record came from. |
| `searchId` | `string` |  | The search it was furnished by. |
| `text` | `string` |  | A plain-language line, as the pre-adverse notice will quote it. |

## Start adverse action — POST /v1/fcra/orders/{order_id}/adverse-actions

`POST /v1/fcra/orders/{order_id}/adverse-actions` · auth: `X-API-Key`

Sends the pre-adverse notice to the consumer now, with the report access code and the summary of rights, and schedules the post-adverse notice after the waiting period.

### Request

**Path parameters**

| Field | Type | Required / default | Description |
| --- | --- | --- | --- |
| `order_id` | `string` | required | Example `"fo_ee0b34c5b52fd35b"`. |

**Body** (application/json)

| Field | Type | Required / default | Description |
| --- | --- | --- | --- |
| `adverseItemIds` | `array of string` | required | The items the decision rests on, from adverse items. |
| `reasonText` | `string` or null | optional | Kept on the adverse action; not sent to the consumer. |
| `waitingDays` | `integer` or null | optional | Calendar days before the post-adverse notice, 1 to 60. Default 7. The use location's rule may lengthen it. |
| `individualizedAssessment` | `boolean` | optional · default `false` | Whether a written individualized assessment was made. Required where the rule says so. |
| `assessmentText` | `string` or null | optional | The assessment, sent with the pre-adverse notice. |
| `medium` | `object` or null | optional | How the notices go. `{"email": true}` today; postal is not yet available. |

### Response

**201** (application/json) — The adverse action, `pending`.

The body is [the `AdverseAction` object](https://offendersearch.app/docs/fcra/adverse-action#object-adverseaction). An adverse action on an order: the pre-adverse notice sent, the waiting period, the post-adverse notice scheduled or sent, and what paused or cancelled it.

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 401 | — | No valid `X-API-Key` (the body is `{ "detail": "…" }`, a string). |
| 403 | `fcra_not_enabled` | This account has no active FCRA partner agreement. |
| 403 | `fcra_not_on_trial` | FCRA orders are not available on a trial account. |
| 403 | `managed_tier_required` | Your agreement names you as the CRA; run adverse action in your own flow. |
| 404 | `not_found` | No such order or adverse action on this account. |
| 409 | `order_not_complete` |  |
| 409 | `adverse_action_open` | One is already pending or paused on this order. |
| 422 | `consumer_contact_required` | The order has no consumer e-mail (set it with the consumer route). |
| 422 | `unknown_adverse_item` | An id is not in the current report. |
| 422 | `individualized_assessment_required` | The use location's rule requires a written assessment. |

## The AdverseAction object

An adverse action on an order: the pre-adverse notice sent, the waiting period, the post-adverse notice scheduled or sent, and what paused or cancelled it.

Returned or accepted by [`POST /v1/fcra/orders/{order_id}/adverse-actions`](https://offendersearch.app/docs/fcra/adverse-action#reference-post-v1-fcra-orders-order-id-adverse-actions), [`GET /v1/fcra/orders/{order_id}/adverse-actions`](https://offendersearch.app/docs/fcra/adverse-action#reference-get-v1-fcra-orders-order-id-adverse-actions), [`GET /v1/fcra/adverse-actions`](https://offendersearch.app/docs/fcra/adverse-action#reference-get-v1-fcra-adverse-actions), [`GET /v1/fcra/adverse-actions/{aa_id}`](https://offendersearch.app/docs/fcra/adverse-action#reference-get-v1-fcra-adverse-actions-aa-id), [`POST /v1/fcra/adverse-actions/{aa_id}/pause`](https://offendersearch.app/docs/fcra/adverse-action#reference-post-v1-fcra-adverse-actions-aa-id-pause), [`POST /v1/fcra/adverse-actions/{aa_id}/resume`](https://offendersearch.app/docs/fcra/adverse-action#reference-post-v1-fcra-adverse-actions-aa-id-resume), [`POST /v1/fcra/adverse-actions/{aa_id}/cancel`](https://offendersearch.app/docs/fcra/adverse-action#reference-post-v1-fcra-adverse-actions-aa-id-cancel).

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  | The adverse action's id (`aa_…`). Example `"fa_1b2c3d4e5f607182"`. |
| `orderId` | `string` |  | The completed order the decision is based on. |
| `status` | `string` — one of `"pending"`, `"paused"`, `"complete"`, `"cancelled"` |  | `pending` (the clock is running), `paused` (a dispute, or you), `complete` (the post-adverse notice was sent), `cancelled`. |
| `adverseItemIds` | `array of string` |  | The record ids from the report that the decision rests on. Every one must be on the report. |
| `reasonText` | `string` or null |  | Your stated reason, printed on both notices. `null` when you gave none. |
| `waitingDays` | `integer` |  | The calendar days actually waited: the later of yours and the rule's. |
| `rule` | [AdverseRule](https://offendersearch.app/docs/fcra/adverse-action#object-adverserule) or null |  | The use location's rule, when one applied. |
| `individualizedAssessment` | `boolean` |  | `true` when you attached a written individualized assessment. Required where the rule says so. |
| `assessmentText` | `string` or null |  | The assessment text, printed with the pre-adverse notice. `null` when none. |
| `medium` | `object` |  | How the notices go out, for example `{"email": true}`. Mail-only delivery is not offered yet. |
| `preNoticeSentAt` | `string (date-time)` or null |  | When the pre-adverse notice was sent. `null` until it is. |
| `postNoticeScheduledAt` | `string (date-time)` |  | When the post-adverse notice goes (moves when paused and resumed). |
| `postNoticeSentAt` | `string (date-time)` or null |  | When the final notice was sent. `null` until the waiting period ends. |
| `pausedAt` | `string (date-time)` or null |  | When you paused it (a dispute, for example). `null` unless paused. |
| `resumedAt` | `string (date-time)` or null |  | When it was resumed after a pause. `null` unless resumed. |
| `cancelledAt` | `string (date-time)` or null |  | When you cancelled it. `null` unless cancelled. |
| `cancelReason` | `string` or null |  | `report_revised` when a dispute changed the report; otherwise what you sent. |
| `disputeId` | `string` or null |  | The dispute that paused it. |
| `createdAt` | `string (date-time)` |  | When it was started. |
| `updatedAt` | `string (date-time)` |  | When it last changed. |

## Adverse actions on an order — GET /v1/fcra/orders/{order_id}/adverse-actions

`GET /v1/fcra/orders/{order_id}/adverse-actions` · auth: `X-API-Key`



### Request

**Path parameters**

| Field | Type | Required / default | Description |
| --- | --- | --- | --- |
| `order_id` | `string` | required | Example `"fo_ee0b34c5b52fd35b"`. |

### Response

**200** (application/json) — 

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `orderId` | `string` |  |  |
| `adverseActions` | array of [AdverseAction](https://offendersearch.app/docs/fcra/adverse-action#object-adverseaction) |  |  |

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 401 | — | No valid `X-API-Key` (the body is `{ "detail": "…" }`, a string). |
| 403 | `fcra_not_enabled` | This account has no active FCRA partner agreement. |
| 403 | `fcra_not_on_trial` | FCRA orders are not available on a trial account. |
| 404 | `not_found` | No such order or adverse action on this account. |

## List adverse actions — GET /v1/fcra/adverse-actions

`GET /v1/fcra/adverse-actions` · auth: `X-API-Key`

Newest first.

### Request

**Query parameters**

| Field | Type | Required / default | Description |
| --- | --- | --- | --- |
| `status` | `string` — one of `"pending"`, `"paused"`, `"complete"`, `"cancelled"` | optional |  |
| `limit` | `integer` | optional · default `100` | 1 to 500. |

### Response

**200** (application/json) — 

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `adverseActions` | array of [AdverseAction](https://offendersearch.app/docs/fcra/adverse-action#object-adverseaction) |  |  |

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 401 | — | No valid `X-API-Key` (the body is `{ "detail": "…" }`, a string). |
| 403 | `fcra_not_enabled` | This account has no active FCRA partner agreement. |
| 403 | `fcra_not_on_trial` | FCRA orders are not available on a trial account. |

## Retrieve an adverse action — GET /v1/fcra/adverse-actions/{aa_id}

`GET /v1/fcra/adverse-actions/{aa_id}` · auth: `X-API-Key`



### Request

**Path parameters**

| Field | Type | Required / default | Description |
| --- | --- | --- | --- |
| `aa_id` | `string` | required | Example `"fa_1b2c3d4e5f607182"`. |

### Response

**200** (application/json) — 

The body is [the `AdverseAction` object](https://offendersearch.app/docs/fcra/adverse-action#object-adverseaction). An adverse action on an order: the pre-adverse notice sent, the waiting period, the post-adverse notice scheduled or sent, and what paused or cancelled it.

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 401 | — | No valid `X-API-Key` (the body is `{ "detail": "…" }`, a string). |
| 403 | `fcra_not_enabled` | This account has no active FCRA partner agreement. |
| 403 | `fcra_not_on_trial` | FCRA orders are not available on a trial account. |
| 404 | `not_found` | No such order or adverse action on this account. |

## Pause the adverse-action clock — POST /v1/fcra/adverse-actions/{aa_id}/pause

`POST /v1/fcra/adverse-actions/{aa_id}/pause` · auth: `X-API-Key`

Stops the clock with the time that is left. A dispute does this on its own.

### Request

**Path parameters**

| Field | Type | Required / default | Description |
| --- | --- | --- | --- |
| `aa_id` | `string` | required | Example `"fa_1b2c3d4e5f607182"`. |

### Response

**200** (application/json) — 

The body is [the `AdverseAction` object](https://offendersearch.app/docs/fcra/adverse-action#object-adverseaction). An adverse action on an order: the pre-adverse notice sent, the waiting period, the post-adverse notice scheduled or sent, and what paused or cancelled it.

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 401 | — | No valid `X-API-Key` (the body is `{ "detail": "…" }`, a string). |
| 403 | `fcra_not_enabled` | This account has no active FCRA partner agreement. |
| 403 | `fcra_not_on_trial` | FCRA orders are not available on a trial account. |
| 403 | `managed_tier_required` | Your agreement names you as the CRA; run adverse action in your own flow. |
| 404 | `not_found` | No such order or adverse action on this account. |
| 409 | `not_pausable` | Not pending. |

## Resume the adverse-action clock — POST /v1/fcra/adverse-actions/{aa_id}/resume

`POST /v1/fcra/adverse-actions/{aa_id}/resume` · auth: `X-API-Key`

Restarts the clock with the time that was left when it paused.

### Request

**Path parameters**

| Field | Type | Required / default | Description |
| --- | --- | --- | --- |
| `aa_id` | `string` | required | Example `"fa_1b2c3d4e5f607182"`. |

### Response

**200** (application/json) — 

The body is [the `AdverseAction` object](https://offendersearch.app/docs/fcra/adverse-action#object-adverseaction). An adverse action on an order: the pre-adverse notice sent, the waiting period, the post-adverse notice scheduled or sent, and what paused or cancelled it.

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 401 | — | No valid `X-API-Key` (the body is `{ "detail": "…" }`, a string). |
| 403 | `fcra_not_enabled` | This account has no active FCRA partner agreement. |
| 403 | `fcra_not_on_trial` | FCRA orders are not available on a trial account. |
| 403 | `managed_tier_required` | Your agreement names you as the CRA; run adverse action in your own flow. |
| 404 | `not_found` | No such order or adverse action on this account. |
| 409 | `not_paused` |  |

## Cancel adverse action — POST /v1/fcra/adverse-actions/{aa_id}/cancel

`POST /v1/fcra/adverse-actions/{aa_id}/cancel` · auth: `X-API-Key`

No post-adverse notice goes; the order's `adjudication` clears.

### Request

**Path parameters**

| Field | Type | Required / default | Description |
| --- | --- | --- | --- |
| `aa_id` | `string` | required | Example `"fa_1b2c3d4e5f607182"`. |

**Body** (application/json)

| Field | Type | Required / default | Description |
| --- | --- | --- | --- |
| `reason` | `string` | optional · default `"client_cancelled"` | Kept on the adverse action. |

### Response

**200** (application/json) — 

The body is [the `AdverseAction` object](https://offendersearch.app/docs/fcra/adverse-action#object-adverseaction). An adverse action on an order: the pre-adverse notice sent, the waiting period, the post-adverse notice scheduled or sent, and what paused or cancelled it.

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 401 | — | No valid `X-API-Key` (the body is `{ "detail": "…" }`, a string). |
| 403 | `fcra_not_enabled` | This account has no active FCRA partner agreement. |
| 403 | `fcra_not_on_trial` | FCRA orders are not available on a trial account. |
| 403 | `managed_tier_required` | Your agreement names you as the CRA; run adverse action in your own flow. |
| 404 | `not_found` | No such order or adverse action on this account. |
| 409 | `not_cancellable` | Already complete or cancelled. |

## The notices sent for an adverse action — GET /v1/fcra/adverse-actions/{aa_id}/notices

`GET /v1/fcra/adverse-actions/{aa_id}/notices` · auth: `X-API-Key`

The pre- and post-adverse notices, and whether the provider took each.

### Request

**Path parameters**

| Field | Type | Required / default | Description |
| --- | --- | --- | --- |
| `aa_id` | `string` | required | Example `"fa_1b2c3d4e5f607182"`. |

### Response

**200** (application/json) — 

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `notices` | array of [Notice](https://offendersearch.app/docs/fcra/hosted-consent#object-notice) |  |  |

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 401 | — | No valid `X-API-Key` (the body is `{ "detail": "…" }`, a string). |
| 403 | `fcra_not_enabled` | This account has no active FCRA partner agreement. |
| 403 | `fcra_not_on_trial` | FCRA orders are not available on a trial account. |
| 404 | `not_found` | No such order or adverse action on this account. |

## The waiting period by use location

The federal Act sets no number of days; the practice is five business days, and no adverse action here waits less. Several states and cities set their own minimums and require a written individualized assessment before an employment decision on a criminal record. The engine applies the longest period that applies to the order’s use location and purpose; `GET /v1/fcra/adverse-rules` lists every rule with its citation. The rules in force today:

| Use location | Purpose | Minimum | Written assessment |
| --- | --- | --- | --- |
| California | employment | 5 business days | yes |
| Los Angeles, CA | employment | 5 business days | yes |
| San Francisco, CA | employment | 7 days | yes |
| New York City, NY | employment | 5 business days | yes (Article 23-A analysis) |
| New York City, NY | tenant screening | 5 business days | yes |
| New York (state) | employment | 5 business days | yes (Article 23-A factors) |
| Philadelphia, PA | employment | 10 business days | yes |
| Illinois; Chicago | employment | 5 business days | yes |
| Seattle, WA | employment | 2 business days (the five-business-day floor applies) | yes |
| Washington (state); District of Columbia; New Jersey; Minnesota | employment | 5 business days | D.C. yes; others no |
| Everywhere else | any | 5 business days (default `waitingDays` 7 calendar days) | no |

## The AdverseRule object — what the use location requires

The adverse-action rule the use location and purpose add: business days to wait and whether a written individualized assessment is required. The engine applies the longest period that applies.

Returned or accepted by [`GET /v1/fcra/orders/{order_id}/adverse-items`](https://offendersearch.app/docs/fcra/adverse-action#reference-get-v1-fcra-orders-order-id-adverse-items), [`POST /v1/fcra/orders/{order_id}/adverse-actions`](https://offendersearch.app/docs/fcra/adverse-action#reference-post-v1-fcra-orders-order-id-adverse-actions), [`GET /v1/fcra/orders/{order_id}/adverse-actions`](https://offendersearch.app/docs/fcra/adverse-action#reference-get-v1-fcra-orders-order-id-adverse-actions), [`GET /v1/fcra/adverse-actions`](https://offendersearch.app/docs/fcra/adverse-action#reference-get-v1-fcra-adverse-actions), [`GET /v1/fcra/adverse-actions/{aa_id}`](https://offendersearch.app/docs/fcra/adverse-action#reference-get-v1-fcra-adverse-actions-aa-id), [`POST /v1/fcra/adverse-actions/{aa_id}/pause`](https://offendersearch.app/docs/fcra/adverse-action#reference-post-v1-fcra-adverse-actions-aa-id-pause), [`POST /v1/fcra/adverse-actions/{aa_id}/resume`](https://offendersearch.app/docs/fcra/adverse-action#reference-post-v1-fcra-adverse-actions-aa-id-resume), [`POST /v1/fcra/adverse-actions/{aa_id}/cancel`](https://offendersearch.app/docs/fcra/adverse-action#reference-post-v1-fcra-adverse-actions-aa-id-cancel).

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `state` | `string` |  | The two-letter state the rule belongs to. |
| `city` | `string` or null |  | The city the rule is for; `null` for a state-wide rule. |
| `purpose` | `string` |  | The permissible purpose it applies to, usually `employment` or `tenant_screening`. |
| `version` | `string` |  | The rules version. |
| `waitingBusinessDays` | `integer` |  | Business days (Monday–Friday) the consumer gets to respond. |
| `individualizedAssessment` | `boolean` |  | Whether a written individualized assessment must go with the pre-adverse notice. |
| `citation` | `string` |  | The statute or ordinance, for your records and the notice. |
| `note` | `string` |  | What the rule requires in plain words. |
| `alsoApplies` | `array of object` |  | Other rules that apply with a shorter period. |
| `alsoApplies[].citation` | `string` |  | A city ordinance that also applies at this use location. |
| `alsoApplies[].waitingBusinessDays` | `integer` |  | The city's waiting period, when longer than the state's. |

## The adverse-action rules by use location — GET /v1/fcra/adverse-rules

`GET /v1/fcra/adverse-rules` · auth: `X-API-Key`

Every jurisdiction rule the engine applies, with its citation.

### Request

### Response

**200** (application/json) — 

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `version` | `string` |  |  |
| `defaultWaitingDays` | `integer` |  | Calendar days when no rule applies. |
| `rules` | `array of object` |  |  |
| `rules[].state` | `string` |  |  |
| `rules[].city` | `string` or null |  |  |
| `rules[].purpose` | `string` |  |  |
| `rules[].waitingBusinessDays` | `integer` |  |  |
| `rules[].individualizedAssessment` | `boolean` |  |  |
| `rules[].citation` | `string` |  |  |
| `rules[].note` | `string` |  |  |

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 401 | — | No valid `X-API-Key` (the body is `{ "detail": "…" }`, a string). |
| 403 | `fcra_not_enabled` | This account has no active FCRA partner agreement. |
| 403 | `fcra_not_on_trial` | FCRA orders are not available on a trial account. |

## Disputes move the clock

No waiting period runs while a dispute on the order is open. A dispute opened while an adverse action is pending pauses it with the time that was left, and the consumer receives a receipt; an adverse action started while a dispute is open starts `paused`. Resuming is refused with 409 `dispute_open` until every dispute on the order is resolved. When the last open dispute is resolved `verified`, the action resumes. A dispute resolved `modified`, `deleted` or `unable_to_verify` changes what the report furnishes: the report is revised and the adverse action is cancelled with `cancelReason: "report_revised"`, because the notice the consumer received no longer matches the report. Start a new one on the revised report if the decision still stands.

## Record your decision — POST /v1/fcra/orders/{order_id}/adjudication

`POST /v1/fcra/orders/{order_id}/adjudication` · auth: `X-API-Key`

Sets `adjudication` on a complete order (`engaged` or `cleared`). Adverse action sets `pre_adverse_action` and `post_adverse_action` itself.

### Request

**Path parameters**

| Field | Type | Required / default | Description |
| --- | --- | --- | --- |
| `order_id` | `string` | required | Example `"fo_ee0b34c5b52fd35b"`. |

**Body** (application/json)

| Field | Type | Required / default | Description |
| --- | --- | --- | --- |
| `decision` | `string` — one of `"engaged"`, `"cleared"` | required | `engaged` (hired, housed, proceeded) or `cleared` (no action on the report). |

### Response

**200** (application/json) — The order.

The body is [the `Order` object](https://offendersearch.app/docs/fcra/orders#object-order). An FCRA order: its status, its end user and purpose, every search it carries, and the consumer portal access code.

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 401 | — | No valid `X-API-Key` (the body is `{ "detail": "…" }`, a string). |
| 403 | `fcra_not_enabled` | This account has no active FCRA partner agreement. |
| 403 | `fcra_not_on_trial` | FCRA orders are not available on a trial account. |
| 404 | `not_found` | No such order or adverse action on this account. |
| 409 | `order_not_complete` |  |
| 409 | `adverse_action_open` | Cancel the open adverse action first. |

## Report revisions

Revision 1 is the report at completion. Each dispute that changes it writes the next revision: a rebuilt report without the removed records (and with corrections attached), a re-rendered PDF, new hashes, and a receipt that signs the revision number. Every earlier revision stays fetchable — `GET …/report?revision=N`, `GET /v1/fcra/receipts/{id}?revision=N` — so whoever holds an older PDF can still verify it against the receipt that was issued for it. `order.revised` tells you when it happens.

## Every revision of an order's report — GET /v1/fcra/orders/{order_id}/revisions

`GET /v1/fcra/orders/{order_id}/revisions` · auth: `X-API-Key`

Revision 1 at completion, then one per dispute that changed the report. Fetch any revision's report with `?revision=` and its receipt likewise.

### Request

**Path parameters**

| Field | Type | Required / default | Description |
| --- | --- | --- | --- |
| `order_id` | `string` | required | Example `"fo_ee0b34c5b52fd35b"`. |

### Response

**200** (application/json) — 

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `orderId` | `string` |  |  |
| `revision` | `integer` |  | The current revision. |
| `revisions` | array of [ReportRevision](https://offendersearch.app/docs/fcra/adverse-action#object-reportrevision) |  |  |

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 401 | — | No valid `X-API-Key` (the body is `{ "detail": "…" }`, a string). |
| 403 | `fcra_not_enabled` | This account has no active FCRA partner agreement. |
| 403 | `fcra_not_on_trial` | FCRA orders are not available on a trial account. |
| 404 | `not_found` | No such order or adverse action on this account. |

## The ReportRevision object

One revision of an order's report: revision 1 at completion, a new one each time a dispute changes what the report furnishes. Each has its own hashes and its own receipt.

Returned or accepted by [`GET /v1/fcra/orders/{order_id}/revisions`](https://offendersearch.app/docs/fcra/adverse-action#reference-get-v1-fcra-orders-order-id-revisions).

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `revision` | `integer` |  | The revision number: `1` is the report as first completed, each later revision adds one. |
| `reportSha256` | `string` |  | SHA-256 of the revision's JSON report, which the receipt signs. |
| `pdfSha256` | `string` or null |  | SHA-256 of the revision's PDF. `null` when no PDF was produced. |
| `disputeId` | `string` or null |  | The dispute that caused it; `null` for revision 1. |
| `createdAt` | `string (date-time)` |  | When the revision was produced. |

## Consumer contact and notices

Orders from the hosted consent flow carry the consumer’s e-mail and whether they asked for a copy. For an order placed through the API, set them with `PATCH …/consumer` before the order completes (the copy of the report goes out on completion) or before starting adverse action (the notices need an address). Every consumer e-mail — the copy, the two adverse notices, the dispute receipt and resolution — is recorded and listed under `GET …/notices` with whether the provider took it.

## Where the consumer's notices go — PATCH /v1/fcra/orders/{order_id}/consumer

`PATCH /v1/fcra/orders/{order_id}/consumer` · auth: `X-API-Key`

For an API order: the consumer's e-mail for notices and the copy of the report.

### Request

**Path parameters**

| Field | Type | Required / default | Description |
| --- | --- | --- | --- |
| `order_id` | `string` | required | Example `"fo_ee0b34c5b52fd35b"`. |

**Body** (application/json)

| Field | Type | Required / default | Description |
| --- | --- | --- | --- |
| `email` | `string` or null | optional | Where the consumer's notices and copy go. `null` clears it. |
| `phone` | `string` or null | optional | The consumer's phone. `null` clears it. |
| `copyRequested` | `boolean` or null | optional | Send the portal link and access code when the order completes. |
| `locale` | `string` or null — one of `"en"`, `"es"` | optional | `en` or `es` for the consumer's notices. `null` keeps the default. |

### Response

**200** (application/json) — 

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `orderId` | `string` |  |  |
| `consumer` | `object` |  |  |
| `consumer.email` | `string` or null |  |  |
| `consumer.phone` | `string` or null |  |  |
| `consumer.copyRequested` | `boolean` |  |  |
| `consumer.locale` | `string` |  |  |

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 401 | — | No valid `X-API-Key` (the body is `{ "detail": "…" }`, a string). |
| 403 | `fcra_not_enabled` | This account has no active FCRA partner agreement. |
| 403 | `fcra_not_on_trial` | FCRA orders are not available on a trial account. |
| 404 | `not_found` | No such order or adverse action on this account. |

## Every consumer e-mail for an order — GET /v1/fcra/orders/{order_id}/notices

`GET /v1/fcra/orders/{order_id}/notices` · auth: `X-API-Key`

The copy of the report, the adverse-action notices and the dispute receipts sent for this order.

### Request

**Path parameters**

| Field | Type | Required / default | Description |
| --- | --- | --- | --- |
| `order_id` | `string` | required | Example `"fo_ee0b34c5b52fd35b"`. |

### Response

**200** (application/json) — 

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `orderId` | `string` |  |  |
| `notices` | array of [Notice](https://offendersearch.app/docs/fcra/hosted-consent#object-notice) |  |  |

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 401 | — | No valid `X-API-Key` (the body is `{ "detail": "…" }`, a string). |
| 403 | `fcra_not_enabled` | This account has no active FCRA partner agreement. |
| 403 | `fcra_not_on_trial` | FCRA orders are not available on a trial account. |
| 404 | `not_found` | No such order or adverse action on this account. |

---

## Related

- Previous: [Controls & reason codes](https://offendersearch.app/docs/fcra/controls.md)
- Next: [Disputes & reinvestigation](https://offendersearch.app/docs/fcra/disputes.md)
- Index: [FCRA API reference](https://offendersearch.app/docs/fcra.md)