FCRA Partner API · v1.0.0 · approved partners

Results & records

Per-search results, live and data coverage by source, furnished records, held records and withheld counts.

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

The 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.

GET /v1/fcra/orders/{id}/searches/{searchId}
{
  "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 statusMeaning
queuedWaiting to run.
in_progressMatching, filtering and re-verifying.
completeFinished; read result.
unavailableNo source for this search could be reached; the result is incomplete.
errorThe search could not run. Nothing was furnished.
cancelledThe order was cancelled before this search ran.
supersededReplaced by a re-verified search; see supersededBy.
ResultMeaning
records_foundEvery 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.
clearEvery 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.
incompleteA 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.

FCRA search results API — GET /v1/fcra/orders/{order_id}/searches/{search_id} response fields

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

One search with its coverage and every furnished record.

Request

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

Response

200 · application/json

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.

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 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.

FieldTypeDescription
source
stringThe source code. Records name their source with the same code.
name
stringThe source's name.
jurisdiction
stringWhere 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 nullFor 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
booleantrue when the source covers a relevant jurisdiction and so had to be searched live.
restricted
booleantrue 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
integerPossible matches this source produced, before the controls.
furnished
integerHow many of them were furnished.
withheld
integerHow many were withheld. The reasons are counted on the search's withheld.
captureIds
array of stringThe 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
objectHealthcare 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 nullThe source's freshness window in days (HHS-OIG 14, SAM.gov 3, state lists 61).
freshness.ageDays
number or nullHow old our copy was when searched. null when the source has no completed refresh on record.
freshness.fresh
boolean or nulltrue 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
integerHealthcare rows only: candidates withheld as insufficient_identifiers because only the name agreed.
feeds
array of objectHealthcare 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 nullThe live check time, or our copy's last refresh. null when the list has no refresh on record.
feeds[].freshness
objectThis 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".

A furnished sex offender record
{
  "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.

FieldTypeDescription
recordId
stringThe 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
objectWhy 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 stringThe identifiers that agreed: ["name", "dob"], ["name", "npi"] or ["name", "license"].
matchBasis.detail
array of stringSex 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
objectliveScope: 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
stringThe 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 stringThe 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 stringThe evidence captures of that confirmation.
corrections
array of objectPresent only when a dispute resolved modified changed this record: each correction applied, oldest first.
corrections[].disputeId
stringThe dispute that made the correction.
corrections[].changes
objectWhat 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 objectCriminal 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 objectThe 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
objectCriminal 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
booleanPresent 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 verification block and you receive record.verified. Gone, sealed or expunged at the source: it is withheld (not_current_at_source, sealed_or_expunged) and you receive record.verification_failed.
  • Not confirmed within five business days: it is withheld as verification_unavailable, its held entry becomes not_verifiable, incompleteReasons carries verification_unavailable, and you receive record.verification_failed.
  • held and heldCount are present only on liveScope: "matches" searches.
A liveScope "matches" search with one record held
{
  "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_matchThe list publishes a full date of birth equal to the consumer’s (the HHS-OIG list, some state lists, some nurse-aide registries).
npi_matchThe list entry’s NPI equals the subject’s npi.
license_matchThe 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).

A healthcare search: one nurse-aide finding furnished, one name-only list entry withheld
{
  "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

POST/v1/fcra/searches/{search_id}/reverifyAuth: X-API-Key

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

Path parameters
FieldTypeDescription
search_id
required
stringThe finished search to run again (fs_…).
Example "fs_452884eecde9a1f2"

Response

202 · application/json

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.

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 search on this account.
409search_not_finishedThe search is not complete, unavailable or error.
409order_cancelledThe 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

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

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

Path parameters
FieldTypeDescription
order_id
required
stringThe order id (fo_…).
Example "fo_ee0b34c5b52fd35b"
Query parameters
FieldTypeDescription
revision
optional
integerAn 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

200 · application/json

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).

FieldTypeDescription
orderId
stringThe order id.
revision
integerThe report revision this is (1 at completion).
Example 1
revisedAt
string (date-time) or nullWhen it was last revised by a dispute. null until then.
removedRecordIds
array of stringRecords 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 nullWhen the order completed.
permissiblePurpose
string
one of "employment", "tenant_screening", "consumer_written_instructions", "legitimate_business_need"
The purpose stated on the order.
endUser
objectThe business the report is for.
endUser.id
stringThe end user id.
endUser.name
string or nullIts legal name.
clientReference
string or nullYour reference. null when you sent none.
subject
objectThe consumer, as sent on the order.
subject.firstName
stringFirst name.
subject.middleName
string or nullMiddle name. null when none was sent.
subject.lastName
stringLast name.
subject.dob
string (date)Full date of birth.
controlVersion
stringThe controls version the order ran under.
sandbox
booleantrue for a sandbox order.
liveScope
string
one of "relevant", "all", "matches"
The order's live scope.
searches
array of SearchEvery current search with its records. A superseded search is not in the report.
scope
ReportScope or nullWhere the report searched and why — the jurisdictions, the sources behind each, and the gaps.
identity
IdentityThe identity layer's status for this order.
evidence
array of CaptureEvery evidence capture behind the current searches (metadata; the bytes are one call away).
integrity
objectWhat the receipt signs.
integrity.reportSha256
stringSHA-256 of this report's canonical JSON — sorted keys, no whitespace — without the integrity block.
integrity.receiptUrl
stringThe 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
stringA one-sentence statement of how reportSha256 is computed.
integrity.pdfSha256
string or nullSHA-256 of the stored PDF, the file format=pdf returns.
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.
409report_not_readyThe order is not complete or error yet.

Product overview