Orders
One order, one or both searches: create it, track its status, cancel it.
Livehttps://api.offendersearch.appSandboxhttps://sandbox.offendersearch.appCreate 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.
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 send | Price |
|---|---|---|
provided | The 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_trace | The 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).
{
"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 live | Use 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. |
all | Every 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. |
matches | Our 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
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
| Field | Type | Description |
|---|---|---|
| Idempotency-Key optional | string | Up 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" |
| Field | Type | Description |
|---|---|---|
| endUserId required | string | A 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 | Consent | Your consent attestation. |
| subject required | Subject | The consumer. |
| useLocation optional | UseLocation or null | Where 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 null | Employment 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 SearchSpec | One to three searches, each type at most once: any of [{"type":"sex_offender"}], [{"type":"criminal"}], [{"type":"healthcare"}]. |
| clientReference optional | string or null | Your 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 null | An 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 null | Overrides 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 null | Your 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 null | Up to 20 tags of 1–50 characters. Filter the order list by tag. |
Response
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.
| Status | Code | When |
|---|---|---|
| 401 | — | No valid X-API-Key (the body is { "detail": "…" }, a string). |
| 403 | fcra_not_enabled | This account has no active FCRA partner agreement. |
| 403 | fcra_not_on_trial | FCRA orders are not available on a trial account. |
| 403 | fcra_purpose_not_allowed | The purpose is not held by the end user or not covered by your agreement. The refusal is written to the evidence record. |
| 404 | unknown_end_user | endUserId is not one of your end users. |
| 409 | idempotency_conflict | The Idempotency-Key was used with a different body. |
| 422 | end_user_suspended | The end user is suspended. |
| 422 | webhook_endpoint_required | callbackUrl was sent and no webhook endpoint is configured. |
| 422 | validation | The Idempotency-Key is over 200 characters. |
| 422 | ssn_required | addressSource is ssn_trace (sent, or the end user's default) and no subject.ssn was sent. |
| 422 | ssn_trace_unavailable | addressSource is ssn_trace and SSN trace is not on for the account yet. Sandbox orders always trace. |
| 422 | ssn_not_used_in_address_mode | subject.ssn was sent with addressSource: "provided". The SSN is not echoed. |
| 422 | addresses_required | addressSource: "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 Consent object — FCRA consent attestation fields
Your attestation that you obtained the consumer's disclosure and authorization, recorded on the order and in its evidence record.
Returned or accepted by POST /v1/fcra/orders.
| Field | Type | Description |
|---|---|---|
| obtainedAt required | string (date-time) | When you obtained the consumer's authorization, ISO 8601. More than five minutes in the future is a 422. Example "2026-10-02T13:55:00Z" |
| method required | string one of "esign", "wet_signature", "electronic_click", "recorded_verbal", "other" | How it was obtained. |
| documentRef optional | string or null | Your reference to the signed authorization, up to 200 characters. |
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.
| Field | Type | Description |
|---|---|---|
| firstName required | string | The consumer's first name, 1 to 100 characters. |
| middleName optional | string or null | Middle name, up to 100 characters. Recorded in the evidence record. |
| lastName required | string | The 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 null | Up to 5 other names. Each is searched. |
| addresses optional | array of SubjectAddress or null | Up to 20 addresses in the consumer's history. Required (at least one) with addressSource: "provided"; optional with ssn_trace. |
| npi optional | string or null | Healthcare 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 null | Healthcare searches: up to 10 professional licenses or certificates the consumer holds (a nurse-aide certificate, a nursing license). |
| ssn optional | string or null | Required 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.
| Field | Type | Description |
|---|---|---|
| firstName required | string | 1 to 100 characters. |
| lastName required | string | 1 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.
| Field | Type | Description |
|---|---|---|
| state required | string | The issuing state, two letters. Example "TX" |
| number required | string | The license or certificate number, 1 to 40 characters. Example "123456" |
| type optional | string or null | What 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.
| Field | Type | Description |
|---|---|---|
| state required | string | Two-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 null | City, up to 100 characters. Used to place the address in a county when there is no ZIP. Example "Fort Worth" |
| line1 optional | string or null | Street line, up to 200 characters. Kept with the order; not used for matching. |
| postalCode optional | string or null | ZIP code. The most reliable way to place the address in a county; it outranks the city name. Example "76102" |
| county optional | string or null | The 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 null | When the consumer moved in: YYYY, YYYY-MM or YYYY-MM-DD.Example "2019-01" |
| to optional | string or null | When 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.
| Field | Type | Description |
|---|---|---|
| state required | string | Two-letter state code, any case. Example "IL" |
| city optional | string or null | City, up to 100 characters. Example "Fort Worth" |
| postalCode optional | string or null | ZIP code; outranks the city for placing the county. |
| county optional | string or null | The 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.
| Field | Type | Description |
|---|---|---|
| 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
{
"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 status | Meaning |
|---|---|
received | Accepted; nothing has run yet. |
in_progress | At least one search is running. |
partial | Some searches are complete and others are not. |
complete | Every search has finished. Read each search’s result. |
cancelled | Cancelled before it completed. |
error | Every 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.
| Field | Type | Description |
|---|---|---|
| id | string | The 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 null | When the last search finished. null until the order is complete or error. |
| cancelledAt | string (date-time) or null | When it was cancelled. null unless status is cancelled. |
| clientReference | string or null | Your reference, as sent. null when you sent none. |
| endUserId | string | The 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 null | The job or housing location, as sent. null when you sent none. |
| useLocation.state | string | Two-letter state code, upper-cased. |
| useLocation.city | string or null | The city, as sent. |
| controlVersion | string | The 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 null | When 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 | boolean | true 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 null | Your metadata, as sent. null when you sent none. |
| tags | array of string | Your tags, sorted. Empty when you sent none. |
| revision | integer | The report revision. 1 at completion; it increases when a dispute changes what the report furnishes. Example 1 |
| revisedAt | string (date-time) or null | When 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 null | The search scope in brief. null only for an order whose plan could not be computed. |
| identity | Identity | The identity layer's status for this order. |
| consumer | object or null | The 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 null | Where consumer notices and the consumer's copy go. null when the consumer has not given one. |
| consumer.phone | string or null | The consumer's phone, when they gave one. null otherwise. |
| consumer.copyRequested | boolean | true when the consumer ticked the box asking for a copy of their report. |
| consumer.locale | string | The locale the consumer completed consent in (for example en-US). |
| searches | array of Search | Every search on the order, superseded ones included. These carry no records; read one search to get them. |
| consumerPortal | object | What 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 | string | The 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}
The order, its status, and the status and result of each search.
Request
| Field | Type | Description |
|---|---|---|
| order_id required | string | The order id (fo_…).Example "fo_ee0b34c5b52fd35b" |
Response
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.
| Status | Code | When |
|---|---|---|
| 401 | — | No valid X-API-Key (the body is { "detail": "…" }, a string). |
| 403 | fcra_not_enabled | This account has no active FCRA partner agreement. |
| 403 | fcra_not_on_trial | FCRA orders are not available on a trial account. |
| 404 | not_found | No 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
Your orders, newest first, one page at a time.
Request
| Field | Type | Description |
|---|---|---|
| status optional | string one of "received", "in_progress", "partial", "complete", "cancelled", "error" | Only orders with this status. |
| clientReference optional | string | Only orders with this clientReference. |
| endUserId optional | string | Only orders for this end user. |
| tag optional | string | Only 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 | string | The nextCursor from the previous page (opaque). |
| limit optional · default 50 | integer | Orders per page, 1 to 200. |
Response
One page of orders.
| Field | Type | Description |
|---|---|---|
| orders | array of Order | The orders, newest first. |
| hasMore | boolean | Whether another page follows. |
| nextCursor | string or null | Send as cursor for the next page. null when hasMore is false. |
| Status | Code | When |
|---|---|---|
| 401 | — | No valid X-API-Key (the body is { "detail": "…" }, a string). |
| 403 | fcra_not_enabled | This account has no active FCRA partner agreement. |
| 403 | fcra_not_on_trial | FCRA orders are not available on a trial account. |
Cancel an FCRA order — POST /v1/fcra/orders/{order_id}/cancel
Cancels an order that has not finished. Its queued searches become cancelled; a search already running finishes.
Request
| Field | Type | Description |
|---|---|---|
| order_id required | string | The order id (fo_…).Example "fo_ee0b34c5b52fd35b" |
Response
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.
| Status | Code | When |
|---|---|---|
| 401 | — | No valid X-API-Key (the body is { "detail": "…" }, a string). |
| 403 | fcra_not_enabled | This account has no active FCRA partner agreement. |
| 403 | fcra_not_on_trial | FCRA orders are not available on a trial account. |
| 404 | not_found | No such order on this account. |
| 409 | not_cancellable | The 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.appNothttps://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 theX-API-Keyheader.
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"
}
}'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.
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" } }'Every test name: FCRA API sandbox ordersPostman collectionFCRA API sandbox