Results & records
Per-search results, live and data coverage by source, furnished records, held records and withheld counts.
Livehttps://api.offendersearch.appSandboxhttps://sandbox.offendersearch.appThe search object
Every search in an order has its own status and result. GET /v1/fcra/orders/{id}/searches/{searchId} returns it with the records furnished.
{
"id": "fs_9c03d7e1a4b6f258",
"type": "criminal",
"status": "complete",
"result": "records_found",
"recordCount": 1,
"withheld": { "insufficient_identifiers": 1 },
"createdAt": "2026-10-02T14:01:07Z",
"startedAt": "2026-10-02T14:01:08Z",
"completedAt": "2026-10-02T14:04:12Z",
"supersededBy": null,
"coverage": [
{ "source": "IL-SANGAMON", "name": "Sangamon County Circuit Court", "jurisdiction": "IL",
"mode": "live", "checkedAt": "2026-10-02T14:02:38Z", "dataAsOf": null,
"status": "answered", "relevant": true, "restricted": false,
"candidates": 2, "furnished": 1, "withheld": 1, "captureIds": ["fc_41a2c7e09b3d5a18"] },
{ "source": "IL-DOC", "name": "Illinois Department of Corrections", "jurisdiction": "IL",
"mode": "live", "checkedAt": "2026-10-02T14:02:51Z", "dataAsOf": null,
"status": "answered", "relevant": true, "restricted": false,
"candidates": 0, "furnished": 0, "withheld": 0, "captureIds": ["fc_41a2d1f6c8e0b274"] },
{ "source": "WI-CCAP", "name": "Wisconsin Circuit Court Access", "jurisdiction": "WI",
"mode": "snapshot", "checkedAt": "2026-10-02T14:01:09Z", "dataAsOf": "2026-10-01",
"status": "answered", "relevant": false, "restricted": false,
"candidates": 0, "furnished": 0, "withheld": 0, "captureIds": [] }| Search status | Meaning |
|---|---|
queued | Waiting to run. |
in_progress | Matching, filtering and re-verifying. |
complete | Finished; read result. |
unavailable | No source for this search could be reached; the result is incomplete. |
error | The search could not run. Nothing was furnished. |
cancelled | The order was cancelled before this search ran. |
superseded | Replaced by a re-verified search; see supersededBy. |
| Result | Meaning |
|---|---|
records_found | Every source answered, every relevant jurisdiction was searched live, every re-verification got an answer, and at least one record was furnished. With liveScope: "matches", every possible record was confirmed with its source agency (or withheld) and none is still held. |
clear | Every relevant jurisdiction answered and nothing reportable was found: searched live wherever a per-person live lookup exists, and answered from our current copy (mode: "snapshot", dated by dataAsOf) where the source is a bulk list with no per-person lookup — or where a registry’s or criminal source’s live lookup is unavailable and our copy is under 48 hours old and holds nobody for the subject there (liveOutcome: "unavailable"). A record is never furnished from a copy: it is always confirmed live first. A relevant source with neither is listed not_searched in coverage, never as checked — and when every relevant source of a criminal search is not_searched, nothing was searched and the result is incomplete (no_source_searched), never clear. On a healthcare search every list is required: a list with no completed refresh on record makes the result incomplete (freshness_unknown). Never returned when a source failed. (Registries withheld for the order’s purpose are not searched live and do not make a result incomplete.) With liveScope: "matches", clear means our stored copies hold no possible record for the subject and every in-scope source we hold no copy of answered live; each coverage row still shows its dataAsOf. |
incomplete | A source did not answer, a relevant source’s live check failed (live_unavailable in incompleteReasons), no relevant source could be searched at all (no_source_searched), a healthcare list has no refresh on record (freshness_unknown), a record could not be re-verified, or — with liveScope: "matches" — a possible record is still being confirmed with its source agency (verification_pending, listed in held). Records that passed every control are still furnished; treat the answer as a lower bound. |
The Search object — FCRA search result fields
One search in an order: its status, its result, the source-by-source coverage behind it, and the counts of records withheld by reason.
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, GET /v1/fcra/orders/{order_id}/searches/{search_id}, POST /v1/fcra/searches/{search_id}/reverify, GET /v1/fcra/orders/{order_id}/report, POST /v1/fcra/orders/{order_id}/adjudication.
| Field | Type | Description |
|---|---|---|
| id | string | The search id. Example "fs_452884eecde9a1f2" |
| type | string one of "sex_offender", "criminal", "healthcare" | sex_offender, criminal or healthcare. |
| status | string one of "queued", "in_progress", "complete", "unavailable", "error", "cancelled", "superseded" | queued, in_progress, complete, unavailable (no source could be reached; result is incomplete), error (the search could not run; nothing furnished), cancelled (the order was cancelled before it ran) or superseded (replaced by a re-verified search — see supersededBy). |
| result | string or null one of "records_found", "clear", "incomplete" | records_found, clear or incomplete. null until the search finishes. clear means every relevant jurisdiction answered — live wherever a per-person live lookup exists, from our current copy where the source is a bulk list, or where a registry's live lookup is unavailable and our copy is under 48 hours old and holds nobody for the subject there (its coverage row says mode: "snapshot", dataAsOf, and liveOutcome when a live check was tried first; a record is never furnished from a copy) — every other source answered, and nothing reportable was found. A relevant source with no per-person lookup and no copy is listed not_searched, never as checked. incomplete means a source did not answer, a relevant source's live check failed, a record could not be re-verified, or (liveScope: matches) a possible record is still being confirmed with its source and is listed in held — read incompleteReasons, and treat the furnished records as a lower bound. |
| recordCount | integer | How many records were furnished. |
| withheld | object | Candidates that did not pass the controls, counted by reason code (insufficient_identifiers, jurisdiction_restricted, time_limited, disputed_suppressed, not_current_at_source, verification_unavailable, sealed_or_expunged (a matches search: the source now shows the record sealed, expunged or not public), and for criminal obsolete_non_conviction, non_conviction_barred, obsolescence_undeterminable). Only the counts: withheld content is never returned. {} when nothing was withheld.Example {"insufficient_identifiers":2} |
| createdAt | string (date-time) | When the search was added to the order. |
| startedAt | string (date-time) or null | When it started running. null while queued. |
| completedAt | string (date-time) or null | When it finished. null until then. |
| supersededBy | string or null | The id of the search that replaced this one after a re-verify. null otherwise. |
| coverage | array of CoverageRow | One row per source searched. [] until the search finishes. |
| incompleteReasons | array of string one of "source_unanswered", "live_unavailable", "no_source_searched", "freshness_unknown", "verification_unavailable", "verification_pending", "identifiers_needed" | Why the result is incomplete: source_unanswered, live_unavailable, no_source_searched (criminal: every relevant source is a not_searched gap), freshness_unknown (healthcare: a required list has no completed refresh on record), verification_unavailable verification_pending (a possible record is being confirmed with its source; see held) and/or identifiers_needed (healthcare: a list entry matched on the name only — it is withheld, never furnished; add the consumer's npi or licenses and order again). [] on every other result. |
| held | array of object | liveScope: matches only: possible records that are not on the report because their source agency has not confirmed them. Jurisdiction and type only, never the record's content. Make no decision on a search while heldCount is above 0. Absent on other searches. |
| held[].jurisdiction | string | The source code where the possible record was found. Example "IL-COOK" |
| held[].recordType | string | The kind of record, such as court_case or sex_offender. |
| held[].status | string one of "pending_verification", "not_verifiable" | pending_verification: being confirmed with the source agency; we ask it again on a schedule and the search is updated when it answers. not_verifiable: the agency could not confirm it within five business days, so it is not reported (counted under withheld.verification_unavailable). |
| heldCount | integer | liveScope: matches only: how many entries of held are pending_verification. Absent on other searches. |
| records | array of FurnishedRecord | Every furnished record. Present on GET /v1/fcra/orders/{order_id}/searches/{search_id} and in the report; the searches inside an order omit it. |
FCRA search results API — GET /v1/fcra/orders/{order_id}/searches/{search_id} response fields
One search with its coverage and every furnished record.
Request
| Field | Type | Description |
|---|---|---|
| order_id required | string | The order id (fo_…).Example "fo_ee0b34c5b52fd35b" |
| search_id required | string | The search id (fs_…).Example "fs_452884eecde9a1f2" |
Response
The search, with records.
The body is the Search object. One search in an order: its status, its result, the source-by-source coverage behind it, and the counts of records withheld by reason.
| 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 or search on this account. |
Coverage — what is behind the result
Every search returns coverage[]: one row per source it searched, saying whether that source was searched live or in our data, when, and what it found. A clear is exactly the sum of these rows — read them before relying on one. Every field of a row is in the CoverageRow object below.
When the result is incomplete, the search’s incompleteReasons says why: source_unanswered (a source did not answer), live_unavailable (a relevant jurisdiction could not be searched live — with liveScope: "matches", an in-scope source we hold no copy of), no_source_searched (criminal: every relevant source is a disclosed not_searched gap, so nothing about the consumer’s jurisdictions was searched), freshness_unknown (healthcare: a required list has no completed refresh on record, so we cannot vouch for our copy of it; its coverage row is unavailable with freshness.fresh: null), verification_unavailable (a record could not be re-verified; with liveScope: "matches", a possible record its agency did not confirm within five business days) and/or verification_pending (liveScope: "matches": a possible record is still being confirmed with its agency — see held).
On a liveScope: "matches" search each coverage row adds copyStatus — on_file (we hold a stored copy of the source and it answered) or none (we hold no copy) — and liveReason, why the source was contacted live for this order: candidate (a possible record was confirmed at its source), no_copy (we hold no copy of the source), dob_lookup (a record on file without a date of birth was looked up at its source), or null when it was not contacted.
The CoverageRow object — FCRA search coverage fields
One source a search covered: whether it was searched live or in our data, when, whether it answered, and what it produced. A clear is exactly the sum of these rows.
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, GET /v1/fcra/orders/{order_id}/searches/{search_id}, POST /v1/fcra/searches/{search_id}/reverify, GET /v1/fcra/orders/{order_id}/report, POST /v1/fcra/orders/{order_id}/adjudication.
| Field | Type | Description |
|---|---|---|
| source | string | The source code. Records name their source with the same code. |
| name | string | The source's name. |
| jurisdiction | string | Where the source covers: a two-letter code, US for a national sex offender registry, or a comma-separated list of codes for a source that covers several. A criminal source with no listed coverage repeats its source code. |
| mode | string one of "live", "snapshot" | live — searched at the official source for this order; snapshot — searched in our data. |
| checkedAt | string (date-time) | When this source was searched for this order. |
| dataAsOf | string (date-time) or null | For a snapshot row, when our data for this source was last complete. null on every live row, and on a snapshot row without that date. |
| status | string one of "answered", "unavailable", "not_searched" | answered (live, or from our current copy when mode is snapshot), unavailable (the check failed — the search is incomplete) or not_searched (the source has no per-person lookup and nothing on file: disclosed, never reported as checked; when every relevant criminal source is not_searched the search is incomplete with no_source_searched). A healthcare list with no completed refresh on record is unavailable, never not_searched. |
| relevant | boolean | true when the source covers a relevant jurisdiction and so had to be searched live. |
| restricted | boolean | true when a jurisdiction rule for the order's purpose applies to this registry: its records are withheld as jurisdiction_restricted, it is not searched live, and it does not make the result incomplete. Always false on criminal rows. |
| candidates | integer | Possible matches this source produced, before the controls. |
| furnished | integer | How many of them were furnished. |
| withheld | integer | How many were withheld. The reasons are counted on the search's withheld. |
| captureIds | array of string | The evidence captures taken from this source for this order. [] for a source searched in our data. |
| liveOutcome | string or null one of "unavailable" | Present only when a source's live check failed and our own copy answered instead (mode: "snapshot", dataAsOf): a registry's or criminal source's copy refreshed within 48 hours (a criminal copy may instead be inside the source's declared window) and holding no candidate for the subject there, or a healthcare list's copy inside its freshness window. A record is never furnished from a copy: a candidate still needs a live confirmation. |
| copyStatus | string one of "on_file", "none" | liveScope: matches only. on_file: we hold a copy of this source and it answered the search; none: we hold no copy, so the source was searched live where it supports a live search. |
| liveReason | string or null one of "candidate", "no_copy", "dob_lookup", "confirm_clear" | liveScope: matches only: why the source was contacted live for this order. candidate: a possible record was pulled at its source to confirm it. no_copy: we hold no copy of the source. dob_lookup: a record on file without a date of birth was looked up at its source. confirm_clear (healthcare): a source with a per-person lookup was asked live to confirm the consumer is not listed. null when it was not contacted. |
| freshness | object | Healthcare rows only: the source's declared freshness window and how old our copy is. A copy older than maxAgeDays makes the row unavailable; so does a source with no completed refresh on record (fresh: null, search incomplete with freshness_unknown). Not required on a row answered live (mode: "live"): the live answer is the proof. |
| freshness.maxAgeDays | integer or null | The source's freshness window in days (HHS-OIG 14, SAM.gov 3, state lists 61). |
| freshness.ageDays | number or null | How old our copy was when searched. null when the source has no completed refresh on record. |
| freshness.fresh | boolean or null | true inside the window; null when the source has no completed refresh on record (then status is unavailable and the search incomplete with freshness_unknown). |
| matchOn | array of string one of "full_dob", "npi", "license_number" | Healthcare rows only: the identifiers, besides the name, a match on this source can rest on. |
| heldForIdentifiers | integer | Healthcare rows only: candidates withheld as insufficient_identifiers because only the name agreed. |
| feeds | array of object | Healthcare rows of a source made of several lists only (US-EXCLUSION: the HHS-OIG list and SAM.gov). Each list is judged on its own: the row is answered only when every list answered — live, or from its own copy inside its own window. A record from one list is verified by that list only. |
| feeds[].feed | string one of "leie", "sam" | leie: the HHS-OIG List of Excluded Individuals/Entities (looked up live per person). sam: SAM.gov exclusions (searched in our copy). |
| feeds[].mode | string one of "live", "snapshot" | live when this list answered a live lookup for the consumer on this order; otherwise snapshot. |
| feeds[].dataAsOf | string or null | The live check time, or our copy's last refresh. null when the list has no refresh on record. |
| feeds[].freshness | object | This list's own window and copy age: maxAgeDays, ageDays, fresh (as on the row). Not required when mode is live. |
| feeds[].liveOutcome | string one of "unavailable" | Present when this list's live lookup failed and its copy answered (or could not). |
Furnished records
Only records that passed every control are furnished. Each keeps its product’s standard record object — the sex offender record from the Record object reference, or the criminal record from the Criminal Search API — plus the FCRA fields defined in the FurnishedRecord object below.
A furnished exclusion-list record (recordType: "healthcare_exclusion") keeps its exclusion block — program, authority, convictionBased, excludedOn, reinstatedOn — and reads dispositionStatus: "conviction" when the exclusion rests on a criminal conviction, or "sanction" when its basis is administrative; the sanction tier appears only when the search was placed with exclusions: "all".
{
"recordId": "rec_a51eafcbd203558b53f5",
"type": "sex_offender",
"matchBasis": { "state": "dob_match", "identifiers": ["name", "dob"],
"detail": ["lastName:exact", "firstName:exact", "name_match"] },
"retrievedAt": "2026-10-02T14:01:30Z",
"verifiedAt": "2026-10-02T14:01:30Z",
"name": { "first": "JORDAN", "middle": "", "last": "EXAMPLE", "suffix": "", "full": "JORDAN EXAMPLE" },
"dob": "1984-02-11",
"registrationState": "WI",
"offenses": [{ "crime": "Sexual assault, second degree", … }],
"source": { "jurisdiction": "WI", "registryName": "Wisconsin Sex Offender Registry", … },
"…": "every other field of the sex offender record object"
}Verification at the source
On a liveScope: "matches" search every furnished record was confirmed with the agency that keeps it for this order, and carries a verification object: status (always verified_at_source), source (the source code it was confirmed with), method (name_dob: found again at the source by name and date of birth; identifier: looked up by the source’s own case, booking or registry number), checkedAt, changedSinceCopy (the fields the source changed since our copy — the record shows the source’s current values; [] when nothing changed) and captureIds (the evidence of that confirmation). Records on relevant and all searches carry no verification.
The FurnishedRecord object — furnished record fields
A record that passed every control. It is the product's own record object — the sex offender Record object or the criminal record object — with the FCRA fields below added. On a sex offender record recordId and matchBasis replace the Record object's own fields of those names.
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, GET /v1/fcra/orders/{order_id}/searches/{search_id}, POST /v1/fcra/searches/{search_id}/reverify, GET /v1/fcra/orders/{order_id}/report, GET /v1/consumer/portal/report, POST /v1/fcra/orders/{order_id}/adjudication.
| Field | Type | Description |
|---|---|---|
| recordId | string | The furnished record's id. Send it in recordIds to dispute the record.Example "crim:IL-SANGAMON:2021CR004417" |
| type | string one of "sex_offender", "criminal", "healthcare" | sex_offender, criminal or healthcare. |
| matchBasis | object | Why the record was furnished. |
| matchBasis.state | string one of "dob_match", "npi_match", "license_match" | dob_match (exact date of birth) on sex offender and criminal records. A healthcare record is furnished on dob_match, npi_match (the record's NPI equals the consumer's npi) or license_match (its license or certificate number equals one of the consumer's licenses) — never on the name alone. |
| matchBasis.identifiers | array of string | The identifiers that agreed: ["name", "dob"], ["name", "npi"] or ["name", "license"]. |
| matchBasis.detail | array of string | Sex offender records only: the record's own matchBasis tokens from the Record object, such as lastName:exact. |
| retrievedAt | string (date-time) | When the record was obtained for this order. |
| verifiedAt | string (date-time) | When it was re-verified with the official source for this order. |
| verification | object | liveScope: matches only: how the record was confirmed at its source for this order. |
| verification.status | string one of "verified_at_source" | Always verified_at_source: a record is reported only after its source confirms it. |
| verification.source | string | The source code the record was confirmed with. Example "IL-COOK" |
| verification.method | string one of "name_dob", "identifier" | name_dob: found again at the source by name and date of birth; identifier: looked up by the source's own case, booking or registry number. |
| verification.checkedAt | string (date-time) | When the source confirmed it. |
| verification.changedSinceCopy | array of string | The fields the source changed since our copy, such as cases[0].charges[0].disposition. The record shows the source's current values. [] when nothing changed. |
| verification.captureIds | array of string | The evidence captures of that confirmation. |
| corrections | array of object | Present only when a dispute resolved modified changed this record: each correction applied, oldest first. |
| corrections[].disputeId | string | The dispute that made the correction. |
| corrections[].changes | object | What changed, as recorded when the dispute was resolved. |
| corrections[].correctedAt | string (date-time) | When the correction was recorded. |
| dispositionStatus | string one of "conviction", "non_conviction", "sanction", "mixed", "unknown" | Criminal records only: conviction, non_conviction, sanction, mixed or unknown, across the charges furnished. sanction is an exclusion-list record whose basis is not a criminal conviction — furnished only when the search asked for exclusions: "all"; a conviction-based exclusion reads conviction. |
| cases | array of object | Criminal records only: the criminal record's own cases, keeping only the charges that passed the controls. Every field of a case and a charge is as the criminal record defines it, plus the one below. |
| cases[].charges | array of object | The furnished charges. |
| cases[].charges[].fcraDisposition | string one of "conviction", "non_conviction", "sanction", "unknown" | How the charge was classified for the FCRA time rules: conviction, non_conviction, sanction (an exclusion-list entry whose basis is not a conviction) or unknown. |
| fcraRedactions | object | Criminal records only, present when charges were removed: how many, by reason code (obsolete_non_conviction, non_conviction_barred, time_limited, obsolescence_undeterminable). Their content is never returned.Example {"obsolete_non_conviction":1} |
| sandbox | boolean | Present and true on every sandbox record, whose recordId begins sandbox:. |
Withheld records
withheld counts the candidates that did not pass, by reason code (see Controls & reason codes). Their content is never returned — not in the search, the report, the webhook or the consumer portal. A liveScope: "matches" search adds sealed_or_expunged (the source agency now shows the record sealed, expunged or not public); there, not_current_at_source means the agency no longer has the record and verification_unavailable means it did not confirm it within five business days.
Held records under liveScope matches
A possible record that its source agency has not confirmed yet is held: it is not on the report, not in records, not in the PDF and not in the consumer portal. The search lists it in held — jurisdiction, record type and status only, never its content — and heldCount counts the entries still pending_verification. The search completes with result incomplete and verification_pending in incompleteReasons. Make no decision on a search while heldCount is above 0.
- A record is held when its source agency cannot be reached, when it was seen only in a secondary listing and not yet at the agency itself, or when no live check exists for its source.
- We ask the agency again 15 minutes, 1 hour and 4 hours after the hold, then once a day. When it answers, the search is run again exactly as a re-verify: a new search supersedes the old one, the order returns to
in_progress, and it completes with a new report, PDF and receipt. - Confirmed: the record is furnished with its
verificationblock and you receiverecord.verified. Gone, sealed or expunged at the source: it is withheld (not_current_at_source,sealed_or_expunged) and you receiverecord.verification_failed. - Not confirmed within five business days: it is withheld as
verification_unavailable, itsheldentry becomesnot_verifiable,incompleteReasonscarriesverification_unavailable, and you receiverecord.verification_failed. heldandheldCountare present only onliveScope: "matches"searches.
{
"id": "fs_7d21c0a9e4b3f516",
"type": "criminal",
"status": "complete",
"result": "incomplete",
"recordCount": 1,
"withheld": { "insufficient_identifiers": 1 },
"coverage": [
{ "source": "IL-SANGAMON", "name": "Sangamon County Circuit Court", "jurisdiction": "IL",
"mode": "live", "checkedAt": "2026-10-30T14:02:11Z", "dataAsOf": null,
"status": "answered", "relevant": true, "restricted": false,
"candidates": 2, "furnished": 1, "withheld": 1,
"copyStatus": "on_file", "liveReason": "candidate", "captureIds": ["fc_461d419f538a882c"] },
{ "source": "IL-COOK", "name": "Cook County Circuit Court", "jurisdiction": "IL",
"mode": "snapshot", "checkedAt": "2026-10-30T14:01:09Z", "dataAsOf": "2026-10-29",
"status": "answered", "relevant": true, "restricted": false,
"candidates": 1, "furnished": 0, "withheld": 0,
"copyStatus": "on_file", "liveReason": "candidate", "liveOutcome": "unavailable",
"captureIds": [] }
],
"incompleteReasons": ["verification_pending"],
"held": [
{ "jurisdiction": "IL-COOK", "recordType": "court_case", "status": "pending_verification" }
],Healthcare results
A healthcare search (type: "healthcare") returns the same search object. Its records are exclusion-list and nurse-aide registry records (recordType: "healthcare_exclusion") with their exclusion block: program (medicare_medicaid, federal_procurement, state_medicaid or nurse_aide_registry), authority, convictionBased, excludedOn, reinstatedOn, excludingAgency, npi, licenseNumber and, on a nurse-aide finding, findingType (abuse, neglect, misappropriation or other). A conviction-based exclusion reads dispositionStatus: "conviction"; an administrative exclusion or a nurse-aide finding reads "sanction".
What a healthcare record is matched on
| `matchBasis.state` | Furnished when |
|---|---|
dob_match | The list publishes a full date of birth equal to the consumer’s (the HHS-OIG list, some state lists, some nurse-aide registries). |
npi_match | The list entry’s NPI equals the subject’s npi. |
license_match | The list entry’s license or certificate number equals one of the subject’s licenses — compared without spaces, punctuation or zero padding, and in the same state when the entry names one. |
Anything else — the name alone, a birth year or age, a city or an address — is not a match. The candidate is withheld as insufficient_identifiers, its content is never returned, and because a list entry we cannot place is not a clear, the search completes incomplete with identifiers_needed in incompleteReasons. Add the consumer’s npi or licenses and place a new order. A list entry whose date of birth differs from the consumer’s is not a candidate at all, and an NPI or license match never overrides it.
identifiers_needed appears only on healthcare searches. It is not an error and not a pending state: nothing will change until you order again with more identifiers.
Healthcare coverage
One coverage row per healthcare source. A list that is a file the agency republishes is searched in our current copy (mode: "snapshot"). A source that can be looked up per person is also asked live for the consumer on every order, under every name: when it answers, the row is mode: "live" with dataAsOf set to the time of that live check, and it is answered however old our copy is — the live answer is the proof, so freshness is shown but not required. When that live lookup fails, the row falls back to our copy under the rules below and adds liveOutcome: "unavailable". Each row adds freshness — maxAgeDays (the source’s window: 14 days for the HHS-OIG list, which is replaced by the 10th of each month; 3 for SAM.gov, published daily; 61 for the state lists), ageDays (how old our copy was) and fresh — matchOn (the identifiers a match on that source can rest on) and heldForIdentifiers (candidates withheld because only the name agreed). A copy older than its window makes the row unavailable and the search incomplete (source_unanswered). Every healthcare list is required, so a list with no completed refresh on record is never a disclosed gap: its row is unavailable with freshness.fresh: null and ageDays: null, and the search is incomplete with freshness_unknown — never clear.
The federal exclusion source (US-EXCLUSION) is two lists: the HHS-OIG list, which is looked up live for the consumer, and SAM.gov, which is searched in our copy. Each is judged on its own and listed under the row’s feeds (feed, mode, dataAsOf, freshness, liveOutcome): the row is answered only when the HHS-OIG list answered — live, or from its own up-to-date copy if the live lookup failed — and our SAM.gov copy is inside its own 3-day window. A SAM.gov entry is verified by SAM.gov’s copy only, never by the HHS-OIG answer.
A healthcare record is verified by its list, not by a per-person call: it must still be on the list in our latest copy, not reinstated, and that copy must be inside the source’s window. Gone from the list or reinstated: withheld not_current_at_source. Copy out of date: withheld verification_unavailable. A source that can be looked up per person is confirmed live at the source like a criminal record: an entry it still lists is furnished from the live answer (even when our copy is out of date), an entry it no longer lists is withheld not_current_at_source (an entry filed under a different first name than the consumer’s is first looked up again under its own name, and is withheld verification_unavailable if that lookup fails), a listing the live lookup finds that our copy lacks is matched like any other, and when the live lookup fails the entry is withheld verification_unavailable — never furnished from our copy. Healthcare records carry no verification block and are never held, under every liveScope; on a liveScope: "matches" order their coverage rows also carry copyStatus and liveReason (candidate when a possible entry was confirmed there, confirm_clear when the source was asked live with no candidate).
{
"id": "fs_3b9e51c0d27a4f86",
"type": "healthcare",
"status": "complete",
"result": "incomplete",
"recordCount": 1,
"withheld": { "insufficient_identifiers": 1 },
"coverage": [
{ "source": "US-EXCLUSION", "name": "Federal — Exclusion list", "jurisdiction": "US",
"mode": "snapshot", "checkedAt": "2026-10-30T14:02:11Z", "dataAsOf": "2026-10-27T03:10:00Z",
"status": "answered", "relevant": true, "restricted": false,
"candidates": 1, "furnished": 0, "withheld": 1,
"freshness": { "maxAgeDays": 14, "ageDays": 3.5, "fresh": true },
"matchOn": ["full_dob", "npi"], "heldForIdentifiers": 1, "captureIds": ["fc_0a7d3e91b25c4f68"] },
{ "source": "TX-NURSE-AIDE", "name": "Texas — statewide nurse aide registry", "jurisdiction": "TX",
"mode": "snapshot", "checkedAt": "2026-10-30T14:02:11Z", "dataAsOf": "2026-10-12T02:40:00Z",
"status": "answered", "relevant": true, "restricted": false,
"candidates": 1, "furnished": 1, "withheld": 0,
"freshness": { "maxAgeDays": 61, "ageDays": 18.5, "fresh": true },
"matchOn": ["license_number"], "heldForIdentifiers": 0, "captureIds": ["fc_5c2e8b17d94a0f33"] }
],
"incompleteReasons": ["identifiers_needed"],
"records": [
{Re-verify a search
POST /v1/fcra/searches/{searchId}/reverify returns 202 and adds a new search of the same type to the order. The old search becomes superseded, with supersededBy pointing at the new one. The order returns to in_progress, and when it completes again it gets a new report, PDF and receipt. Only a finished search can be re-verified (409 search_not_finished), and not on a cancelled order (409 order_cancelled). A liveScope: "matches" search with held records is re-run this way on its own when the source agency answers; you do not need to call it.
Re-verify an FCRA search — POST /v1/fcra/searches/{search_id}/reverify
Adds a new search of the same type to the order and marks this one superseded, with supersededBy pointing at the new one. The order returns to in_progress.
Request
| Field | Type | Description |
|---|---|---|
| search_id required | string | The finished search to run again (fs_…).Example "fs_452884eecde9a1f2" |
Response
The new search, status queued.
The body is the Search object. One search in an order: its status, its result, the source-by-source coverage behind it, and the counts of records withheld by reason.
| 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 search on this account. |
| 409 | search_not_finished | The search is not complete, unavailable or error. |
| 409 | order_cancelled | The order was cancelled. |
The report
GET /v1/fcra/orders/{id}/report returns every current search (a superseded one is left out), its coverage, every furnished record and the metadata of every evidence capture in one document, as JSON or as the stored PDF. The PDF, its hashes, the evidence captures and the signed receipt are covered in Evidence & verification.
FCRA report API — GET /v1/fcra/orders/{order_id}/report response fields
The furnished report in one document: as JSON, or as the PDF rendered once when the order completed and stored, so its bytes and hash stay the same unless a re-verify completes the order again with a new report.
Request
| Field | Type | Description |
|---|---|---|
| order_id required | string | The order id (fo_…).Example "fo_ee0b34c5b52fd35b" |
| Field | Type | Description |
|---|---|---|
| revision optional | integer | An earlier revision of the report (see revisions); the current one when omitted. |
| format optional · default "json" | string one of "json", "pdf" | json returns the report object; pdf returns the stored PDF with X-Report-SHA256 and X-PDF-SHA256 headers. |
Response
format=json: the report object below. format=pdf: the stored PDF bytes as application/pdf, with X-Report-SHA256 (the report's reportSha256) and X-PDF-SHA256 (the SHA-256 of these bytes, as signed in the receipt).
| Field | Type | Description |
|---|---|---|
| orderId | string | The order id. |
| revision | integer | The report revision this is (1 at completion). Example 1 |
| revisedAt | string (date-time) or null | When it was last revised by a dispute. null until then. |
| removedRecordIds | array of string | Records a dispute removed since completion (empty on revision 1). |
| status | string one of "complete", "error" | complete, or error when every search errored. |
| createdAt | string (date-time) | When the order was accepted. |
| completedAt | string (date-time) or null | When the order completed. |
| permissiblePurpose | string one of "employment", "tenant_screening", "consumer_written_instructions", "legitimate_business_need" | The purpose stated on the order. |
| endUser | object | The business the report is for. |
| endUser.id | string | The end user id. |
| endUser.name | string or null | Its legal name. |
| clientReference | string or null | Your reference. null when you sent none. |
| subject | object | The consumer, as sent on the order. |
| subject.firstName | string | First name. |
| subject.middleName | string or null | Middle name. null when none was sent. |
| subject.lastName | string | Last name. |
| subject.dob | string (date) | Full date of birth. |
| controlVersion | string | The controls version the order ran under. |
| sandbox | boolean | true for a sandbox order. |
| liveScope | string one of "relevant", "all", "matches" | The order's live scope. |
| searches | array of Search | Every current search with its records. A superseded search is not in the report. |
| scope | ReportScope or null | Where the report searched and why — the jurisdictions, the sources behind each, and the gaps. |
| identity | Identity | The identity layer's status for this order. |
| evidence | array of Capture | Every evidence capture behind the current searches (metadata; the bytes are one call away). |
| integrity | object | What the receipt signs. |
| integrity.reportSha256 | string | SHA-256 of this report's canonical JSON — sorted keys, no whitespace — without the integrity block. |
| integrity.receiptUrl | string | The public receipt for this order: /v1/fcra/receipts/{order_id}. |
| integrity.verifyUrl | string (uri) | The page where anyone holding the PDF can check it: https://offendersearch.app/verify/{order_id}. |
| integrity.note | string | A one-sentence statement of how reportSha256 is computed. |
| integrity.pdfSha256 | string or null | SHA-256 of the stored PDF, the file format=pdf returns. |
| 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 | report_not_ready | The order is not complete or error yet. |