Adverse action & revisions

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.

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.

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, GET /v1/fcra/orders/{order_id}/adverse-actions, GET /v1/fcra/adverse-actions, GET /v1/fcra/adverse-actions/{aa_id}, POST /v1/fcra/adverse-actions/{aa_id}/pause, POST /v1/fcra/adverse-actions/{aa_id}/resume, POST /v1/fcra/adverse-actions/{aa_id}/cancel.

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:

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, POST /v1/fcra/orders/{order_id}/adverse-actions, GET /v1/fcra/orders/{order_id}/adverse-actions, GET /v1/fcra/adverse-actions, GET /v1/fcra/adverse-actions/{aa_id}, POST /v1/fcra/adverse-actions/{aa_id}/pause, POST /v1/fcra/adverse-actions/{aa_id}/resume, POST /v1/fcra/adverse-actions/{aa_id}/cancel.

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.

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.

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.

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.

Test FCRA orders on the sandbox server

With a test key (os_test_…) every account is a sandbox FCRA partner on the sandbox server, with the same last-name rules. Register an end user, then place orders against it; nothing is billed. An order finishes right after the 202: read it once with GET /v1/fcra/orders/{orderId}.

Base URL

https://sandbox.offendersearch.app Not https://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 the X-API-Key header.

curl -X POST "https://sandbox.offendersearch.app/v1/fcra/end-users" \
  -H "X-API-Key: $OFFENDERSEARCH_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "name": "Sample Staffing LLC",
      "permissiblePurposes": [
        "employment"
      ],
      "certification": {
        "text": "End user certifies it will use reports only for employment purposes.",
        "version": "v1",
        "certifiedAt": "2026-10-01T12:00:00Z"
      }
    }'

curl -X POST "https://sandbox.offendersearch.app/v1/fcra/orders" \
  -H "X-API-Key: $OFFENDERSEARCH_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "endUserId": "{endUserId}",
      "permissiblePurpose": "employment",
      "consent": {
        "obtainedAt": "2026-10-01T12:00:00Z",
        "method": "esign"
      },
      "subject": {
        "firstName": "Pat",
        "lastName": "Records",
        "dob": "1980-01-01"
      },
      "searches": [
        {
          "type": "sex_offender"
        },
        {
          "type": "criminal"
        }
      ]
    }'

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.

curl -X POST https://sandbox.offendersearch.app/v1/fcra/end-users \
  -H "X-API-Key: $OFFENDERSEARCH_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Sample Staffing LLC", "permissiblePurposes": [ "employment" ], "certification": { "text": "End user certifies it will use reports only for employment purposes.", "version": "v1", "certifiedAt": "2026-10-01T12:00:00Z" } }'

Every test name: FCRA API sandbox orders·Postman collection·FCRA API sandbox