FCRA API
FCRA-regulated orders for approved consumer reporting agencies and screening platforms: one order covers a sex offender search, a criminal search or both, with controls before anything is furnished, a disputes endpoint, a consumer portal and signed webhooks.
Livehttps://api.offendersearch.appSandboxhttps://sandbox.offendersearch.appWays to use the FCRA API
Pick the row that is you. Every row runs on the same orders, controls, evidence, signed report, disputes and consumer portal; the differences are who the consumer reporting agency is and how an order starts.
| You are | Mode | How an order starts | What we run for you | What stays with you |
|---|---|---|---|---|
| An employer hiring, a landlord screening applicants, a volunteer organization or school vetting people | direct | Invite the person (hosted consent flow in your branding), or place an order yourself and attest to the consent you collected, from the dashboard or the API | The disclosure and authorization, the searches with live verification, the signed report, the copy to the consumer, the pre- and post-adverse notices, the portal and disputes, continuous checks | The decision |
| A platform, staffing firm or property manager screening for your clients | platform | Register each client as an end user; invite their applicants under your branding, or place orders through the API from your product | Everything in the row above, for every client | The decision, and certifying each client |
| A consumer reporting agency building a registry and criminal layer into your own reports | cra | Place orders through the API with your consent attestation | The searches with live verification, the controls, the evidence, the signed report, reinvestigations and the consumer file | Consent, notices, adverse action, the consumer’s copy, the decision |
- Start: apply under Access & end users; build against the sandbox meanwhile.
- Hosted consent (direct and platform): Hosted consent. Your own consent (any mode): Orders.
- Where it searches: Search scope. After the report: Adverse action & revisions, Continuous checks.
- Your brand on it: White-label & branding.
Introduction
The FCRA API is for approved partners under a written FCRA agreement in one of three modes: an employer, landlord or organization screening for itself (direct), a platform screening for its clients under its own brand (platform), or a consumer reporting agency that wants the data (cra). In the first two we are the consumer reporting agency: the hosted consent flow, the consumer’s copy, the adverse-action notices and continuous checks are ours to run. 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 in the address history you send and in the state where the job or housing is, and in our data everywhere else. A source-by-source
coveragetable shows exactly what is behind every result, including aclear. - Or verify only the matches. With
liveScope: "matches", a consumer with no possible record is answered from our current data, and every possible record is confirmed with the agency that keeps it before it can be reported. A record the agency has not confirmed yet is held — never reported — and the search says so. - 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 check keeps hash-pinned evidence of what it returned; the stored PDF carries a QR code to a public page where anyone can confirm the file against its signed receipt without uploading it.
- Where it searched, stated. Every order carries its search plan: the counties around each address, the states, the sources behind each, and the counties with no county-level source. Preview it before you order.
- Hosted consent, in your branding. Invite the consumer; they read the disclosure and the rights summary, give their details and sign; the signed consent is stored with the order. You choose what the page asks for: their address history, or their Social Security number so we trace the address history for them (never stored). Identity verification is coming soon.
- Adverse action, run for you. Name the records a decision rests on; the pre-adverse notice goes with the report access code, the waiting period follows the use location’s rule, the post-adverse notice follows. A dispute pauses the clock; a correction revises the report with a new signed receipt.
- Continuous checks. Enroll a subject with an evergreen authorization; an order is placed only when a reportable change appears.
FCRA order turnaround
Orders are asynchronous: POST /v1/fcra/orders returns 202 and an order id at once, and the result arrives by webhook. Measured on production:
- Sex-offender search, typical order: about 2–6 seconds from the request to the finished, signed report.
liveScope: "all"(every one of the 57 registries that support a live check, checked live): under 2 minutes.- Criminal search: 90% of checks are done in under 30 minutes.
liveScope: "matches": a consumer with no possible record is answered without waiting on a live check. A possible record the agency has not confirmed yet is held: the search completesincompletewithverification_pending, and is updated when the agency answers (held records).- Report and webhook:
order.completedand the signed report arrive within seconds of the last search finishing.
A source that cannot answer makes the result incomplete, never clear. The coverage table on each search shows exactly which sources the times cover. Overview and comparison: FCRA turnaround.
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. A search used for those decisions runs as an FCRA order: you state the permissible purpose and attest to the consumer’s consent, and the order applies the accuracy controls and gives the consumer a dispute path. Whether a particular decision falls under the FCRA is yours to determine under your agreement.
- 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, run it as an FCRA order.
The lifecycle of an order
- Register the end user once — the employer or landlord the report is for, with its permissible purposes and your certification.
- Create the order with the subject, the purpose, your consent attestation, where the job or housing is, and the searches to run. You get
202and an order id at once. - Each search runs — live in the relevant jurisdictions and in our data elsewhere, matched, filtered through the controls, re-verified — and moves from
queuedtocomplete(orunavailablewhen its sources cannot be reached). The order ispartialwhile some searches are done and others are not. - You are told by
search.completedandorder.completedwebhooks, or you poll the order. - 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.
- If the consumer disputes, through you or the consumer portal, a reinvestigation runs on the 30-day clock; you receive the outcome, and a correction or deletion reaches every partner that received the record.
Your first order
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_0b44acbeefeaa7d7",
"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", "exclusions": "all" }],
"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 evidence capture taken for the order’s live checks, with its hash. |
| GET | /v1/fcra/orders/{id}/evidence/{captureId} | One capture’s stored bytes, with its hash and its kind. |
| 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. |
| POST | /v1/fcra/application | Apply for FCRA Partner Access: company, compliance contact, purposes, mode and certifications. |
| POST | /v1/fcra/search-plans | Preview where an order would search: counties, states, sources and gaps, before placing it. |
| GET | /v1/fcra/orders/{id}/scope | The full search plan an order ran under. |
| POST | /v1/fcra/invitations | Invite a consumer to the hosted consent flow in your branding; the signed consent is stored with the order. |
| GET | /v1/apply/{token} | What the consumer sees: the disclosure, the rights summary, the state notices and the authorization. |
| GET | /v1/fcra/orders/{id}/consent-documents | The signed consent behind an order; upload your own for an API order. |
| PUT | /v1/fcra/branding | Your name, logo and colour on the consumer-facing surfaces. |
| POST | /v1/fcra/orders/{id}/adverse-actions | Send the pre-adverse notice now and the post-adverse notice after the waiting period the use location requires. |
| POST | /v1/fcra/orders/{id}/adjudication | Record your decision on a complete order. |
| GET | /v1/fcra/orders/{id}/revisions | Every revision of the report, each with its own receipt. |
| POST | /v1/fcra/monitors | Enroll a subject in a continuous check; an order is placed only when a reportable change appears. |
Documentation
Each section below is its own page, with worked examples and a markdown alternate at /docs/fcra/{section}.md.
Start here: who you are, which mode that is, and the whole journey from invitation to decision.
Access & end usersHow access is switched on, the permissible purposes, and registering your end users.
POST /v1/fcra/end-users · GET /v1/fcra/end-usersFCRA API sandbox & test subjectsA test key, a sandbox end user, and test subjects for every order outcome, exclusions included. No live calls, no charges.
White-label & brandingYour name, logo and colour on the consent flow, the e-mails and the portal; the agency named where the law puts it.
PUT /v1/fcra/branding · GET /v1/fcra/brandingOne order, one or both searches: create it, track its status, cancel it.
POST /v1/fcra/orders · GET /v1/fcra/orders/{id} · POST /v1/fcra/orders/{id}/cancelHosted consentInvite the consumer; we collect the disclosure, the authorization and their details, and place the order.
POST /v1/fcra/invitations · GET /v1/apply/{token} · POST /v1/apply/{token}/completeSearch scopeWhere an order searches and why: the plan, the policy, the gaps, and the identity layer.
POST /v1/fcra/search-plans · GET /v1/fcra/orders/{id}/scopeResults & recordsPer-search results, live and data coverage by source, furnished records, held records and withheld counts.
GET /v1/fcra/orders/{id}/searches/{searchId} · GET /v1/fcra/orders/{id}/reportEvidence & verificationOfficial-source captures, the stored PDF, the signed receipt and how to verify a report.
GET /v1/fcra/orders/{id}/evidence · GET /v1/fcra/orders/{id}/evidence/{captureId} · GET /v1/fcra/receipts/{orderId}Controls & reason codesEvery control, in the order it runs, for each search type — with the reason code it writes.
Continuous checksEnroll a subject once; an order is placed only when a reportable change appears.
POST /v1/fcra/monitors · POST /v1/fcra/monitors/{id}/evaluatePre- and post-adverse notices sent for you, the waiting period by jurisdiction, disputes that pause the clock, and report revisions with their own receipts.
POST /v1/fcra/orders/{id}/adverse-actions · GET /v1/fcra/orders/{id}/revisionsDisputes & reinvestigationOpen a dispute on a furnished record, follow the 30-day clock, and get the outcome.
POST /v1/fcra/orders/{id}/disputes · GET /v1/fcra/disputes/{id}The consumer portalThe access code on every order, what the consumer sees, and how their disputes reach you.
Every endpoint and every object, each linked to its request and response fields.
Webhooks & eventsSigned, retried, identifiers-only events — and the list to poll if one is missed.
GET /v1/fcra/events · POST /v1/fcra/events/{id}/resendErrorsEvery status and stable error code, and what to do about each.
Get access
FCRA Partner Access is enabled after a written FCRA agreement that sets your permissible purposes. FCRA orders are priced per order, with no packages: checks are $4.95 per order, criminal court search included, with no court fees or extra charges, with volume discounts above 100 checks a month. Build against the free sandbox meanwhile. Request FCRA Partner Access, or read the program overview.