OffenderSearch
FCRA Partner Access · the orders API

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.

For consumer reporting agencies, screening platforms and organizations screening for themselves, under a written FCRA agreement. Data API calls are separate and are not a consumer report.No code? Run the same search in the screening dashboard ›
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"
    }'
Index

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

ResourceEndpointsWhat it is for
PartnerGET /v1/fcra/partnerYour agreement: the purposes enabled on the key and the live scope you may request.
End usersPOST /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.
OrdersPOST /v1/fcra/ordersGET /v1/fcra/ordersGET /v1/fcra/orders/{orderId}POST /v1/fcra/orders/{orderId}/cancelOne consumer, one end user, one purpose, one consent attestation, and the searches to run.
SearchesGET /v1/fcra/orders/{orderId}/searches/{searchId}POST /v1/fcra/searches/{searchId}/reverifyEach search in an order: status, result, coverage rows, withheld counts, and reverify.
Report and receiptGET /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.
EvidenceGET /v1/fcra/orders/{orderId}/evidenceGET /v1/fcra/orders/{orderId}/evidence/{captureId}What each live source returned, capture by capture, with its hash.
DisputesPOST /v1/fcra/orders/{orderId}/disputesGET /v1/fcra/disputesGET /v1/fcra/disputes/{disputeId}POST /v1/fcra/disputes/{disputeId}/informationOpen a reinvestigation, read it back, supply information while it runs.
Webhooks and eventsGET /v1/fcra/webhook-endpointPUT /v1/fcra/webhook-endpointDELETE /v1/fcra/webhook-endpointGET /v1/fcra/eventsPOST /v1/fcra/events/{eventId}/resendOne 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.

End users

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.

Orders

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.

Scope

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.

Searches

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.

resultMeaning
clearEvery source in scope answered and nothing reportable was found. Shown only when the live sources answered.
records_foundAt least one record passed every control and was furnished, each with matchBasis and verifiedAt.
incompleteA 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.

Report

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.

Disputes

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."
    }'
  1. 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.
  2. 02Investigating. The record is checked again with the authority that holds it — the registry or the court — not against our own copy.
  3. 03Outcome. Verified, modified, deleted, or unable to verify — and a record that cannot be verified in time is treated as deleted.
  4. 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.

Webhooks

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, and record.verification_pending, record.verified, record.verification_failed for records being confirmed with their source.
  • Signature. X-Offendersearch-Signature carries a timestamp and an HMAC-SHA256 over t.body with 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/events lists every event in order and POST …/events/{eventId}/resend replays one.
Sandbox

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.

SubjectOutcome
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 foundOrder complete; each search furnishes one sandbox record (records_found). The sex offender record carries registry{}, the criminal record cases[] with a misdemeanor conviction.
Records withheldSearch complete with result clear: nothing furnished, only withheld counts (2 insufficient_identifiers, 1 not_current_at_source).
Sources unavailableThe 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 confirmationSearch 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 resolvesOne 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 exclusionThe 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 noneThe same subject with exclusions: "none": no exclusion-list record is furnished or counted, so the search is clear.
Administrative exclusion, default modeAn administrative exclusion (license action, not a conviction) is not furnished under the default conviction_only mode: the search is clear.
Administrative exclusion, exclusions allWith exclusions: "all" the administrative exclusion is furnished: one record, dispositionStatus sanction, convictionBased false.
Healthcare search, federal exclusionA healthcare search furnishes one HHS-OIG conviction-based exclusion, matched on the exact date of birth (matchBasis dob_match).
Healthcare search, nurse-aide findingA 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 matchA 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.

Two paths

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.

Path 1

Data API, not FCRA

$0.15a call, 25 free, no card
  • 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.

Path 2

FCRA Partner Access

$4.95per order, searches and live checks included, no court fees
  • 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.

Access

How FCRA Partner Access is enabled on a key

Regulated access is a grant made after the agreement, not a setting.

  1. 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.
  2. 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.
  3. 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.
  4. 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.

Pricing

FCRA Orders API pricing

One meter for orders; sandbox orders free.

ItemPriceUnit
FCRA order$4.95per order; sex offender and criminal court search included, with no court fees or extra charges
Sandbox$060 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.

FAQ

FCRA Orders API questions

Why is the FCRA API an orders API rather than a search endpoint?

Because a consumer report has context a lookup does not: the end user, the permissible purpose and the consent attestation belong to the order, both searches share them, and a live court check can take longer than a request should wait. Orders run in the background and report back by webhook.

What does an Idempotency-Key do on POST /v1/fcra/orders?

The same key with the same body returns the original order instead of creating a second one. The same key with a different body is refused with 409, so a retry bug cannot place a second report on the same consumer.

What is in a webhook payload, and what is not?

The event id, its type, and the order, search or dispute id with its new status. No names, dates of birth or records. Your handler fetches the detail with your key, so a webhook log or a misrouted endpoint never holds consumer data.

What does liveScope change?

Which sources are searched live for the order. relevant (the default) searches the sources for each state in subject.addresses and useLocation.state live and the rest from our data; all searches every source that supports a live check; matches answers a person with no possible record from our data and confirms every possible record with its source before it is reported.

When is an FCRA order billed?

When it is accepted, at $4.95, with the searches and the live checks included and no court fees. A sandbox order is never billed. The data API's per-call meter is separate.

Can one order run only the registry search, or only the criminal search?

Yes. searches takes one or both of sex_offender and criminal, and each has its own status, result and records, so a finished registry answer is readable while a criminal search is still running.

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.

Background check API ›Criminal records and 58 US sex offender registries on one key, per call.
Criminal records API ›Court cases, jail bookings, prison custody and warrants as JSON.
Sex offender API ›One POST across 58 US registries, scored and cited.
Free background check API ›25 free calls on real data, no card, plus the free sandbox.
Employment screening API ›The public-records stage of a hiring pipeline, and the FCRA path for the decision.
Tenant screening API ›The registry and criminal layer behind a rental application.
Inmate search API ›State prison and county jail custody records.
Background check API pricing ›Costs from 100 to 100,000 searches a month.
Public API for testing ›A free sandbox with documented test people in the production shape.
SDKs: Python, Node, CLI ›Client status and the method surface, one per endpoint.
Postman collection ›Every endpoint with sandbox bodies pre-filled.
MCP server ›Registry and criminal lookups as tools for Claude, Cursor and agents.