Results & records

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

Base URL https://api.offendersearch.app

View as MarkdownCopy the whole reference for an LLM

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_b52e",
  "type": "criminal",
  "status": "complete",
  "result": "records_found",
  "recordCount": 1,
  "withheld": { "insufficient_identifiers": 3, "obsolete_non_conviction": 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": ["cap_41a2c7"] },
    { "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": ["cap_41a2d1"] },
    { "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": [] }
  ],
  "incompleteReasons": [],
  "records": [
    {
      "recordId": "crim:IL-SANGAMON:2021CR004417",
      "type": "criminal",
      "matchBasis": { "state": "dob_match", "identifiers": ["name", "dob"] },
      "retrievedAt": "2026-10-02T14:02:40Z",
      "verifiedAt": "2026-10-02T14:04:09Z",
      "name": { "full": "JORDAN EXAMPLE" },
      "dob": "1984-02-11",
      "sources": [{ "code": "IL-SANGAMON", "level": "county" }],
      "dispositionStatus": "conviction",
      "cases": [
        { "caseNumber": "2021CR004417", "court": "Sangamon County Circuit Court",
          "filedDate": "2021-06-14",
          "charges": [
            { "description": "Retail theft", "level": "misdemeanor", "disposition": "Guilty",
              "dispositionDate": "2022-03-09", "fcraDisposition": "conviction" }
          ] }
      ],
      "fcraRedactions": { "obsolete_non_conviction": 1 },
      "…": "every other field of the criminal record object"
    }
  ]
}

Search status	Meaning
`queued`	Waiting to run.
`in_progress`	Matching, filtering and re-verifying.
`complete`	Finished; read `result`.
`unavailable`	The source system could not 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 and at least one record was furnished.
`clear`	Every relevant jurisdiction was searched live and answered, every other source answered, and nothing reportable was found. Never returned on a partial search. (Registries withheld for the order’s purpose are not searched and do not make a result incomplete.)
`incomplete`	A source did not answer, a relevant jurisdiction could not be searched live (`live_unavailable` in `incompleteReasons`), or a record could not be re-verified. Records that passed every control are still furnished; treat the answer as a lower bound.

Coverage — what is behind the result

Every search returns coverage[]: one row per source it searched, saying whether that source was searched live or from our data, when, and what it found. A clear is exactly the sum of these rows — read them before relying on one.

Field	Meaning
`source`	The source code (also used in `sources` on records).
`name`	The source’s name.
`jurisdiction`	The two-letter state or territory the source covers, or `US` for a national source.
`mode`	`live` — searched in real time for this order; `snapshot` — searched in our data.
`checkedAt`	When this source was searched for this order.
`dataAsOf`	For `snapshot` rows, the date our data for this source is current to. `null` for live rows.
`status`	`answered`, `unavailable` (could not be reached), or `not_searched`.
`relevant`	`true` when the source covers a relevant jurisdiction and so had to be searched live.
`restricted`	`true` when a jurisdiction rule for the order’s purpose applies to this source (its records are withheld as `jurisdiction_restricted`).
`candidates`	How many possible matches this source produced, before the controls.
`furnished`	How many of them were furnished.
`withheld`	How many were withheld (reasons are counted on the search’s `withheld`).
`captureIds`	The evidence captures taken from this source for this order — see Evidence & verification.

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) and/or verification_unavailable (a record could not be re-verified).

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 below:

Field	Meaning
`recordId`	A stable id. Use it to dispute the record.
`type`	`sex_offender` or `criminal`.
`matchBasis`	`{ state, identifiers, detail }` — `state` is always `dob_match` in an FCRA order; `identifiers` lists what agreed.
`retrievedAt`	When we obtained the record for this order.
`verifiedAt`	When it was re-verified with the official source for this order.
`corrections`	Present when a `modified` dispute changed this record: what changed, and the dispute that changed it.
`dispositionStatus` (criminal)	`conviction`, `non_conviction`, `mixed` or `unknown` across the charges furnished.
`cases[].charges[].fcraDisposition` (criminal)	How each furnished charge was classified: `conviction`, `non_conviction` or `unknown`.
`fcraRedactions` (criminal)	How many charges were removed from this record, by reason. Their content is never returned.

A furnished sex offender record

{
  "recordId": "so:WI:4418210",
  "type": "sex_offender",
  "matchBasis": { "state": "dob_match", "identifiers": ["name", "dob"], "detail": { … } },
  "retrievedAt": "2026-10-02T14:01:30Z",
  "verifiedAt": "2026-10-02T14:01:49Z",
  "name": { "full": "JORDAN EXAMPLE" },
  "registrationState": "WI",
  "offenses": [{ "description": "Sexual assault, second degree" }],
  "source": { "jurisdiction": "WI" },
  "…": "every other field of the sex offender record object"
}

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.

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. Only a finished search can be re-verified (409 search_not_finished), and not on a cancelled order (409 order_cancelled).

The report

GET /v1/fcra/orders/{id}/report returns every search, its coverage and every furnished record 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.