The FCRA Orders API
One order covers a sex-offender search, a criminal search, or both — with the end user, the permissible purpose and your consent attestation on the order, signed webhooks when each search finishes, match evidence on every furnished record, a disputes endpoint, and a consumer portal code on every order.
For approved consumer reporting agencies and screening platforms under a written FCRA agreement. Standard self-serve search is separate and is not a consumer report.
curl -X POST https://api.offendersearch.app/v1/fcra/orders \
-H "X-API-Key: $OFFENDERSEARCH_FCRA_KEY" \
-H "Idempotency-Key: cra-order-889" \
-H "Content-Type: application/json" \
-d '{
"endUserId": "eu_northwind",
"permissiblePurpose": "employment",
"consent": { "obtainedAt": "2026-10-02T13:55:00Z", "method": "esign" },
"subject": { "firstName": "Jordan", "lastName": "Example", "dob": "1984-02-11" },
"useLocation": { "state": "IL" },
"searches": [{ "type": "sex_offender" }, { "type": "criminal" }],
"callbackUrl": "https://your-cra.example/hooks/offendersearch"
}'Built the way screening platforms already work
One order covers a sex-offender search, a criminal search, or both — with the end user, purpose and consent recorded on the order.
One order, both datasets
An order runs a sex-offender search, a criminal search, or both, for one consumer. Each search has its own status, result and records, so a slow court never holds up a finished registry answer.
The FCRA facts travel with the order
The end user, the permissible purpose and your consent attestation are part of the order itself, with the consumer’s full date of birth and where the job or housing is — so the controls and the evidence record always know the context.
Asynchronous, with signed webhooks
Create an order and get an id at once. search.completed and order.completed arrive by HMAC-signed webhook, retried with backoff, with an events list to poll if one is missed — identifiers and statuses only, never personal data.
Match evidence on every record
Each furnished record says how it matched, which identifiers agreed, which official source holds it, when it was obtained and when it was re-verified for this order.
Disputes are an endpoint
Open a reinvestigation on a furnished record with one call, follow it on the 30-day clock, and receive the outcome by webhook — with corrections sent to every partner that received the record.
A consumer portal on every order
Each order carries an access code for its consumer. Put it in your pre-adverse notice: they see exactly what was furnished and can dispute any item, without calling you first.
Live in every state that matters
Each search runs in real time in every state of the address history on the order plus where the job or housing is — or, with liveScope "all", in every source that supports a live search — and in our data everywhere else.
A coverage table behind every result
Every search lists each source it searched: live or from data, when, the date the data is current to, and what it found. A clear is exactly the sum of those rows, so it can be shown, not just asserted.
Evidence for every live check
Every live search — match or no match — keeps hash-pinned evidence: the official source’s own response wherever we receive it directly, and always a labelled record of what that live search returned, with its time and SHA-256 hash. Download each capture for the order.
A PDF anyone can check
The report PDF is rendered once and stored, and an Ed25519-signed public receipt carries its hash. A QR code on the PDF opens /verify, where anyone holding the file can confirm it is genuine without uploading it.
Idempotent, with a sandbox
An Idempotency-Key makes retries safe. Sandbox test subjects return clear, records found, withheld, incomplete and dispute outcomes with no live calls and no charges.
Six resources, one integration
Everything lives under /v1/fcra, authenticated with the same X-API-Key header as the standard APIs, on an account with FCRA Partner Access.
End users
/v1/fcra/end-users
The employers and landlords your reports are for. Register each once with its permissible purposes and your certification; every order references one.
Orders
/v1/fcra/orders
One consumer, one end user, one purpose, one consent attestation — and the searches to run. Created with an Idempotency-Key, returned at once with 202.
Searches
/v1/fcra/orders/{id}/searches/{searchId}
Each search in an order has its own status, result, coverage table, furnished records and withheld counts. Re-verify one and the old search is marked superseded.
Evidence
/v1/fcra/orders/{id}/evidence
What each official source returned to every live search in the order — match or no match — with its URL, time and SHA-256 hash, downloadable capture by capture.
Reports & receipts
/v1/fcra/orders/{id}/report
The furnished report as JSON or the stored PDF, with a public Ed25519-signed receipt carrying both hashes — checkable by anyone at /verify, with no personal data in it.
Disputes
/v1/fcra/orders/{id}/disputes
Open a reinvestigation on furnished records, follow it on the 30-day clock, and receive the outcome. Disputes from the consumer portal land here too.
Events
/v1/fcra/events
Every webhook event for your account, in order, so a missed delivery is never lost — plus resend for any single event.
From received to complete
An order moves through four statuses; each search inside it moves from queued to complete on its own. A search whose source cannot answer ends unavailable, and its result is incomplete — never clear.
received
The order is accepted and recorded with its end user, purpose and consent attestation.
in_progress
Searches are running live in the relevant states and in our data everywhere else, matching the subject under every name supplied and passing the controls.
partial
At least one search is complete and another is still running — read what is finished.
complete
Every search has finished. Each carries clear, records_found or incomplete.
The eta on every order gives the 50th and 90th percentile completion time from recent orders with the same searches.
What every search passes before anything is furnished
Applied in order to every search in an order — sex offender and criminal — before a single record leaves.
End user, purpose and consent on every order
An order is refused unless its end user is registered and certified, its permissible purpose is one that end user holds under your agreement, and it carries your consent attestation. A refused order is still recorded.
Exact date of birth, or nothing
Only a record that matches the consumer’s full date of birth can be furnished. A name-only or birth-year match is withheld — name-only matching is the pattern regulators have penalized screening vendors for.
Searched live in the consumer’s states
Every search runs in real time in each state of the address history on the order and the state where the job or housing is — not only against stored data — so a recent registration or filing in those states is not missed. Everywhere else, the coverage table shows the date the data is current to; an order sent without addresses or a use state says so, row by row.
Re-verified before anything is furnished
Every remaining record is re-checked against the official record at the time of the request. A record that is no longer listed is withheld; a source that cannot answer makes the result incomplete rather than clear.
Disputed records stay out
When a consumer dispute ends with a record deleted or found not to be theirs, that record is suppressed from every later regulated answer about them.
Never “clear” on a partial search
An answer is clear only when every state that matters was searched live and answered, every other source answered, and nothing reportable was found. Otherwise it says incomplete — and the coverage table shows exactly which source did not answer.
An evidence record for every order
Purpose, end user and certification, the identifiers searched, what each source said, the control version that applied, and every record furnished or withheld with its reason.
Live where it matters, with the evidence to show it
A clear answer is only as good as what was searched. Every FCRA search shows its work, source by source, and keeps what the official source said.
Live, not just stored
Each search runs in real time in every state of the address history on the order and the state where the job or housing is. A relevant state that cannot be searched live makes the result incomplete — never clear. Registries a state bars for the purpose are not searched at all, and the coverage table says so.
Coverage you can read
One row per source: searched live or from data, when it was checked, the date the data is current to, how many candidates it produced and how many were furnished or withheld.
What the live search saw
Every live check — match and no-match alike — keeps hash-pinned evidence: the official source’s own response wherever we receive it directly, and always a labelled record of what that live search returned. Each capture says which kind it is, and every one is listed in the PDF.
Verifiable by anyone
The PDF is stored once, so its hash never changes. The signed receipt carries that hash; /verify checks a file against it in the browser, and the file never leaves the device.
| Source | Mode | Checked | Data current to | Found |
|---|---|---|---|---|
| County court, Illinois | Live | 14:02 UTC | — | 1 furnished, 1 withheld |
| State corrections, Illinois | Live | 14:02 UTC | — | None |
| Court records, Wisconsin | Data | 14:01 UTC | Oct 1, 2026 | None |
Holding a report PDF? Verify it — the check runs in your browser and the file is never uploaded.
Signed, retried, and never carrying personal data
Seven events
order.created, search.completed, order.completed, order.cancelled, dispute.created, dispute.updated and record.corrected — the last sent to every partner that received a record a dispute changed.
Verify every delivery
Each carries an HMAC-SHA256 signature over a timestamp and the raw body. Reject a mismatch or a stale timestamp; the docs include a working verifier.
Nothing is lost
Failed deliveries retry with backoff for 24 hours, any event can be resent, and the events list lets you poll in order if your endpoint was down.
Build every branch before your first live order
The subject’s last name picks the outcome — Clear, Records, Withheld, Unavailable or Dispute — with no live calls and no charges, and the full webhook and dispute flow behind each.
From agreement to your first order
Regulated access is a separate grant on your account, not a setting you can turn on yourself.
1. Agree the scope
We review your business and the permissible purposes you serve, and sign a written FCRA agreement that fixes those purposes, your end-user certifications and the controls applied to every answer.
2. We enable your key
Regulated access is switched on for your account only after the agreement is signed, and only for the purposes it names. Standard self-serve access stays exactly as it was, and never carries regulated use.
3. Register end users, then place orders
Register each employer or landlord once, with its permissible purposes and your certification. Each order then names the end user, the purpose and your consent attestation, carries the consumer’s full name and date of birth, and runs a sex-offender search, a criminal search, or both.
4. Get an answer you can stand behind
Orders run in the background and report back by signed webhook. Each search runs live in the states that matter and comes with a source-by-source coverage table. Only records that pass every control are furnished, each with its match evidence and the time it was verified; everything else is a count by reason, and the whole order is kept as evidence.
What the API carries, and what your platform keeps
The API is the furnisher’s side of the report. Your platform keeps the employer-facing workflow — invitations, disclosures, adjudication and adverse action — and the API gives it everything it needs to be defensible.
What the API carries
- End-user, purpose and consent records on every order
- Exact-DOB matching, state rules and seven-year limits
- Live search in the relevant states, and live re-verification
- A coverage table on every search
- Official-source evidence, a stored PDF and a signed receipt
- Disputes, corrections and the consumer portal
What stays with you and your client
- Disclosure, authorization and consent from the consumer
- Pre-adverse and adverse-action notices to the consumer
- The hiring, tenancy or eligibility decision itself
- Notices to your own end users, under your agreement with them
The disputes API · The consumer portal · Sex offender search · Criminal search
FCRA Orders API questions
Who is the FCRA Orders API for?
Background check companies and screening platforms that furnish consumer reports — the consumer reporting agency behind a background check. Employers and landlords use it through them. It is the regulated data layer under your product, not a replacement for your adjudication or adverse action workflow.
Why an orders API instead of a search endpoint?
Because a consumer report is an order, not a lookup. The end user, the permissible purpose and the consent attestation belong to the order, both searches share them, and the work can take longer than a request should wait — a live re-check with a slow court is normal. Orders run in the background and report back by webhook, the way screening platforms already work.
Can an order run only one search?
Yes. searches takes one or both of sex_offender and criminal. Each search has its own status and result, so a finished registry answer never waits on a criminal search that is still running.
How do I avoid duplicate orders when my client retries?
Send an Idempotency-Key with every order. The same key and body return the original order; the same key with a different body is refused with 409, so a bug cannot silently create a second report.
What is in a webhook?
Identifiers and statuses only — the order, search or dispute id and its new status. Never personal data. You fetch the detail with your key, so a webhook log or a misconfigured endpoint never holds a consumer’s record.
How do I know a record is the right person?
Every furnished record carries matchBasis — always an exact date-of-birth match in an FCRA order — and which identifiers agreed, the official source that holds it, when it was obtained, and when it was re-verified for your order. Anything weaker is withheld and counted by reason.
Which sources are searched live?
By default, every source for each state in subject.addresses and for useLocation.state, plus any jurisdiction that produced a candidate. Set liveScope to "all" for every source that supports a live search. Everything else is searched in our data, and each search’s coverage table lists every source with its mode, time and the date its data is current to.
What does clear actually mean?
That every relevant state was searched live and answered, every other source answered, and nothing reportable was found. If a relevant state cannot be searched live, the result is incomplete with live_unavailable in the coverage table — never a quiet clear.
Is there a sandbox?
Yes. Sandbox test subjects return clear, records found, withheld-only, incomplete and dispute outcomes deterministically, with no live calls and no charges, so you can build every branch of your integration before the first live order.
How is it priced?
FCRA pricing is quoted per partner — contact us for pricing. FCRA orders are metered separately from standard calls.
Start building against the FCRA Orders API
Tell us about your platform and the purposes you serve. We will set up the agreement, enable FCRA orders on your key and open your sandbox.
Request FCRA Partner Access How the program works
FCRA pricing is quoted per partner — contact us for pricing. Standard self-serve access is separate and is not a consumer report.