The FCRA Orders API
Eight resources under /v1/fcra: register an end user, place an order, read its scope and each search, fetch the report and its receipt, open a dispute, and receive every change by signed webhook. $4.95 an order; sandbox orders free.
curl -X POST "https://sandbox.offendersearch.app/v1/fcra/orders" \
-H "X-API-Key: $OFFENDERSEARCH_TEST_KEY" \
-H "Content-Type: application/json" \
-d '{
"endUserId": "eu_d04e9a0f73263706",
"permissiblePurpose": "employment",
"consent": {
"obtainedAt": "2026-11-08T14:00:00Z",
"method": "esign",
"documentRef": "consent-2026-11-08-0412"
},
"subject": {
"firstName": "Pat",
"lastName": "Records",
"dob": "1980-01-01",
"addresses": [
{
"state": "OH",
"city": "Columbus"
}
]
},
"useLocation": {
"state": "OH",
"city": "Columbus",
"postalCode": "43215",
"county": "Franklin"
},
"searches": [
{
"type": "sex_offender"
},
{
"type": "criminal"
}
],
"clientReference": "onboarding-7781"
}'FCRA API endpoints in the order an integration calls them
Every route the sandbox serves, grouped by resource. Authenticate with the same X-API-Key header as the data API.
Updated November 8, 2026 · API changelog
| Resource | Endpoints | What it is for |
|---|---|---|
| Partner | GET /v1/fcra/partner | Your agreement: the purposes enabled on the key and the live scope you may request. |
| End users | POST /v1/fcra/end-usersGET /v1/fcra/end-usersGET /v1/fcra/end-users/{endUserId}PATCH /v1/fcra/end-users/{endUserId} | The employers and landlords reports are for, registered once with their purposes and certification. |
| Orders | POST /v1/fcra/ordersGET /v1/fcra/ordersGET /v1/fcra/orders/{orderId}POST /v1/fcra/orders/{orderId}/cancel | One consumer, one end user, one purpose, one consent attestation, and the searches to run. |
| Searches | GET /v1/fcra/orders/{orderId}/searches/{searchId}POST /v1/fcra/searches/{searchId}/reverify | Each search in an order: status, result, coverage rows, withheld counts, and reverify. |
| Report and receipt | GET /v1/fcra/orders/{orderId}/report?format=json|pdfGET /v1/fcra/receipts/{orderId} | The furnished report as JSON or PDF, and the signed receipt that proves it. |
| Evidence | GET /v1/fcra/orders/{orderId}/evidenceGET /v1/fcra/orders/{orderId}/evidence/{captureId} | What each live source returned, capture by capture, with its hash. |
| Disputes | POST /v1/fcra/orders/{orderId}/disputesGET /v1/fcra/disputesGET /v1/fcra/disputes/{disputeId}POST /v1/fcra/disputes/{disputeId}/information | Open a reinvestigation, read it back, supply information while it runs. |
| Webhooks and events | GET /v1/fcra/webhook-endpointPUT /v1/fcra/webhook-endpointDELETE /v1/fcra/webhook-endpointGET /v1/fcra/eventsPOST /v1/fcra/events/{eventId}/resend | One signed endpoint per partner, an ordered events list, and resend. |
24 endpoints, as listed in the sandbox fixtures. The FCRA API reference carries every field; errors lists every status code.
Register an FCRA end user before the first order
The employer or landlord a report is for, with the purposes it holds and your certification. Once per end user.
curl -X POST "https://sandbox.offendersearch.app/v1/fcra/end-users" \
-H "X-API-Key: $OFFENDERSEARCH_TEST_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Acme Staffing LLC",
"externalId": "acme-1",
"address": {
"line1": "1 Main St",
"city": "Columbus",
"state": "OH",
"postalCode": "43215"
},
"permissiblePurposes": [
"employment"
],
"certification": {
"text": "I certify the information will be used for the stated permissible purpose and for no other purpose, in compliance with the FCRA.",
"version": "2026-10",
"certifiedAt": "2026-11-08T14:00:00Z",
"certifiedBy": "Dana Reyes, Compliance"
}
}'status is active on creation; PATCH changes the purposes or suspends the end user, and an order for a suspended or unregistered end user is refused and recorded. scopePolicy is null until you set a per-end-user scope.
Create an FCRA order and read it back when complete
202 at once with an eta and a scope; four statuses after that; each search finishes on its own.
The request in the hero carries the consumer (full name, full date of birth, addresses), the end user, the purpose, the consent attestation, useLocation and the searches. The 202 returns status: "received", an eta with p50 and p90 from recent orders, the scope the order will search, and the consumerPortal code. The order then moves through in_progress and, when one search finishes before the other, partial, to complete; the complete order in the third tab shows both searches with result: "records_found" and recordCount: 1.
liveScope on the order defaults to relevant; controlVersion names the control set that applied, so a report can be read against the rules in force when it was made. POST …/orders/{id}/cancel stops an order that has not completed. Field by field: orders.
How an FCRA order decides which jurisdictions to search
The scope block on every order and report: counties, states and national sources, each with the reason it is there.
scope.jurisdictions[] lists each county, state and national source set with a reasons[] array: a declared residence resolved from a city or postal code, the use location, or a neighbour within the policy radius of a residence county. scope.policy shows the rule that built it: the look-back in years, the neighbour-county radius and cap, whether the use location and the statewide and national sources are included.
scope.gaps[] names a county in scope that has no live source yet, with the statewide sources that still cover it; scope.summary.sources counts the live and pending sources. The captured report below carries a full scope for one Ohio address: five counties, one state, eighteen live sources and one gap. Preview a scope before ordering and set a per-end-user policy under scope.
Search detail, result values and the reverify endpoint
GET …/orders/{orderId}/searches/{searchId} for one search; POST /v1/fcra/searches/{searchId}/reverify to run it again.
| result | Meaning |
|---|---|
clear | Every source in scope answered and nothing reportable was found. Shown only when the live sources answered. |
records_found | At least one record passed every control and was furnished, each with matchBasis and verifiedAt. |
incomplete | A source in scope did not answer, or a possible record is still being confirmed; incompleteReasons says which. Never read as clear. |
A search carries coverage[], one row per source with the mode (live or from our data), the time it was checked, the date its data is current to and what it produced; withheld, a count per reason for records that did not pass a control; and records[] for what was furnished. Reverify runs the search again on request, marks the old one supersededBy the new id, and re-applies the controls to the fresh copy. Reasons and reason codes: controls; the furnished shape: results. Why every criminal hit is re-checked at its source court before it is furnished: FCRA 613 compliance.
The FCRA report as JSON or PDF, with a signed receipt
GET …/orders/{id}/report?format=json|pdf. The JSON for the order above, complete.
{
"orderId": "fo_cccc30f9c62c84c6",
"status": "complete",
"createdAt": "2026-11-08T15:51:14.170077+00:00",
"revision": 1,
"revisedAt": null,
"removedRecordIds": [],
"completedAt": "2026-11-08T15:51:14.170923+00:00",
"permissiblePurpose": "employment",
"endUser": {
"id": "eu_d04e9a0f73263706",
"name": "Acme Staffing LLC"
},
"clientReference": "onboarding-7781",
"subject": {
"firstName": "Pat",
"middleName": null,
"lastName": "Records",
"dob": "1980-01-01"
},
"controlVersion": "fcra-controls-2026-10-28.1",
"sandbox": true,
"liveScope": "relevant",
"searches": [integrity.reportSha256 is the hash of this object without the integrity block; pdfSha256 is the stored PDF’s hash; receiptUrl returns the Ed25519-signed receipt and verifyUrl opens /verify, where anyone holding the PDF can check it in the browser without uploading it. revision and removedRecordIds change when a dispute removes a record. Evidence captures for the live checks are under evidence.
Open an FCRA dispute and follow it on the 30-day clock
POST …/orders/{id}/disputes, GET /v1/fcra/disputes/{id}, and POST …/disputes/{id}/information while it runs.
curl -X POST "https://sandbox.offendersearch.app/v1/fcra/orders/fo_0234ff4985cbf257/disputes" \
-H "X-API-Key: $OFFENDERSEARCH_TEST_KEY" \
-H "Content-Type: application/json" \
-d '{
"recordIds": [
"sandbox:criminal:dispute-1980-01-01"
],
"reason": "not_me",
"consumerStatement": "This record is not mine. Different middle name and I have never lived in that county."
}'- 01Received. You open the dispute through the API, or the consumer opens it in the portal. The 30-day clock starts from when the dispute reached you.
- 02Investigating. The record is checked again with the authority that holds it — the registry or the court — not against our own copy.
- 03Outcome. Verified, modified, deleted, or unable to verify — and a record that cannot be verified in time is treated as deleted.
- 04Correction fan-out. A changed or removed record is corrected or suppressed in every later order, and every partner that received it gets a record.corrected event.
reason takes not_me, inaccurate, incomplete, outdated or other; origin is partner or consumer. information adds a statement the consumer sent during the reinvestigation: the one 15-day extension, after which dueAt moves and extendedAt records when. Detail: FCRA dispute API; the consumer side: FCRA consumer portal.
FCRA webhooks: one signed endpoint, an events list and resend
PUT /v1/fcra/webhook-endpoint once. Every event is signed; none carries personal data.
- Events.
order.created,search.completed,order.completed,order.cancelled,dispute.created,dispute.updated,record.corrected, andrecord.verification_pending,record.verified,record.verification_failedfor records being confirmed with their source. - Signature.
X-Offendersearch-Signaturecarries a timestamp and an HMAC-SHA256 overt.bodywith your partner secret; reject a mismatch or a stale timestamp. A working verifier is in webhooks, and the webhook tester shows live events. - Delivery. Failed deliveries retry with backoff for 24 hours;
GET /v1/fcra/eventslists every event in order andPOST …/events/{eventId}/resendreplays one.
Sandbox subjects for every FCRA order outcome
The subject's last name picks the outcome. No live calls, no charge, the full webhook and dispute flow behind each.
| Subject | Outcome |
|---|---|
| Clear (any other last name) | Order complete; every search complete with result clear and no records. Any last name not listed here behaves the same way. |
| Records found | Order complete; each search furnishes one sandbox record (records_found). The sex offender record carries registry{}, the criminal record cases[] with a misdemeanor conviction. |
| Records withheld | Search complete with result clear: nothing furnished, only withheld counts (2 insufficient_identifiers, 1 not_current_at_source). |
| Sources unavailable | The search ends unavailable with result incomplete (the sources could not be reached), and the order completes. This is production's documented sandbox outcome for an FCRA order, not a simulated outage of the sandbox. |
| Record held for confirmation | Search complete with result incomplete and incompleteReasons ["verification_pending"]: one possible record is being confirmed with its source agency, so it is listed under held (jurisdiction ZZ-SANDBOX, status pending_verification, heldCount 1) and nothing is furnished. This is the outcome a liveScope matches order gives while a record is held; the sandbox gives it for this name whatever the liveScope. |
| Dispute that resolves | One furnished record, as Records. A dispute filed on it (POST /v1/fcra/orders/{id}/disputes) resolves deleted 60 seconds later, read on the next GET of the dispute; dispute.created and dispute.updated events are emitted. |
| Conviction-based exclusion | The criminal search furnishes one exclusion-list record (recordType healthcare_exclusion, dispositionStatus conviction, authority 1128(a)(1)). A conviction-based exclusion is furnished under the default exclusions mode, conviction_only. |
| Conviction-based exclusion, exclusions none | The same subject with exclusions: "none": no exclusion-list record is furnished or counted, so the search is clear. |
| Administrative exclusion, default mode | An administrative exclusion (license action, not a conviction) is not furnished under the default conviction_only mode: the search is clear. |
| Administrative exclusion, exclusions all | With exclusions: "all" the administrative exclusion is furnished: one record, dispositionStatus sanction, convictionBased false. |
| Healthcare search, federal exclusion | A healthcare search furnishes one HHS-OIG conviction-based exclusion, matched on the exact date of birth (matchBasis dob_match). |
| Healthcare search, nurse-aide finding | A healthcare search (exclusions all, also its default when omitted) furnishes one nurse-aide registry neglect finding, matched on the certificate number (matchBasis license_match, dispositionStatus sanction). |
| Healthcare search, name-only list match | A list entry matched on the name only is withheld (1 insufficient_identifiers) and the search is incomplete with incompleteReasons identifiers_needed: add the subject's npi or licenses and order again. |
Mint an os_test_ key in the dashboard; the same bodies run against the public API for testing. Reference: FCRA sandbox.
Where the FCRA API sits beside the data API
Same records, different product. One block, so the two prices read the same on every page.
Data API, not FCRA
- For: visitor and volunteer screening, trust and safety, research, monitoring, and software that shows a public record to the person who asked for it.
- Must not decide: whether someone is hired, housed, insured or given credit. The response is a public-records lookup, not a consumer report, and the key is not approved for those uses.
- Example: An admissions desk screens a visitor against the registries before a visit; no hiring, housing or credit decision is involved.
Self-serve: get a key, then POST /v1/search or /v1/criminal/search.
FCRA Partner Access
- Built in: end-user registration with a permissible purpose, consent on every order, the pre-adverse and adverse-action notices with the consumer’s copy, and a consumer portal.
- Disputes: a dispute endpoint; the record is re-checked with the registry or court that holds it, with an outcome inside 30 days, and a correction reaches every partner that received it.
- Example: A screening company furnishes a report an employer or landlord will act on; the order runs the consent, notice and dispute steps.
Under a written agreement: Request FCRA Partner Access.
The records can be the same; the process around them is not. How the program works: FCRA Partner Access · the orders endpoint: FCRA orders API · reference and statute citations: FCRA docs. This page describes the product, not legal advice.
How FCRA Partner Access is enabled on a key
Regulated access is a grant made after the agreement, not a setting.
- 01Agree 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.
- 02We 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.
- 03Register 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.
- 04Get 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.
The hiring and housing uses of the same API, step by step: employment screening API and tenant screening API; the time rules on the criminal search: FCRA criminal background check API; the registry search: FCRA sex offender check API.
FCRA Orders API pricing
One meter for orders; sandbox orders free.
| Item | Price | Unit |
|---|---|---|
| FCRA order | $4.95 | per order; sex offender and criminal court search included, with no court fees or extra charges |
| Sandbox | $0 | 60 calls a minute and 2,000 a day per test key |
No minimum on search. The Map API has its own $300 monthly minimum. No seats, no platform fee, no per-state fee; a batch row is billed as one call.
Worked examples by volume: background check API pricing · every rate: pricing.
FCRA Orders API questions
Why is the FCRA API an orders API rather than a search endpoint?
What does an Idempotency-Key do on POST /v1/fcra/orders?
What is in a webhook payload, and what is not?
What does liveScope change?
When is an FCRA order billed?
Can one order run only the registry search, or only the criminal search?
Start building against the FCRA Orders API
Mint a test key and place sandbox orders today; tell us about your platform and the purposes you serve when the first live order is in sight. $4.95 an order, searches and live checks included.
Related FCRA Orders API pages
The rest of the developer surface, one anchor per page.
The OffenderSearch APIs
One account, one key, one bill.