FCRA Partner API · v1.0.0 · approved partners

FCRA API sandbox & test subjects

A test key, a sandbox end user, and test subjects for every order outcome, exclusions included. No live calls, no charges.

Sandboxhttps://sandbox.offendersearch.appLivehttps://api.offendersearch.app

Test without live calls

Sandbox orders run the full order, search, dispute and webhook flow with deterministic results, no live calls and no charges. The subject’s last name picks the outcome; every test subject is listed under FCRA API sandbox orders below, with what it returns.

Any other last name returns clear. Sandbox orders are never metered, and every sandbox record carries sandbox: true and an id beginning sandbox:.

The last name Pending returns the held outcome of a liveScope: "matches" order whatever the order’s liveScope: one possible record held for confirmation (held, heldCount: 1, verification_pending) and a record.verification_pending event. When "matches" is enabled for your account, every furnished sandbox record on a "matches" order also carries its verification block.

On a healthcare search: Excluded returns one HHS-OIG conviction-based exclusion matched on the date of birth (dob_match); Sanctioned one nurse-aide registry neglect finding matched on the certificate number (license_match, dispositionStatus: "sanction") — clear under exclusions: "conviction_only"; Possible a list entry matched on the name only: nothing furnished, withheld: {"insufficient_identifiers": 1}, result incomplete with identifiers_needed. Unavailable returns incomplete; every other last name returns clear.

SSN-trace orders (addressSource: "ssn_trace") work in the sandbox too, by the SSN’s last four digits: 1111 no data (the scope falls back), 2222 thin file, 3333 invalid, 4444 name mismatch; anything else is answered with two traced addresses in Franklin County, OH.

Two ways to use these rules. On the live API, sandbox is a setting on your partner account, enabled by our team — ask for it when you request FCRA Partner Access. On the sandbox server, with a test key, every account is already a sandbox partner for every permissible purpose, and orders follow the same last-name rules. The rest of this page is the sandbox server.

FCRA API test keys: create one in the dashboard

The FCRA sandbox server is the FCRA API on a separate server. With a test key, every account is already a sandbox FCRA partner for every permissible purpose, so there is nothing to request first: register an end user, place orders, open disputes and read webhook events, with the same paths and shapes as live. Nothing is billed.

  1. In the dashboard, open Developers → API keys.
  2. Choose Create test key. Test keys are for business accounts and need no subscription.
  3. Copy the key. Test keys begin os_test_. Like a live key, the full secret is shown once, so put it in your secrets store straight away.

One test key works on every API’s sandbox. Each key in the list is labelled Test · Sandbox or Live, with the base URL it works on. Send it in the same X-API-Key header the live API uses. An account holds up to 3 active test keys and can create 10 a day. A revoked test key stops working on the sandbox within a few minutes.

FCRA API sandbox base URL vs live

SandboxProduction
Base URLhttps://sandbox.offendersearch.apphttps://api.offendersearch.app
Key prefixos_test_os_live_
DataOutcomes picked by the subject’s last name, listed belowLive FCRA orders under your partner agreement
BillingNever billed, never recorded to usageYour plan’s prices
sandbox fieldtrue on every responseAbsent
X-Offendersearch-Environmentsandbox on every responseAbsent

Each key works on its own server only, so a mixed-up configuration is caught on the first request rather than after a release. A test key sent to the live API, or a live key sent to the sandbox, is refused with 401 and a detail message that says so:

401 — a test key sent to the live API
{
  "detail": "This is a test key (os_test_…). Test keys work only on the sandbox at https://sandbox.offendersearch.app, which answers with sample data. To search real records, send a live key (os_live_…) to https://api.offendersearch.app."
}
401 — a live key sent to the sandbox
{
  "detail": "This is a live key. The sandbox at https://sandbox.offendersearch.app accepts test keys (os_test_…) only — create one in the dashboard under Developers → API keys. Send live keys to https://api.offendersearch.app."
}

A revoked test key gets 401 with: “This test key has been revoked. Create a new test key in the dashboard under Developers → API keys.”

Each test key can send 60 requests a minute and 2,000 a day, and one IP address 120 a minute, across every API on the sandbox. Past a limit the sandbox answers 429 with a Retry-After header. See Sandbox rate limits.

Register an FCRA end user in the sandbox

Every order names an end user: the employer or landlord the report is for. Register one once with POST /v1/fcra/end-users, keep its id, and send it as endUserId on every sandbox order. The fields are the same as live; see Access & end users.

1. POST /v1/fcra/end-users — sandbox
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": "Sample Staffing LLC",
      "permissiblePurposes": [
        "employment"
      ],
      "certification": {
        "text": "End user certifies it will use reports only for employment purposes.",
        "version": "v1",
        "certifiedAt": "2026-10-01T12:00:00Z"
      }
    }'

FCRA API sandbox orders

The subject’s last name picks the outcome, and for Excluded and Sanctioned the criminal search’s exclusions mode picks it too. An order finishes right after the 202: read it once with GET /v1/fcra/orders/{orderId}. Sandbox records carry sandbox: true and ids beginning sandbox:.

SendWhat comes back
subject.lastName: Clear
searches: sex_offender, criminal
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.
subject.lastName: Records
searches: sex_offender, criminal
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.
subject.lastName: Withheld
searches: criminal
Records withheld. Search complete with result clear: nothing furnished, only withheld counts (2 insufficient_identifiers, 1 not_current_at_source).
subject.lastName: Unavailable
searches: sex_offender
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.
subject.lastName: Pending
searches: criminal
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.
subject.lastName: Dispute
searches: criminal
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.
subject.lastName: Excluded
searches: criminal
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.
subject.lastName: Excluded
searches: criminal (exclusions: none)
Conviction-based exclusion, exclusions none. The same subject with exclusions: "none": no exclusion-list record is furnished or counted, so the search is clear.
subject.lastName: Sanctioned
searches: criminal
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.
subject.lastName: Sanctioned
searches: criminal (exclusions: all)
Administrative exclusion, exclusions all. With exclusions: "all" the administrative exclusion is furnished: one record, dispositionStatus sanction, convictionBased false.
subject.lastName: Excluded
searches: healthcare
Healthcare search, federal exclusion. A healthcare search furnishes one HHS-OIG conviction-based exclusion, matched on the exact date of birth (matchBasis dob_match).
subject.lastName: Sanctioned
searches: healthcare (exclusions: all)
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).
subject.lastName: Possible
searches: healthcare
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.
2. POST /v1/fcra/orders — sandbox (use the end user’s id)
curl -X POST "https://sandbox.offendersearch.app/v1/fcra/orders" \
  -H "X-API-Key: $OFFENDERSEARCH_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "endUserId": "{endUserId}",
      "permissiblePurpose": "employment",
      "consent": {
        "obtainedAt": "2026-10-01T12:00:00Z",
        "method": "esign"
      },
      "subject": {
        "firstName": "Pat",
        "lastName": "Records",
        "dob": "1980-01-01"
      },
      "searches": [
        {
          "type": "sex_offender"
        },
        {
          "type": "criminal"
        }
      ]
    }'

FCRA API sandbox examples in cURL, Node and Python

Records found: an order for subject.lastName Records, after you register an end user. Put its id in endUserId. Export your test key as OFFENDERSEARCH_TEST_KEY first.

curl -X POST "https://sandbox.offendersearch.app/v1/fcra/orders" \
  -H "X-API-Key: $OFFENDERSEARCH_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "endUserId": "{endUserId}",
      "permissiblePurpose": "employment",
      "consent": {
        "obtainedAt": "2026-10-01T12:00:00Z",
        "method": "esign"
      },
      "subject": {
        "firstName": "Pat",
        "lastName": "Records",
        "dob": "1980-01-01"
      },
      "searches": [
        {
          "type": "sex_offender"
        },
        {
          "type": "criminal"
        }
      ]
    }'

Postman collection for the FCRA API sandbox

One collection covers every API’s sandbox, with a folder per API, ready to import into Postman or Insomnia. The FCRA API folder has one request for every scenario on this page. Set {{apiKey}} to your test key; {{baseUrl}} is preset to the sandbox. A request that needs an id from an earlier response uses a variable for it: {{endUserId}}.

Download the sandbox collection (JSON)

Postman: Import, then drop the file. Insomnia: Import, then From file.

Move FCRA orders from the sandbox to production

The sandbox and the live API differ only in the base URL and the key. Keep both in configuration, not in code, and going live is a configuration change:

.env
# Sandbox
OFFENDERSEARCH_BASE=https://sandbox.offendersearch.app
OFFENDERSEARCH_KEY=os_test_…

# Production — change these two values and nothing else
OFFENDERSEARCH_BASE=https://api.offendersearch.app
OFFENDERSEARCH_KEY=os_live_…
  • Create a live key on the same Developers → API keys page.
  • Remove any branch that reads sandbox. The field does not exist on live.
  • Live FCRA orders need FCRA Partner Access under a written agreement: see Access & end users. Register your live end users again with the live key.
  • FCRA checks are $4.95 per order, criminal court search included, with no court fees or extra charges.

Product overview