FCRA Partner API · v1.0.0 · approved partners

Orders

One order, one or both searches: create it, track its status, cancel it.

Livehttps://api.offendersearch.appSandboxhttps://sandbox.offendersearch.app

Create an order

POST /v1/fcra/orders returns 202 with the order at status received, and the work starts in the background. Send an Idempotency-Key header: the same key with the same body within 24 hours returns the original order (with the response header Idempotent-Replayed: true); the same key with a different body is 409 idempotency_conflict. Every request field is in the order request reference below.

POST /v1/fcra/orders
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"
  }'

Two ways to run an FCRA order: addresses or SSN trace

An order needs the places the consumer has lived, because that is where the courts are searched. addressSource says where they come from.

`addressSource`You sendPrice
providedThe name, full date of birth and subject.addresses (the address history). No SSN: one sent is refused with 422 ssn_not_used_in_address_mode.$4.95 per order
ssn_traceThe name, full date of birth and subject.ssn. We run an SSN-based address history trace; the counties it finds pick the scope, with any addresses you also send and the use location.$6.95 per order

Omit addressSource and the end user’s default applies (scopePolicy.addressSource); with none, an order that carries subject.ssn runs ssn_trace and one without runs provided. ssn_trace without an SSN is 422 ssn_required; provided named explicitly with no address is 422 addresses_required. The SSN is never stored or returned — the order keeps its last four digits — and the traced addresses are used only to choose where to search: they are never in the order, the plan or the report. When the trace finds nothing usable, the order still runs: the scope is built from the addresses you sent, the use location and the statewide and national tiers, and scope.traceFallback and identity.trace.scopeOutcome say so. Until SSN trace is on for your account, ssn_trace is 422 ssn_trace_unavailable; sandbox orders always trace (Search scope).

An SSN-trace order (subject)
{
  "addressSource": "ssn_trace",
  "subject": { "firstName": "Jordan", "lastName": "Rivera", "dob": "1988-04-12", "ssn": "123-45-5555" }
}

Exclusion lists in a criminal search

A criminal search also covers the HHS-OIG, SAM.gov and state Medicaid exclusion lists — exclusion-list records with recordType: "healthcare_exclusion" and an exclusion block (see the criminal record object). The search’s exclusions option says which of them may be furnished: conviction_only (the default) furnishes exclusions whose basis is a criminal conviction, as convictions dated by the exclusion date; all also furnishes the administrative tier — license actions, debarments from federal awards, loan defaults — with dispositionStatus: "sanction"; none furnishes no exclusion-list records. A list entry with no date of birth is withheld as insufficient_identifiers whatever the setting. The option is in the SearchSpec reference below.

The healthcare search

searches: [{ "type": "healthcare" }] screens the consumer against the healthcare sanction lists: the HHS-OIG List of Excluded Individuals/Entities, SAM.gov exclusions, every state Medicaid exclusion list and every state nurse-aide registry finding we hold — in every state, whatever the consumer’s addresses. It can run alone or next to sex_offender and criminal: an order carries one to three searches, each type at most once. It is included in the order price.

Most exclusion lists publish no date of birth, so a healthcare search can also match on the consumer’s professional identifiers. Send them on the subject: npi (the 10-digit National Provider Identifier; one that fails its check digit is a 422) and up to 10 licenses, each { "state", "number", "type" } — a nurse-aide certificate, a nursing license. A list entry matched on the name alone is never reported (see Healthcare results).

The search’s exclusions option works the other way round from the criminal search: all is the default when you omit it (every active exclusion and nurse-aide finding — administrative findings are what a sanctions check is for), and conviction_only keeps only exclusions whose basis is a criminal conviction. none is refused with a 422.

Live scope: relevant, all or matches

liveScope says where an order checks live. Every value searches the same scope (see Search scope) and applies the same controls; what changes is which sources are asked live and when.

`liveScope`What runs liveUse it when
relevant (default)Every live-capable source in the states of subject.addresses and useLocation.state, plus the source of every exact-date-of-birth candidate. Every other source is searched in our data.You want each relevant state checked live for every order.
allEvery source that supports a live search for that type.You want the widest live check, at the cost of time and more metered live checks.
matchesOur stored copies answer first, and a consumer with no possible record is answered from them. Live checks happen only to confirm each possible record with the agency that keeps it, to search an in-scope source we hold no copy of, and to look up a record on file that has no date of birth.You want a fast answer for a consumer with no record, and every reported record confirmed at its source on the day of the order.

"matches" is available when it is enabled for your account; until then an order or invitation that asks for it is refused with 422 live_scope_not_enabled and nothing is placed. An order that omits liveScope runs relevant, unless matches has been made the default for your account; the order’s liveScope always says which ran. A record a "matches" order cannot confirm is held, not reported: see Held records.

Create an FCRA order API — POST /v1/fcra/orders request and response fields

POST/v1/fcra/ordersAuth: X-API-Key

Creates an order for one consumer with a sex offender search, a criminal search or both. Returns 202 with the order at received; the searches run in the background and report by webhook.

Request

Headers
FieldTypeDescription
Idempotency-Key
optional
stringUp to 200 characters. The same key with the same body within 24 hours returns the original order, with the response header Idempotent-Replayed: true; the same key with a different body is 409 idempotency_conflict.
Example "8f1c2a7e-order-889"
Body · application/json
FieldTypeDescription
endUserId
required
stringA registered, active end user on this account. Unknown: 404 unknown_end_user; suspended: 422 end_user_suspended.
Example "eu_0b44acbeefeaa7d7"
permissiblePurpose
required
string
one of "employment", "tenant_screening", "consumer_written_instructions", "legitimate_business_need"
One of employment, tenant_screening, consumer_written_instructions or legitimate_business_need. It must be held by the end user and covered by your agreement — otherwise 403 fcra_purpose_not_allowed, and the refusal is written to the evidence record.
consent
required
ConsentYour consent attestation.
subject
required
SubjectThe consumer.
useLocation
optional
UseLocation or nullWhere the job or housing is. When omitted, only the states in subject.addresses (and any jurisdiction that produces an exact date-of-birth candidate) are searched live.
annualSalary
optional
integer or nullEmployment only: the position's annual salary in US dollars, 0 to 100,000,000. At $75,000 or more the federal seven-year limit on non-conviction criminal items does not apply; a state limit still does.
searches
required
array of SearchSpecOne to three searches, each type at most once: any of [{"type":"sex_offender"}], [{"type":"criminal"}], [{"type":"healthcare"}].
clientReference
optional
string or nullYour order reference, up to 200 characters. Returned on the order and in the report, and filterable on GET /v1/fcra/orders.
Example "cra-order-889"
callbackUrl
optional
string (uri) or nullAn https:// URL that receives this order's events instead of your webhook endpoint, signed with the same secret. Requires a configured webhook endpoint (422 webhook_endpoint_required).
Example "https://your-cra.example/hooks/offendersearch"
liveScope
optional · default "relevant"
string
one of "relevant", "all", "matches"
relevant: each search runs live in every state in subject.addresses, in useLocation.state, and in every jurisdiction that produced an exact date-of-birth candidate. all: live in every source that supports a live search for that type. Every other source is searched in our data, and coverage says which was which. matches: our stored copies are searched for the subject and a subject with no possible record is answered from them, with no live calls. Each possible record is then confirmed live at the agency that keeps it before it can be reported; a source we hold no copy of is searched live. Available when enabled for your account.
scopePolicy
optional
ScopePolicy or nullOverrides on top of the end user's search-scope policy, for this order only.
addressSource
optional
string or null
one of "provided", "ssn_trace"
How the subject's address history is found. provided: you send subject.addresses (the address history) and no SSN — $4.95 per order. ssn_trace: you send the name, date of birth and subject.ssn; we run an SSN-based address history trace and the counties it finds pick the search scope, with any addresses you also send and the use location — $6.95 per order. Omitted: scopePolicy.addressSource, then the end user's default, else ssn_trace when subject.ssn is sent and provided when it is not (addresses then stay optional, as before). Errors: ssn_required, ssn_trace_unavailable, ssn_not_used_in_address_mode, addresses_required.
Example "ssn_trace"
metadata
optional
object or nullYour own key–value cross-references, up to 50 pairs (keys 1–40 characters, values up to 500). Echoed on the order; never in an event.
tags
optional
array of string or nullUp to 20 tags of 1–50 characters. Filter the order list by tag.

Response

202 · application/json

The order, accepted (or, for a replayed Idempotency-Key, the original order).

The body is the Order object. An FCRA order: its status, its end user and purpose, every search it carries, and the consumer portal access code.

Errors
StatusCodeWhen
401—No valid X-API-Key (the body is { "detail": "…" }, a string).
403fcra_not_enabledThis account has no active FCRA partner agreement.
403fcra_not_on_trialFCRA orders are not available on a trial account.
403fcra_purpose_not_allowedThe purpose is not held by the end user or not covered by your agreement. The refusal is written to the evidence record.
404unknown_end_userendUserId is not one of your end users.
409idempotency_conflictThe Idempotency-Key was used with a different body.
422end_user_suspendedThe end user is suspended.
422webhook_endpoint_requiredcallbackUrl was sent and no webhook endpoint is configured.
422validationThe Idempotency-Key is over 200 characters.
422ssn_requiredaddressSource is ssn_trace (sent, or the end user's default) and no subject.ssn was sent.
422ssn_trace_unavailableaddressSource is ssn_trace and SSN trace is not on for the account yet. Sandbox orders always trace.
422ssn_not_used_in_address_modesubject.ssn was sent with addressSource: "provided". The SSN is not echoed.
422addresses_requiredaddressSource: "provided" was chosen and subject.addresses is empty.
422—A field failed validation — a partial or future date of birth, a future consent time, an unknown purpose, search type or liveScope, a repeated search type, or an unexpected field (the standard validation body).

The Subject object — FCRA order subject fields

The consumer the order is about. A full date of birth is required: the FCRA controls furnish exact date-of-birth matches only.

Returned or accepted by POST /v1/fcra/orders, POST /v1/fcra/monitors, GET /v1/fcra/monitors, GET /v1/fcra/monitors/{monitor_id}, DELETE /v1/fcra/monitors/{monitor_id}, POST /v1/fcra/monitors/{monitor_id}/evaluate.

FieldTypeDescription
firstName
required
stringThe consumer's first name, 1 to 100 characters.
middleName
optional
string or nullMiddle name, up to 100 characters. Recorded in the evidence record.
lastName
required
stringThe consumer's last name, 1 to 100 characters. The consumer portal matches on it.
dob
required
string (date)A full, real, past date of birth, YYYY-MM-DD. A year, an age or a future date is a 422.
Example "1984-02-11"
aliases
optional
array of Alias or nullUp to 5 other names. Each is searched.
addresses
optional
array of SubjectAddress or nullUp to 20 addresses in the consumer's history. Required (at least one) with addressSource: "provided"; optional with ssn_trace.
npi
optional
string or nullHealthcare searches: the consumer's National Provider Identifier, 10 digits with a valid check digit (otherwise 422). Most exclusion lists publish no date of birth; a record there is reportable only when its NPI or license number matches one given here.
Example "1234567893"
licenses
optional
array of License or nullHealthcare searches: up to 10 professional licenses or certificates the consumer holds (a nurse-aide certificate, a nursing license).
ssn
optional
string or nullRequired with addressSource: "ssn_trace", refused otherwise (422 ssn_not_used_in_address_mode). The address history behind it is traced and its counties pick the search scope (identity.trace reports the outcome). Never stored and never returned: the order keeps the last four digits. 422 ssn_trace_unavailable until SSN trace is on for the account; sandbox orders always accept it.
Example "123-45-6789"

The Alias object — subject alias fields

Another name the consumer has used. Every alias is searched in addition to the subject's name.

Returned or accepted by POST /v1/fcra/orders, POST /v1/fcra/monitors, GET /v1/fcra/monitors, GET /v1/fcra/monitors/{monitor_id}, DELETE /v1/fcra/monitors/{monitor_id}, POST /v1/fcra/monitors/{monitor_id}/evaluate.

FieldTypeDescription
firstName
required
string1 to 100 characters.
lastName
required
string1 to 100 characters.

The License object — subject license fields

A professional license or certificate the consumer holds. A healthcare search matches a list entry on its number — compared without spaces, punctuation or zero padding, and in the same state when the entry names one.

Returned or accepted by POST /v1/fcra/orders, POST /v1/fcra/monitors, GET /v1/fcra/monitors, GET /v1/fcra/monitors/{monitor_id}, DELETE /v1/fcra/monitors/{monitor_id}, POST /v1/fcra/monitors/{monitor_id}/evaluate.

FieldTypeDescription
state
required
stringThe issuing state, two letters.
Example "TX"
number
required
stringThe license or certificate number, 1 to 40 characters.
Example "123456"
type
optional
string or nullWhat the credential is, as you name it (for your own reference).
Example "Certified Nurse Aide"

The SubjectAddress object — subject address history fields

One address in the consumer's history. Its county, the counties around it and its state come into the search scope (see Search scope); each state also brings its reporting limits to the criminal search.

Returned or accepted by POST /v1/fcra/orders, POST /v1/fcra/search-plans, POST /v1/fcra/monitors, GET /v1/fcra/monitors, GET /v1/fcra/monitors/{monitor_id}, DELETE /v1/fcra/monitors/{monitor_id}, POST /v1/fcra/monitors/{monitor_id}/evaluate.

FieldTypeDescription
state
required
stringTwo-letter state code, any case. Its state and county come into the search scope, and its seven-year conviction limit applies when it has one.
Example "IL"
city
optional
string or nullCity, up to 100 characters. Used to place the address in a county when there is no ZIP.
Example "Fort Worth"
line1
optional
string or nullStreet line, up to 200 characters. Kept with the order; not used for matching.
postalCode
optional
string or nullZIP code. The most reliable way to place the address in a county; it outranks the city name.
Example "76102"
county
optional
string or nullThe county, named directly, in any common form. Outranks the ZIP.
source
optional · default "declared"
string
one of "declared"
Where the address came from. Clients send declared only; traced addresses are added by the order when subject.ssn is given, and document is reserved for identity verification.
from
optional
string or nullWhen the consumer moved in: YYYY, YYYY-MM or YYYY-MM-DD.
Example "2019-01"
to
optional
string or nullWhen they moved out, same format. null for the current address. An address whose to is older than the policy's lookback is out of scope.

The UseLocation object — job or housing state

Where the job, the housing or the transaction is. Its state picks the reporting controls and is searched; its city, ZIP or county puts that county in the search scope.

Returned or accepted by POST /v1/fcra/orders, POST /v1/fcra/search-plans, POST /v1/fcra/invitations, POST /v1/fcra/monitors.

FieldTypeDescription
state
required
stringTwo-letter state code, any case.
Example "IL"
city
optional
string or nullCity, up to 100 characters.
Example "Fort Worth"
postalCode
optional
string or nullZIP code; outranks the city for placing the county.
county
optional
string or nullThe county, named directly; outranks the ZIP.

The SearchSpec object — FCRA search types

One search to run in the order.

Returned or accepted by POST /v1/fcra/orders, POST /v1/fcra/search-plans, POST /v1/fcra/invitations, GET /v1/fcra/invitations, GET /v1/fcra/invitations/{invitation_id}, DELETE /v1/fcra/invitations/{invitation_id}, POST /v1/fcra/invitations/{invitation_id}/resend, POST /v1/fcra/monitors, GET /v1/fcra/monitors, GET /v1/fcra/monitors/{monitor_id}, DELETE /v1/fcra/monitors/{monitor_id}, POST /v1/fcra/monitors/{monitor_id}/evaluate.

FieldTypeDescription
type
required
string
one of "sex_offender", "criminal", "healthcare"
The search to run. healthcare searches the HHS-OIG and SAM.gov exclusion lists, every state Medicaid exclusion list and every state nurse-aide registry we hold, in every state; it is included in the order price.
exclusions
optional · default "conviction_only"
string
one of "conviction_only", "all", "none"
Criminal searches only: which exclusion-list records the search may furnish. conviction_only (the default): only exclusions whose basis is a criminal conviction, furnished as convictions dated by the exclusion date. all: also the administrative tier — license actions, debarments, loan defaults — furnished with dispositionStatus: "sanction". none: no exclusion-list records. A list entry with no date of birth is withheld as insufficient_identifiers whatever the setting. Healthcare searches: all is the default when exclusions is omitted — every active exclusion and nurse-aide finding; conviction_only keeps conviction-based exclusions only; none is a 422.

The order object

GET /v1/fcra/orders/{id}
{
  "id": "fo_ee0b34c5b52fd35b",
  "status": "in_progress",
  "createdAt": "2026-10-02T14:01:07Z",
  "updatedAt": "2026-10-02T14:01:51Z",
  "completedAt": null,
  "cancelledAt": null,
  "clientReference": "cra-order-889",
  "endUserId": "eu_0b44acbeefeaa7d7",
  "permissiblePurpose": "employment",
  "useLocation": { "state": "IL" },
  "liveScope": "relevant",
  "controlVersion": "fcra-controls-2026-10-19.1",
  "sandbox": false,
  "eta": { "p50": "2026-10-02T14:03:00Z", "p90": "2026-10-02T14:09:00Z" },
  "searches": [
    { "id": "fs_452884eecde9a1f2", "type": "sex_offender", "status": "complete", "result": "clear",
      "recordCount": 0, "withheld": { "insufficient_identifiers": 2 },
      "createdAt": "2026-10-02T14:01:07Z", "startedAt": "2026-10-02T14:01:08Z",
      "completedAt": "2026-10-02T14:01:51Z", "supersededBy": null,
      "coverage": [ … ], "incompleteReasons": [] },
    { "id": "fs_9c03d7e1a4b6f258", "type": "criminal", "status": "in_progress", "result": null,
      "recordCount": 0, "withheld": {},
      "createdAt": "2026-10-02T14:01:07Z", "startedAt": "2026-10-02T14:01:09Z",
      "completedAt": null, "supersededBy": null,
      "coverage": [], "incompleteReasons": [] }
  ],
  "consumerPortal": {
    "url": "https://offendersearch.app/consumer/report",
    "accessCode": "K7QF-2MXP-9RDA"
  }
}
Order statusMeaning
receivedAccepted; nothing has run yet.
in_progressAt least one search is running.
partialSome searches are complete and others are not.
completeEvery search has finished. Read each search’s result.
cancelledCancelled before it completed.
errorEvery search in the order errored. Nothing was furnished; place a new order.

eta gives the 50th and 90th percentile completion times for the searches still running, from the last seven days of completions of each search type (a fixed estimate until five completions exist). It is null once the order is complete, cancelled or error.

The Order object — FCRA order response fields

An FCRA order: its status, its end user and purpose, every search it carries, and the consumer portal access code.

Returned or accepted by POST /v1/fcra/orders, GET /v1/fcra/orders, GET /v1/fcra/orders/{order_id}, POST /v1/fcra/orders/{order_id}/cancel, POST /v1/fcra/orders/{order_id}/adjudication.

FieldTypeDescription
id
stringThe order id. Use it on every other order route.
Example "fo_ee0b34c5b52fd35b"
status
string
one of "received", "in_progress", "partial", "complete", "cancelled", "error"
received (nothing has run), in_progress (a search is running), partial (some searches are finished, others are not), complete (every search finished — read each search's result), cancelled, or error (every search errored; nothing was furnished — place a new order).
createdAt
string (date-time)When the order was accepted.
updatedAt
string (date-time)When anything on the order last changed.
completedAt
string (date-time) or nullWhen the last search finished. null until the order is complete or error.
cancelledAt
string (date-time) or nullWhen it was cancelled. null unless status is cancelled.
clientReference
string or nullYour reference, as sent. null when you sent none.
endUserId
stringThe end user the order is for.
permissiblePurpose
string
one of "employment", "tenant_screening", "consumer_written_instructions", "legitimate_business_need"
The purpose stated on the order.
useLocation
object or nullThe job or housing location, as sent. null when you sent none.
useLocation.state
stringTwo-letter state code, upper-cased.
useLocation.city
string or nullThe city, as sent.
controlVersion
stringThe version of the controls this order runs under. The evidence record pins a hash of those exact rules.
Example "fcra-controls-2026-10-19.1"
liveScope
string
one of "relevant", "all", "matches"
The live scope the order runs with.
addressSource
string
one of "provided", "ssn_trace"
How this order got the subject's address history: provided (addresses sent) or ssn_trace (traced from the SSN; identity.trace reports the outcome). It also sets the price: $4.95 or $6.95.
eta
object or nullWhen the searches still running are expected to finish. null once the order is complete, cancelled or error, or when no search is queued or running.
eta.p50
string (date-time)Median expected completion, from the last seven days of completions of each search type still running (a fixed estimate until five completions exist), measured from when the search was created.
eta.p90
string (date-time)90th-percentile expected completion, on the same basis.
sandbox
booleantrue for a sandbox order: deterministic answers, no live calls, never metered.
source
string
one of "api", "dashboard", "invitation", "continuous"
How the order was placed: api (an API key), dashboard (a signed-in user), invitation (the consumer completed a hosted consent flow), continuous (a continuous check found a change).
metadata
object or nullYour metadata, as sent. null when you sent none.
tags
array of stringYour tags, sorted. Empty when you sent none.
revision
integerThe report revision. 1 at completion; it increases when a dispute changes what the report furnishes.
Example 1
revisedAt
string (date-time) or nullWhen the report was last revised. null until it is.
adjudication
string or null
one of "engaged", "pre_adverse_action", "post_adverse_action", "cleared"
The decision state you recorded on the order, if any.
scope
ScopeSummary or nullThe search scope in brief. null only for an order whose plan could not be computed.
identity
IdentityThe identity layer's status for this order.
consumer
object or nullThe consumer's contact for notices and whether they asked for a copy: from the hosted consent flow, or set with the consumer route. null when none. Shown only to the ordering account.
consumer.email
string or nullWhere consumer notices and the consumer's copy go. null when the consumer has not given one.
consumer.phone
string or nullThe consumer's phone, when they gave one. null otherwise.
consumer.copyRequested
booleantrue when the consumer ticked the box asking for a copy of their report.
consumer.locale
stringThe locale the consumer completed consent in (for example en-US).
searches
array of SearchEvery search on the order, superseded ones included. These carry no records; read one search to get them.
consumerPortal
objectWhat the consumer needs to see this order's file. Shown only to the account that placed the order.
consumerPortal.url
string (uri)The consumer portal address. Put it in the consumer's copy of the report or your pre-adverse notice.
consumerPortal.accessCode
stringThe order's access code: 12 characters in three groups of four, with no 0, O, 1, I or L. The consumer may type it with or without dashes, in any case.
Example "K7QF-2MXP-9RDA"

Retrieve an FCRA order — GET /v1/fcra/orders/{order_id}

GET/v1/fcra/orders/{order_id}Auth: X-API-Key

The order, its status, and the status and result of each search.

Request

Path parameters
FieldTypeDescription
order_id
required
stringThe order id (fo_…).
Example "fo_ee0b34c5b52fd35b"

Response

200 · application/json

The order.

The body is the Order object. An FCRA order: its status, its end user and purpose, every search it carries, and the consumer portal access code.

Errors
StatusCodeWhen
401—No valid X-API-Key (the body is { "detail": "…" }, a string).
403fcra_not_enabledThis account has no active FCRA partner agreement.
403fcra_not_on_trialFCRA orders are not available on a trial account.
404not_foundNo such order on this account.

List and cancel

GET /v1/fcra/orders?status=&clientReference=&cursor=&limit= lists your orders, newest first, 50 to a page by default (up to 200); pass the response’s nextCursor as cursor for the next page. POST /v1/fcra/orders/{id}/cancel cancels an order that has not finished — its queued searches become cancelled, and a search already running finishes — and returns 409 not_cancellable for an order that is already complete, error or cancelled.

List FCRA orders — GET /v1/fcra/orders query parameters and response

GET/v1/fcra/ordersAuth: X-API-Key

Your orders, newest first, one page at a time.

Request

Query parameters
FieldTypeDescription
status
optional
string
one of "received", "in_progress", "partial", "complete", "cancelled", "error"
Only orders with this status.
clientReference
optional
stringOnly orders with this clientReference.
endUserId
optional
stringOnly orders for this end user.
tag
optional
stringOnly orders carrying this tag.
source
optional
string
one of "api", "dashboard", "invitation", "continuous"
Only orders placed this way.
createdAfter
optional
string (date-time)Only orders created at or after this time.
createdBefore
optional
string (date-time)Only orders created before this time.
cursor
optional
stringThe nextCursor from the previous page (opaque).
limit
optional · default 50
integerOrders per page, 1 to 200.

Response

200 · application/json

One page of orders.

FieldTypeDescription
orders
array of OrderThe orders, newest first.
hasMore
booleanWhether another page follows.
nextCursor
string or nullSend as cursor for the next page. null when hasMore is false.
Errors
StatusCodeWhen
401—No valid X-API-Key (the body is { "detail": "…" }, a string).
403fcra_not_enabledThis account has no active FCRA partner agreement.
403fcra_not_on_trialFCRA orders are not available on a trial account.

Cancel an FCRA order — POST /v1/fcra/orders/{order_id}/cancel

POST/v1/fcra/orders/{order_id}/cancelAuth: X-API-Key

Cancels an order that has not finished. Its queued searches become cancelled; a search already running finishes.

Request

Path parameters
FieldTypeDescription
order_id
required
stringThe order id (fo_…).
Example "fo_ee0b34c5b52fd35b"

Response

200 · application/json

The cancelled order.

The body is the Order object. An FCRA order: its status, its end user and purpose, every search it carries, and the consumer portal access code.

Errors
StatusCodeWhen
401—No valid X-API-Key (the body is { "detail": "…" }, a string).
403fcra_not_enabledThis account has no active FCRA partner agreement.
403fcra_not_on_trialFCRA orders are not available on a trial account.
404not_foundNo such order on this account.
409not_cancellableThe order is already complete, error or cancelled.

Test FCRA orders on the sandbox server

With a test key (os_test_…) every account is a sandbox FCRA partner on the sandbox server, with the same last-name rules. Register an end user, then place orders against it; nothing is billed. An order finishes right after the 202: read it once with GET /v1/fcra/orders/{orderId}.

Base URL
https://sandbox.offendersearch.app Not https://api.offendersearch.app, which takes live keys only.
Test key
In the dashboard, Developers → API keys → Create test key. Test keys begin os_test_; send yours in the X-API-Key header.
1. POST /v1/fcra/end-users
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"
      }
    }'
2. POST /v1/fcra/orders
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"
        }
      ]
    }'

Try it here

Pick a scenario, edit the request, and run it against the sandbox from this page. The explorer accepts os_test_ keys only and never reaches the live host, so nothing here is billed; the “production” code it copies is for your own backend with a live key.

Create a test key under Dashboard → API keys. Live keys are refused here.
Copy this request as code

Sandbox code uses your test key. Production code calls the live host and is billed per call; run it from your backend with an os_live_… key.

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" } }'

Product overview