FCRA Partner API · v1.0.0 · approved partners

Evidence & verification

Official-source captures, the stored PDF, the signed receipt and how to verify a report.

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

Official-source evidence

Every live check in an order — whether it finds a match or not — keeps hash-pinned evidence, so a clear can be shown, not only asserted. Each capture records its time, a SHA-256 hash and the bytes, and says which kind it is:

`kind`What it is
source_responseThe official source’s own response, as received: URL, HTTP status, content type and body. Recorded wherever the live check receives the source’s response directly.
parsed_resultOur structured reading of what that source’s live search returned, as canonical JSON. Recorded for every live sex-offender check, so no check is ever without evidence.
service_resultFor criminal searches: the criminal records service’s live answer for that source.

A body over 2,000,000 bytes is stored up to that limit with truncated: true — its sha256 and size still describe the full body — and at most 25 captures are kept per source in each search. Captures are kept for as long as the order’s evidence record.

GET /v1/fcra/orders/{id}/evidence
{
  "orderId": "fo_ee0b34c5b52fd35b",
  "captures": [
    { "captureId": "fc_31f0a9c2d4e6b801", "searchId": "fs_452884eecde9a1f2", "source": "WI",
      "kind": "source_response",
      "url": "https://…official registry search page…",
      "retrievedAt": "2026-10-02T14:01:31Z", "httpStatus": 200,
      "contentType": "text/html; charset=utf-8",
      "sha256": "e3b0c442…b855", "size": 48213, "truncated": false },
    { "captureId": "fc_31f0b2e5a7c9d013", "searchId": "fs_452884eecde9a1f2", "source": "WI",
      "kind": "parsed_result", "url": null,
      "retrievedAt": "2026-10-02T14:01:31Z", "httpStatus": null,
      "contentType": "application/json",
      "sha256": "9f86d081…0f00", "size": 2210, "truncated": false }
  ]
}

GET /v1/fcra/orders/{id}/evidence/{captureId} returns one capture’s stored bytes, with its original content type and the headers X-Capture-SHA256, X-Capture-Kind, X-Capture-Source and X-Capture-Truncated. Only the account that placed the order can read them. Each search’s coverage rows list the captureIds taken from that source.

Every capture is either bytes a source returned or our labelled reading of them. Nothing in an FCRA report is a re-creation of a source’s page.

On a liveScope: "matches" order, the confirmation of each furnished record is a live check like any other: its captures are listed in the record’s verification.captureIds as well as on the source’s coverage row, and the evidence record keeps, per record, how it was confirmed and which fields the source changed since our copy (verification.changedSinceCopy).

The Capture object — FCRA evidence capture fields

One piece of official-source evidence taken during a live check: what it is, where it came from, when, and its SHA-256. The bytes are at GET /v1/fcra/orders/{order_id}/evidence/{capture_id}.

Returned or accepted by GET /v1/fcra/orders/{order_id}/report, GET /v1/fcra/orders/{order_id}/evidence.

FieldTypeDescription
captureId
stringThe capture id. GET /v1/fcra/orders/{order_id}/evidence/{capture_id} returns its bytes.
Example "fc_461d419f538a882c"
searchId
stringThe search it was taken for.
source
stringThe source code, matching a coverage row.
kind
string
one of "source_response", "parsed_result", "service_result"
source_response — the official source's own response as received; parsed_result — our structured reading of that source's live search, as canonical JSON (recorded for every live sex offender check); service_result — for criminal searches, the criminal records service's live answer for that source.
url
string or nullThe URL the source response came from. null on parsed_result and service_result captures.
retrievedAt
string (date-time)When it was taken.
httpStatus
integer or nullThe source's HTTP status. null on parsed_result and service_result captures.
contentType
string or nullThe stored body's content type.
sha256
stringSHA-256 of the full body, also when the stored copy is truncated.
size
integerSize of the full body, in bytes.
truncated
booleantrue when the body was over 2,000,000 bytes and the stored copy stops at that limit. At most 25 captures are kept per source per search.

FCRA evidence API — GET /v1/fcra/orders/{order_id}/evidence response fields

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

Every official-source capture taken for the order, with its hash. Only the account that placed the order can read them.

Request

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

Response

200 · application/json

The capture metadata.

FieldTypeDescription
orderId
stringThe order id.
captures
array of CaptureEvery capture, superseded searches included.
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.

Download an FCRA evidence capture — GET /v1/fcra/orders/{order_id}/evidence/{capture_id}

GET/v1/fcra/orders/{order_id}/evidence/{capture_id}Auth: X-API-Key

One capture's stored bytes, exactly as kept, as a file download.

Request

Path parameters
FieldTypeDescription
order_id
required
stringThe order id (fo_…).
Example "fo_ee0b34c5b52fd35b"
capture_id
required
stringThe capture's captureId (fc_…).
Example "fc_461d419f538a882c"

Response

200 · the capture's own content type

The stored bytes, with the headers below.

FieldTypeDescription
X-Capture-SHA256
string (header)The capture's sha256: the hash of the full body.
X-Capture-Kind
string (header)source_response, parsed_result or service_result.
X-Capture-Source
string (header)The source code.
X-Capture-Truncated
string (header)true when the stored copy stops at 2,000,000 bytes, otherwise false.
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 capture on this account.

The stored PDF

GET /v1/fcra/orders/{id}/report?format=pdf returns the PDF rendered once, when the order completed, and stored — so its bytes, and its hash, stay the same unless a re-verify completes the order again with a new report. It lists every current search with its result and coverage, every furnished record with the name and date of birth it carries and when it was re-verified (on a liveScope: "matches" order, the source it was confirmed with and what the source changed since our copy), each held record as its jurisdiction only, the withheld counts, every evidence capture with its hash, and a QR code to the order’s verification page. The PDF response carries its hash in the X-PDF-SHA256 header and the report’s in X-Report-SHA256. format=json returns the same report as JSON, with the capture metadata in evidence[] and an integrity block holding reportSha256 (computed over the canonical JSON without that block), pdfSha256, receiptUrl and verifyUrl. Both are available once the order is complete or error (409 report_not_ready before then).

The signed receipt

GET /v1/fcra/receipts/{orderId} — public, no key — returns an Ed25519-signed receipt. The signature covers the fields listed in signedFields: the order id, the completion time, the control version, reportSha256 and pdfSha256. The receipt contains no personal data. It returns 404 for an unknown or unfinished order, and 503 receipts_unavailable when receipt signing is unavailable.

GET /v1/fcra/receipts/{orderId}
{
  "orderId": "fo_ee0b34c5b52fd35b",
  "completedAt": "2026-10-02T14:04:13Z",
  "controlVersion": "fcra-controls-2026-10-19.1",
  "reportSha256": "4b1f…9e0c",
  "pdfSha256": "a90d…71b4",
  "issuedAt": "2026-10-02T14:04:13Z",
  "algorithm": "Ed25519",
  "alg": "Ed25519",
  "keyId": "ed25519:88f16fa019c4132c",
  "signature": "Qk3x…",
  "publicKeyPem": "-----BEGIN PUBLIC KEY-----\n…\n-----END PUBLIC KEY-----\n",
  "signedFields": ["completedAt", "controlVersion", "orderId", "pdfSha256", "reportSha256"],
  "canonicalization": "Ed25519 signature (base64url, no padding) over the UTF-8 JSON of exactly the fields listed in signedFields, …"
}

FCRA signed receipt API — GET /v1/fcra/receipts/{order_id}

GET/v1/fcra/receipts/{order_id}No API key

Public, no API key: the Ed25519-signed receipt for a completed order. It contains no personal data.

Request

No API key.

Path parameters
FieldTypeDescription
order_id
required
stringThe order id (fo_…).
Example "fo_ee0b34c5b52fd35b"
Query parameters
FieldTypeDescription
revision
optional
integerThe receipt of an earlier revision; the current one when omitted.

Response

200 · application/json

The signed receipt.

FieldTypeDescription
revision
integerThe revision this receipt is for. Signed when greater than 1.
Example 1
currentRevision
integerThe order's current revision.
Example 1
orderId
stringThe order id. Signed.
completedAt
string (date-time)When the order completed. Signed.
controlVersion
stringThe controls version. Signed.
reportSha256
stringThe report's integrity.reportSha256. Signed.
pdfSha256
string or nullSHA-256 of the stored PDF. Signed.
issuedAt
string (date-time)The receipt's time, equal to completedAt.
algorithm
string
one of "Ed25519"
The signature algorithm.
alg
string
one of "Ed25519"
The same value as algorithm.
keyId
stringIdentifies the signing key: ed25519: and 16 hex characters derived from the public key.
Example "ed25519:88f16fa019c4132c"
signature
stringThe Ed25519 signature, base64url without padding.
publicKeyPem
stringThe public key to verify signature with, PEM-encoded.
signedFields
array of stringThe fields the signature covers, sorted.
canonicalization
stringHow the signed bytes are built from signedFields, in one sentence.
Errors
StatusCodeWhen
404not_foundUnknown order, or an order that has not completed.
503receipts_unavailableReceipt signing is unavailable. Retry.

Verify a PDF

Anyone holding the PDF — the end user, the consumer, an auditor — can open https://offendersearch.app/verify/{orderId} (the QR code on the PDF goes there), choose the file, and check it. The browser computes the file’s SHA-256 locally and compares it with the signed pdfSha256, and checks the signature with the published key. The file is never uploaded, and the page shows only the receipt.

Offline

  • Hash the file: shasum -a 256 report.pdf and compare with pdfSha256.
  • Rebuild the signed payload: the signedFields and their values as compact JSON with the keys sorted, no spaces.
  • Verify with OpenSSL 3: save publicKeyPem as key.pem, base64url-decode signature into sig.bin, then openssl pkeyutl -verify -pubin -inkey key.pem -rawin -in payload.json -sigfile sig.bin.

Product overview