# FCRA API
> The FCRA API reference: one order covers a sex offender and a criminal search, with controls, a disputes endpoint, a consumer portal and signed webhooks.
- **HTML:** https://offendersearch.app/docs/fcra

## Introduction

The FCRA API is for **approved consumer reporting agencies and screening platforms under a written FCRA agreement**. It is an orders API: one order carries a sex offender search, a criminal search, or both, for one consumer, under one end user, one permissible purpose and one consent attestation. Orders run in the background and report back by signed webhook.

- **One order, both products.** `searches: [{"type":"sex_offender"},{"type":"criminal"}]` — each search has its own status, result and records.
- **The FCRA facts travel with the order.** The end user, the permissible purpose and your consent attestation are recorded on every order, with the subject’s full date of birth.
- **Live where it matters.** Each search runs live in every state the subject lived in and where the job or housing is, and in our data everywhere else. A source-by-source `coverage` table shows exactly what is behind every result, including a `clear`.
- **Controls before anything is furnished.** Exact date-of-birth matching, state restrictions, the seven-year rules for criminal records, dispute suppressions and re-verification with the official source. Anything that fails is withheld and counted by reason.
- **Disputes are an endpoint.** Open a reinvestigation on a furnished record, follow it on the 30-day clock, and receive the outcome by webhook.
- **A consumer portal on every order.** The access code on each order lets the consumer see exactly what was furnished about them and dispute any item.
- **Evidence anyone can check.** Every live search keeps what the official source returned, with its hash; the stored PDF carries a QR code to a public page where anyone can confirm the file against its signed receipt without uploading it.

> The standard Sex Offender and Criminal Search APIs are not a consumer report and may not be used for FCRA-covered decisions. FCRA-regulated use runs only through this API, under FCRA Partner Access. FCRA pricing is quoted per partner — contact us for pricing.

## What FCRA workflows are for

FCRA workflows are meant **primarily for tenant screening and hiring decisions** — any time a result will help decide whether to rent to someone or whether to hire them (including contractors, volunteers in paid programs and promotions or retention). Those decisions are regulated by the Fair Credit Reporting Act, so the search has to run as a consumer report: with a permissible purpose, a consent attestation, accuracy controls, and a dispute path for the consumer.

- **Use the FCRA API** for: tenant and rental-applicant screening, pre-employment and employment screening, and any other eligibility decision your agreement covers (`permissiblePurpose`: `employment`, `tenant_screening`, `consumer_written_instructions`, `legitimate_business_need`).
- **Use the standard Sex Offender and Criminal Search APIs** for everything that is not an eligibility decision about a consumer — community safety, platform trust and safety signals reviewed by your own team, research, and monitoring.
- **Not sure?** If a person could be turned down for housing or a job because of the result, it is an FCRA workflow.

## The lifecycle of an order

1. **Register the end user** once — the employer or landlord the report is for, with its permissible purposes and your certification.
2. **Create the order** with the subject, the purpose, your consent attestation, where the job or housing is, and the searches to run. You get `202` and an order id at once.
3. **Each search runs** — live in the relevant jurisdictions and in our data elsewhere, matched, filtered through the controls, re-verified — and moves from `queued` to `complete` (or `unavailable` when a source cannot answer). The order is `partial` while some searches are done and others are not.
4. **You are told** by `search.completed` and `order.completed` webhooks, or you poll the order.
5. **You read the results** — the furnished records with their match evidence, and the counts of what was withheld and why — and adjudicate under your own process.
6. **If the consumer disputes**, through you or the consumer portal, a reinvestigation runs on the 30-day clock and the outcome reaches every partner that received the record.

## Your first order

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"
  }'
```

## Endpoint index

| Method | Path | What it does |
| --- | --- | --- |
| POST | `/v1/fcra/end-users` | Register an employer, landlord or other end user, with its permissible purposes and your certification. |
| GET | `/v1/fcra/end-users/{id}` | Retrieve an end user. `PATCH` updates its purposes or suspends it. |
| POST | `/v1/fcra/orders` | Create an order with a sex offender search, a criminal search, or both. Returns 202. |
| GET | `/v1/fcra/orders/{id}` | The order, its status, and the status and result of each search. |
| POST | `/v1/fcra/orders/{id}/cancel` | Cancel an order that has not completed. |
| GET | `/v1/fcra/orders/{id}/searches/{searchId}` | One search with the records furnished. |
| POST | `/v1/fcra/searches/{searchId}/reverify` | Run a search again; the old one is marked superseded. |
| GET | `/v1/fcra/orders/{id}/report` | The furnished report, as JSON or the stored PDF. |
| GET | `/v1/fcra/orders/{id}/evidence` | Every official-source capture taken for the order, with its hash. |
| GET | `/v1/fcra/orders/{id}/evidence/{captureId}` | One capture: exactly what the official source returned, as stored. |
| GET | `/v1/fcra/receipts/{orderId}` | A public signed receipt for a completed order. No key, no personal data. |
| POST | `/v1/fcra/orders/{id}/disputes` | Open a dispute on furnished records. |
| GET | `/v1/fcra/disputes/{id}` | A dispute, its due date and its outcome. `GET /v1/fcra/disputes` lists them. |
| POST | `/v1/fcra/disputes/{id}/information` | Add the consumer’s new information — the one 15-day extension. |
| PUT | `/v1/fcra/webhook-endpoint` | Set your webhook URL and get its signing secret. `GET` and `DELETE` too. |
| GET | `/v1/fcra/events` | Every event for your account, to poll when a webhook is missed. |
| POST | `/v1/fcra/events/{id}/resend` | Deliver one event to your webhook again. |

## Contents

- [Access & end users](https://offendersearch.app/docs/fcra/access.md) — How access is switched on, the permissible purposes, and registering your end users.
- [Orders](https://offendersearch.app/docs/fcra/orders.md) — One order, one or both searches: create it, track its status, cancel it.
- [Results & records](https://offendersearch.app/docs/fcra/results.md) — Per-search results, live and data coverage by source, furnished records and withheld counts.
- [Evidence & verification](https://offendersearch.app/docs/fcra/evidence.md) — Official-source captures, the stored PDF, the signed receipt and how to verify a report.
- [Controls & reason codes](https://offendersearch.app/docs/fcra/controls.md) — Every control, in the order it runs, for each search type — with the reason code it writes.
- [Disputes & reinvestigation](https://offendersearch.app/docs/fcra/disputes.md) — Open a dispute on a furnished record, follow the 30-day clock, and get the outcome.
- [The consumer portal](https://offendersearch.app/docs/fcra/consumer-portal.md) — The access code on every order, what the consumer sees, and how their disputes reach you.
- [Webhooks & events](https://offendersearch.app/docs/fcra/webhooks.md) — Signed, retried, identifiers-only events — and the list to poll if one is missed.
- [Sandbox](https://offendersearch.app/docs/fcra/sandbox.md) — Deterministic test subjects for every outcome, with no live calls and no charges.
- [Errors](https://offendersearch.app/docs/fcra/errors.md) — Every status and stable error code, and what to do about each.

Request FCRA Partner Access: https://offendersearch.app/contact?topic=fcra

---

## Related

- Index: [Offendersearch API documentation](https://offendersearch.app/docs.md)