# FCRA API reference

> Every FCRA API endpoint with its request and response fields, and every object it sends and returns: orders, searches, records, disputes, events.

- **HTML:** https://offendersearch.app/docs/fcra/api-reference
- **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

Every endpoint of the FCRA API and every object it sends and returns, in one index. Each endpoint links to its Request and Response tables — every field, its type, whether it is required, its default and an example — and each object links to the one place it is defined. Every partner call authenticates with the `X-API-Key` header on an account with FCRA Partner Access; the receipt and the consumer request are public, and the consumer portal routes take the portal session token. Refusals return `{ "detail": { "code", "message" } }` (see Errors).

## FCRA background check API endpoints

Every endpoint, with a link to its Request and Response tables. Partner routes take `X-API-Key`; the receipt and the consumer request are public; the consumer portal routes take the portal session token.

| Endpoint | What it does |
| --- | --- |
| [`GET /v1/fcra/partner`](https://offendersearch.app/docs/fcra/access#reference-get-v1-fcra-partner) | **Partner status.** Whether this account can place FCRA orders, the purposes its agreement covers, and whether a webhook endpoint is set. Never 403: an account without access gets `enabled: false`. |
| [`POST /v1/fcra/end-users`](https://offendersearch.app/docs/fcra/access#reference-post-v1-fcra-end-users) | **Register an end user.** Registers the employer, landlord or other business a report is for, once, with the permissible purposes it holds and your certification. |
| [`GET /v1/fcra/end-users`](https://offendersearch.app/docs/fcra/access#reference-get-v1-fcra-end-users) | **List end users.** Every end user on this account. |
| [`GET /v1/fcra/end-users/{end_user_id}`](https://offendersearch.app/docs/fcra/access#reference-get-v1-fcra-end-users-end-user-id) | **Retrieve an end user.** One end user. |
| [`PATCH /v1/fcra/end-users/{end_user_id}`](https://offendersearch.app/docs/fcra/access#reference-patch-v1-fcra-end-users-end-user-id) | **Update an end user.** Changes an end user's purposes, or suspends or reinstates it. |
| [`POST /v1/fcra/orders`](https://offendersearch.app/docs/fcra/orders#reference-post-v1-fcra-orders) | **Create an order.** Creates an order for one consumer with a sex offender search, a criminal search or both. Returns 202 with the order at `received`; the searches run in the background and report by webhook. |
| [`GET /v1/fcra/orders`](https://offendersearch.app/docs/fcra/orders#reference-get-v1-fcra-orders) | **List orders.** Your orders, newest first, one page at a time. |
| [`GET /v1/fcra/orders/{order_id}`](https://offendersearch.app/docs/fcra/orders#reference-get-v1-fcra-orders-order-id) | **Retrieve an order.** The order, its status, and the status and result of each search. |
| [`POST /v1/fcra/orders/{order_id}/cancel`](https://offendersearch.app/docs/fcra/orders#reference-post-v1-fcra-orders-order-id-cancel) | **Cancel an order.** Cancels an order that has not finished. Its queued searches become `cancelled`; a search already running finishes. |
| [`GET /v1/fcra/orders/{order_id}/searches/{search_id}`](https://offendersearch.app/docs/fcra/results#reference-get-v1-fcra-orders-order-id-searches-search-id) | **Retrieve a search.** One search with its coverage and every furnished record. |
| [`POST /v1/fcra/searches/{search_id}/reverify`](https://offendersearch.app/docs/fcra/results#reference-post-v1-fcra-searches-search-id-reverify) | **Re-verify a search.** Adds a new search of the same type to the order and marks this one `superseded`, with `supersededBy` pointing at the new one. The order returns to `in_progress`. |
| [`GET /v1/fcra/orders/{order_id}/report`](https://offendersearch.app/docs/fcra/results#reference-get-v1-fcra-orders-order-id-report) | **Get the report.** The furnished report in one document: as JSON, or as the PDF rendered once when the order completed and stored, so its bytes and hash stay the same unless a re-verify completes the order again with a new report. |
| [`GET /v1/fcra/receipts/{order_id}`](https://offendersearch.app/docs/fcra/evidence#reference-get-v1-fcra-receipts-order-id) | **Get the signed receipt.** Public, no API key: the Ed25519-signed receipt for a completed order. It contains no personal data. |
| [`GET /v1/fcra/orders/{order_id}/evidence`](https://offendersearch.app/docs/fcra/evidence#reference-get-v1-fcra-orders-order-id-evidence) | **List evidence.** Every official-source capture taken for the order, with its hash. Only the account that placed the order can read them. |
| [`GET /v1/fcra/orders/{order_id}/evidence/{capture_id}`](https://offendersearch.app/docs/fcra/evidence#reference-get-v1-fcra-orders-order-id-evidence-capture-id) | **Get one capture.** One capture's stored bytes, exactly as kept, as a file download. |
| [`POST /v1/fcra/orders/{order_id}/disputes`](https://offendersearch.app/docs/fcra/disputes#reference-post-v1-fcra-orders-order-id-disputes) | **Open a dispute.** Opens a reinvestigation of records furnished in this order. You receive `dispute.created`, and our team is notified. |
| [`GET /v1/fcra/disputes`](https://offendersearch.app/docs/fcra/disputes#reference-get-v1-fcra-disputes) | **List disputes.** Every dispute on your orders, opened by you or in the consumer portal, earliest due first. |
| [`GET /v1/fcra/disputes/{dispute_id}`](https://offendersearch.app/docs/fcra/disputes#reference-get-v1-fcra-disputes-dispute-id) | **Retrieve a dispute.** A dispute, its due date and its outcome. |
| [`POST /v1/fcra/disputes/{dispute_id}/information`](https://offendersearch.app/docs/fcra/disputes#reference-post-v1-fcra-disputes-dispute-id-information) | **Add information.** Adds the consumer's new information to an open dispute. This is the one 15-day extension: `dueAt` moves 15 days and `extendedAt` records when. |
| [`GET /v1/fcra/webhook-endpoint`](https://offendersearch.app/docs/fcra/webhooks#reference-get-v1-fcra-webhook-endpoint) | **Get the webhook endpoint.** Whether a webhook endpoint is configured, and where. The secret is never returned here. |
| [`PUT /v1/fcra/webhook-endpoint`](https://offendersearch.app/docs/fcra/webhooks#reference-put-v1-fcra-webhook-endpoint) | **Set the webhook endpoint.** Sets your webhook URL. The response carries the signing `secret` when the endpoint is created and when `rotateSecret` is true — store it then. From the dashboard, only an account admin can call it. |
| [`DELETE /v1/fcra/webhook-endpoint`](https://offendersearch.app/docs/fcra/webhooks#reference-delete-v1-fcra-webhook-endpoint) | **Remove the webhook endpoint.** Removes your webhook endpoint. Events are still recorded, with delivery status `no_endpoint`, and listed by `GET /v1/fcra/events`. |
| [`GET /v1/fcra/events`](https://offendersearch.app/docs/fcra/webhooks#reference-get-v1-fcra-events) | **List events.** Every event for your account in the order it happened, each with its delivery status, so a missed delivery is never lost. |
| [`POST /v1/fcra/events/{event_id}/resend`](https://offendersearch.app/docs/fcra/webhooks#reference-post-v1-fcra-events-event-id-resend) | **Resend an event.** Delivers one event to your webhook again, now, and returns it with the result of that attempt. |
| [`POST /v1/consumer/portal/session`](https://offendersearch.app/docs/fcra/consumer-portal#reference-post-v1-consumer-portal-session) | **Open a portal session.** The consumer opens their file for one order with its access code, their last name and their date of birth. Returns a token valid for 30 minutes. |
| [`GET /v1/consumer/portal/report`](https://offendersearch.app/docs/fcra/consumer-portal#reference-get-v1-consumer-portal-report) | **Portal report.** Exactly what was furnished about the consumer in this order, in plain language. Withheld records, other orders and anything not furnished are never shown. |
| [`POST /v1/consumer/portal/disputes`](https://offendersearch.app/docs/fcra/consumer-portal#reference-post-v1-consumer-portal-disputes) | **Dispute from the portal.** The consumer disputes records in this report. It creates the same dispute you would open through the API, with `origin: "consumer_portal"`, and you receive `dispute.created`. |
| [`GET /v1/consumer/portal/disputes`](https://offendersearch.app/docs/fcra/consumer-portal#reference-get-v1-consumer-portal-disputes) | **Portal disputes.** Every dispute on this order — the consumer's and yours — with status, due date and outcome. |
| [`POST /v1/consumer/requests`](https://offendersearch.app/docs/fcra/consumer-portal#reference-post-v1-consumer-requests) | **Consumer file or dispute request.** Public: a consumer without an access code requests their file or disputes information. Identity is verified separately before anything is disclosed. It is what the `/consumer` page sends. |

## FCRA API objects — request and response fields

Every object the FCRA API sends or returns, linked to the one place its fields are defined. A furnished record is the [sex offender Record](https://offendersearch.app/docs/record-object) or the [criminal record](https://offendersearch.app/docs/criminal/record-object) with the FCRA fields added.

| Object | What it is |
| --- | --- |
| [`Address`](https://offendersearch.app/docs/fcra/access#object-address) | An end user's business address. Every field is optional; `state` is a two-letter code and is returned upper-cased. |
| [`Certification`](https://offendersearch.app/docs/fcra/access#object-certification) | The certification the end user gave you that it holds the stated purposes, recorded as you hold it. |
| [`EndUser`](https://offendersearch.app/docs/fcra/access#object-enduser) | An employer, landlord or other business your orders are for. Every order names one by `id`. |
| [`Consent`](https://offendersearch.app/docs/fcra/orders#object-consent) | Your attestation that you obtained the consumer's disclosure and authorization, recorded on the order and in its evidence record. |
| [`Subject`](https://offendersearch.app/docs/fcra/orders#object-subject) | The consumer the order is about. A full date of birth is required: the FCRA controls furnish exact date-of-birth matches only. |
| [`Alias`](https://offendersearch.app/docs/fcra/orders#object-alias) | Another name the consumer has used. Every alias is searched in addition to the subject's name. |
| [`SubjectAddress`](https://offendersearch.app/docs/fcra/orders#object-subjectaddress) | One address in the consumer's history. Each state listed here is searched live (except a registry withheld for the order's purpose) and brings its reporting limits to the criminal search. |
| [`UseLocation`](https://offendersearch.app/docs/fcra/orders#object-uselocation) | Where the job or the housing is. Its state is searched live (except a registry withheld for the order's purpose) and its reporting limits apply. |
| [`SearchSpec`](https://offendersearch.app/docs/fcra/orders#object-searchspec) | One search to run in the order. |
| [`Order`](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. |
| [`Search`](https://offendersearch.app/docs/fcra/results#object-search) | One search in an order: its status, its result, the source-by-source coverage behind it, and the counts of records withheld by reason. |
| [`CoverageRow`](https://offendersearch.app/docs/fcra/results#object-coveragerow) | One source a search covered: whether it was searched live or in our data, when, whether it answered, and what it produced. A `clear` is exactly the sum of these rows. |
| [`FurnishedRecord`](https://offendersearch.app/docs/fcra/results#object-furnishedrecord) | A record that passed every control. It is the product's own record object — the sex offender [Record object](https://offendersearch.app/docs/record-object) or the [criminal record object](https://offendersearch.app/docs/criminal/record-object) — with the FCRA fields below added. On a sex offender record `recordId` and `matchBasis` replace the Record object's own fields of those names. |
| [`Capture`](https://offendersearch.app/docs/fcra/evidence#object-capture) | One piece of official-source evidence taken during a live check: what it is, where it came from, when, and its SHA-256. The bytes are at `GET /v1/fcra/orders/{order_id}/evidence/{capture_id}`. |
| [`Dispute`](https://offendersearch.app/docs/fcra/disputes#object-dispute) | A reinvestigation of furnished records, on the 30-day clock from `receivedAt`. |
| [`PortalRecord`](https://offendersearch.app/docs/fcra/consumer-portal#object-portalrecord) | One furnished record as the consumer sees it: a plain-language summary and the full record. |
| [`PortalDispute`](https://offendersearch.app/docs/fcra/consumer-portal#object-portaldispute) | A dispute as the consumer sees it in the portal. |
| [`WebhookEndpoint`](https://offendersearch.app/docs/fcra/webhooks#object-webhookendpoint) | Your FCRA webhook endpoint. `secret` appears only in the response that created it or rotated it. |
| [`Event`](https://offendersearch.app/docs/fcra/webhooks#object-event) | One FCRA event on your account, with its delivery status. `GET /v1/fcra/events` lists them, oldest first. |
| [`EventData`](https://offendersearch.app/docs/fcra/webhooks#object-eventdata) | The identifiers and statuses an event carries — never personal data. Which keys are present depends on the event type (see the table under Events). |
| [`WebhookDelivery`](https://offendersearch.app/docs/fcra/webhooks#object-webhookdelivery) | The JSON body POSTed to your webhook URL (or the order's `callbackUrl`), signed in `X-Offendersearch-Signature`. |
| [`Error`](https://offendersearch.app/docs/fcra/errors#object-error) | Every refusal the FCRA API raises itself. Switch on `detail.code`; show `detail.message`. A body that fails field validation returns the standard validation body instead, where `detail` is an array of `{ loc, msg, type }` entries. |

---

## Related

- Previous: [The consumer portal](https://offendersearch.app/docs/fcra/consumer-portal.md)
- Next: [Webhooks & events](https://offendersearch.app/docs/fcra/webhooks.md)
- Index: [FCRA API reference](https://offendersearch.app/docs/fcra.md)