FCRA API reference
Every endpoint and every object, each linked to its request and response fields.
Livehttps://api.offendersearch.appSandboxhttps://sandbox.offendersearch.appEvery 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 | 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 | 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 | List end users. Every end user on this account. |
| GET /v1/fcra/end-users/{end_user_id} | Retrieve an end user. One end user. |
| 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 | 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 | List orders. Your orders, newest first, one page at a time. |
| 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 | 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} | Retrieve a search. One search with its coverage and every furnished record. |
| 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 | 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} | 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 | 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} | Get one capture. One capture's stored bytes, exactly as kept, as a file download. |
| 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 | List disputes. Every dispute on your orders, opened by you or in the consumer portal, earliest due first. |
| GET /v1/fcra/disputes/{dispute_id} | Retrieve a dispute. A dispute, its due date and its outcome. |
| 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 | Get the webhook endpoint. Whether a webhook endpoint is configured, and where. The secret is never returned here. |
| 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 | 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 | 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 | 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 | 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 | 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 | 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 | Portal disputes. Every dispute on this order — the consumer's and yours — with status, due date and outcome. |
| 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 or the criminal record with the FCRA fields added.
| Object | What it is |
|---|---|
| Address | An end user's business address. Every field is optional; state is a two-letter code and is returned upper-cased. |
| Certification | The certification the end user gave you that it holds the stated purposes, recorded as you hold it. |
| EndUser | An employer, landlord or other business your orders are for. Every order names one by id. |
| Consent | Your attestation that you obtained the consumer's disclosure and authorization, recorded on the order and in its evidence record. |
| 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 | Another name the consumer has used. Every alias is searched in addition to the subject's name. |
| 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 | 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 | One search to run in the order. |
| Order | An FCRA order: its status, its end user and purpose, every search it carries, and the consumer portal access code. |
| 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 | 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 | A record that passed every control. It is the product's own record object — the sex offender Record object or the 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 | 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 | A reinvestigation of furnished records, on the 30-day clock from receivedAt. |
| PortalRecord | One furnished record as the consumer sees it: a plain-language summary and the full record. |
| PortalDispute | A dispute as the consumer sees it in the portal. |
| WebhookEndpoint | Your FCRA webhook endpoint. secret appears only in the response that created it or rotated it. |
| Event | One FCRA event on your account, with its delivery status. GET /v1/fcra/events lists them, oldest first. |
| 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 | The JSON body POSTed to your webhook URL (or the order's callbackUrl), signed in X-Offendersearch-Signature. |
| 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. |