FCRA Partner API · v1.0.0 · approved partners

Controls & reason codes

Every control, in the order it runs, for each search type — with the reason code it writes.

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

How the controls run

Each search in an order first runs live in the relevant jurisdictions, and in our data everywhere else. Live and data candidates are merged under every name supplied, then pass the controls below in order. A relevant jurisdiction that cannot be searched live makes the result incomplete, never clear.

  • Sex offender — relevant registries: the registry of each state in subject.addresses and of useLocation.state, plus the registry of every exact-date-of-birth candidate. National registries are searched in our data unless liveScope is "all" or they produced a candidate.
  • Criminal — relevant sources: every live-capable court and custody source covering one of those states, plus the sources of every exact-date-of-birth candidate.
  • Restricted registries are never searched live. A registry whose records are withheld for the order’s purpose (California for every purpose; Nevada and New Jersey for tenant screening) shows restricted: true in coverage and does not make the result incomplete.
  • No addresses, no use state, no candidates: the order has no relevant jurisdictions, its result rests on our data, and every coverage row says mode: "snapshot". Send the address history to get live coverage.
  • liveScope: "matches" runs the other way round: our stored copies are searched first, and live checks run only for the possible records they find, for in-scope sources we hold no copy of, and for records on file without a date of birth. See Verification at the source below.

Then each candidate is checked in order. A candidate that fails one is withheld with that reason code. The controls are versioned: the order carries controlVersion, and the evidence record pins a hash of the exact rules that ran.

Sex offender search

StepControlReason code
aExact date of birth. Only a record whose date of birth matches the subject’s exactly can be furnished. A year, age or name-only match is withheld.insufficient_identifiers
bJurisdiction and purpose restrictions. California registry information is withheld for every purpose (Cal. Penal Code § 290.46(j)); Nevada (NRS 179B.270) and New Jersey (N.J.S.A. 2C:7-16(c)) registry information is withheld for tenant screening. The check covers each registry that holds the person.jurisdiction_restricted
cDisputes. A record removed by a resolved dispute is withheld from every later FCRA order.disputed_suppressed
dRe-verified before it is furnished. Each remaining record is re-verified with the official source. No longer listed: withheld. Source unreachable: withheld, and the result is incomplete (with liveScope: "matches": held, then withheld after five business days). Sealed, expunged or not public at the source (liveScope: "matches"): withheld.not_current_at_source · verification_unavailable · sealed_or_expunged

Criminal search

StepControlReason code
aExact date of birth, as above.insufficient_identifiers
bFederal seven-year rule. Charge by charge, an item that is not a conviction — an arrest, a dismissed or pending charge, a booking, a warrant — is removed once it is more than seven years old (15 U.S.C. § 1681c(a)(2), (a)(5)). Convictions are not limited by federal law. Employment at a stated annualSalary of $75,000 or more lifts this rule (§ 1681c(b)(3)).obsolete_non_conviction
cState seven-year limits. A conviction more than seven years old is removed when the record’s state, a state in subject.addresses, or useLocation.state is one of the states below. We apply each limit conservatively, without the exceptions some of those states allow; the salary exemption does not lift a state limit.time_limited
c2State bars on non-convictions. A charge that ended without a conviction — dismissed, acquitted, nolle prosequi, no bill, diversion, sealed — is removed at any age when the record’s state, a state in subject.addresses, or useLocation.state is California, Kentucky, New Mexico or New York. A pending charge is still reported, subject to step b.non_conviction_barred
—Missing date or disposition. If a seven-year rule could apply but the date or disposition needed to decide it is missing, the charge is removed rather than reported on a guess.obsolescence_undeterminable
dDisputes, as above.disputed_suppressed
eRe-verified before it is furnished, and the time rules run again on the fresh copy. With liveScope: "matches", a record the source cannot confirm yet is held, then withheld after five business days; one the source shows sealed, expunged or not public is withheld.not_current_at_source · verification_unavailable · sealed_or_expunged

Exclusion-list records. A conviction-based exclusion (exclusion.convictionBased: true) is a conviction dated by exclusion.excludedOn, so steps a–e apply to it unchanged. An administrative exclusion is the sanction kind: reportable as a current public-record status while the exclusion is in effect (lifecycle.droppedOut false, no past reinstatedOn) and, once it has ended, a non-conviction item measured from the reinstatement date under step b. It is furnished only when the search was placed with exclusions: "all"; conviction_only (the default) withholds it, and none withholds every exclusion-list record. Step a holds for both tiers: a list entry with no date of birth — most SAM.gov and state entries — is withheld as insufficient_identifiers.

States with a seven-year conviction limit

StateCitation
CACal. Civ. Code § 1786.18(a)(7)
COColo. Rev. Stat. § 5-18-109
KSKan. Stat. Ann. § 50-704 (citation under review)
MAMass. Gen. Laws ch. 93, § 52 (citation under review)
MDMd. Code, Com. Law § 14-1203 (citation under review)
MTMont. Code Ann. § 31-3-112
NHN.H. Rev. Stat. Ann. § 359-B:5 (citation under review)
NMN.M. Stat. Ann. § 56-3-6 (citation under review)
NYN.Y. Gen. Bus. Law § 380-j
TXTex. Bus. & Com. Code § 20.05
WAWash. Rev. Code § 19.182.040 (citation under review)

Healthcare search

StepControlReason code
aA strong identifier. A list entry is reportable only on the name plus a full date of birth (dob_match), the subject’s NPI (npi_match) or one of the subject’s license or certificate numbers (license_match). A name-only, birth-year, age or address match is withheld, and the search is incomplete with identifiers_needed.insufficient_identifiers
bTime rules, exactly as on the criminal search: a conviction-based exclusion is a conviction dated by excludedOn; an administrative exclusion or nurse-aide finding is the sanction kind — reportable while in effect, then judged by the seven-year rule and the state bars from the date it ended. The $75,000 salary exemption applies as above.obsolete_non_conviction · non_conviction_barred · obsolescence_undeterminable
cDisputes, as above.disputed_suppressed
dCurrent on the list. The entry must still be on the list in our latest copy and not reinstated, and the copy must be inside the source’s freshness window; a source that can be looked up per person is confirmed live.not_current_at_source · verification_unavailable

Verification at the source (liveScope matches)

A liveScope: "matches" order never reports a record from a copy. Each possible record our stored copies find is checked in full with the agency that keeps it — the court, the department of corrections, the state registry — before it can be reported, and the controls above run on that fresh copy. A record seen only in a secondary listing is never treated as confirmed: it is held until the agency itself confirms it.

At the source agencyWhat the order doesReported as
ConfirmedFurnished from the fresh copy, with a verification block; the fields the agency changed since our copy are in verification.changedSinceCopy.records[] · record.verified when it had been held
No longer thereWithheld.not_current_at_source
Sealed, expunged or not publicWithheld.sealed_or_expunged
No answer yet, or no live check for that sourceHeld: not reported, listed in held; the result is incomplete. We ask again 15 minutes, 1 hour and 4 hours later, then once a day, and run the search again when the agency answers.verification_pending · held[].status: "pending_verification" · record.verification_pending
No answer within five business daysWithheld.verification_unavailable · held[].status: "not_verifiable" · record.verification_failed
  • In-scope source with no stored copy: searched live; a failed live search makes the result incomplete with live_unavailable.
  • A record on file with no date of birth: looked up at its source to get one, for at most 10 sources per searched name; beyond that the search is incomplete rather than silently short.
  • The rules are pinned. A "matches" order’s evidence record pins a controls hash that also covers these verification rules (the hold period, the retry schedule and the reason codes), so the rules it ran under can be shown later. Orders with relevant or all keep the hash they always had.

The evidence record

Every accepted order writes an evidence record (a purpose refusal is written too) holding the end user, the purpose, your consent attestation, the subject identifiers, what each source answered, the control version and hash, and every record furnished or withheld with its reason. It is written once and never edited, so the rules a past answer ran under can be shown exactly.

Product overview