Live evidence — the registry’s page as a PDF

Who live evidence is for

Some files have to hold what the registry itself showed, not only a record of it. A skilled nursing admission that must survive a survey, a visitor-management log with an audit obligation, a home care or staffing agency that keeps what the registry displayed on the day of the check, a legal or licensing file — in each of those the question later is “what did the registry’s page say when you looked?”, and a database row does not answer it.

Live evidence answers it. It is a separate service on its own base URL, https://evidence.offendersearch.app, used with the same API key and X-API-Key header as the main API. Send it the same request body you send POST /v1/search: it runs the live check for the registries you name, and in addition opens each registry’s own public website in a real browser, runs the search there, and prints every result page and each matching registrant’s detail page to one PDF per registry, behind a cover page that states the query, the registry, the capture time, the URLs captured and a content hash. Most callers do not need it; the main API is unchanged. This is the path for compliance-heavy flows where a record of the registry’s own page is required.

Records or documents — a live check and a live evidence search

A live check on the main API re-verifies a registry and gives you back records: normalized, de-duplicated, scored, each with a personRef. A live evidence search gives you the same records and documents: the registry’s own pages, printed as shown. You name the registries the same way in both — live.jurisdictions — and the records arrive exactly as the main API returns them, because they come from the normal live check; the documents are added beside them.

Clearances apply to the records as usual. A cleared person’s page is still printed: the page is the registry’s statement, and the clearance is your decision about it, so the document stays faithful to what the registry showed.

The flow: request, poll, download

Post the body you would send POST /v1/search to POST /v1/evidence/searches on the evidence host. The registries named in live.jurisdictions are the ones that get a printed document — up to 20 per request.

curl https://evidence.offendersearch.app/v1/evidence/searches \
  -H "X-API-Key: $OS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": { "firstName": "Jordan", "lastName": "Rivera", "dob": "1988-04-12" },
    "live": { "jurisdictions": ["CA", "NV"] }
  }'

A live evidence search always runs asynchronously, even for one registry: the answer is a 202 with a job handle, never an inline result.

HTTP/1.1 202 Accepted

{
  "searchId": "srch_7d41e2",
  "status": "pending",
  "mode": "async",
  "pollUrl": "/v1/evidence/searches/srch_7d41e2"
}

Poll GET /v1/evidence/searches/{searchId} on the evidence host until status leaves pending and running — the same handshake as an async search on the main API. The finished result is the full search response exactly as POST /v1/search returns it, with one addition: evidence[], one entry per registry you named.

{
  "searchId": "srch_7d41e2",
  "status": "complete",
  "counts": { "records": 1, "recordsReturned": 1, "sourcesQueried": 2,
              "sourcesComplete": 2, "sourcesIncomplete": 0 },
  "sourceStatus": [ /* one entry per registry, as on every search */ ],
  "records": [ /* one Record per matched registrant, with personRef, as on every search */ ],
  "evidence": [
    {
      "jurisdiction": "CA",
      "status": "complete",
      "kind": "text",
      "pages": 3,
      "resultPages": 2,
      "detailPages": 1,
      "capturedAt": "2026-10-18T14:02:11+00:00",
      "sourceUrl": "https://…",
      "pageUrls": ["https://…", "https://…", "https://…"],
      "sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
      "bytes": 412330,
      "downloadUrl": "/v1/evidence/searches/srch_7d41e2/CA.pdf",
      "billed": true,
      "chargeUsd": 0.25,
      "pdfBase64": "JVBERi0x…",
      "inline": true
    },
    {
      "jurisdiction": "NV",
      "status": "incomplete",
      "incompleteReason": "no_recipe",
      "detail": "This registry cannot be printed yet.",
      "billed": false
    }
  ],
  "usage": {
    "liveChecks": 2, "liveChargeUsd": 0.04,
    "liveEvidence": 1, "liveEvidenceUsd": 0.25,
    "capped": false, "display": "2 live checks · 1 document · $0.29"
  }
}

• A complete entry carries the capture: kind, pages split into resultPages and detailPages, capturedAt in UTC, sourceUrl and every pageUrls entry, the sha256 of the PDF, its bytes, the downloadUrl, and the charge.
• The PDF itself is in pdfBase64 when the document is 4 MB or smaller (inline: true). Above that, pdfBase64 is null, inline is false, and the download link is the way to get it.
• An incomplete entry carries incompleteReason from a closed list — no_recipe, renderer_unavailable, source_unreachable, blocked, timed_out, no_results_page, render_failed or query_unsupported — a free-text detail, and billed: false. Branch on the reason, never on detail.

Download any completed document with the API key or a dashboard session. The search must belong to your account; any other search id answers 404. Documents are kept for 30 days.

curl https://evidence.offendersearch.app/v1/evidence/searches/srch_7d41e2/CA.pdf \
  -H "X-API-Key: $OS_API_KEY" \
  -o jordan-rivera-CA.pdf

What a document contains

Every PDF has the same two parts, in this order:

• Our cover page. The query as sent, the registry printed, the capture time in UTC, the URL of every page captured, the page count, and the SHA-256 of the document that follows — so a reviewer can tell, years later, that the file is intact and which registry and moment it describes.
• The registry’s pages, as shown. Every result page the search produced on the registry’s website, then the detail page of each registrant that matched the query. Nothing is re-typed or re-formatted; the page is what the registry displayed at that moment.

kind tells you how the registry pages were produced. text means they were printed from the page and the PDF is searchable. image means each page is a full-page capture rendered as an image — some registries only work this way, and the result is a faithful picture rather than selectable text. mixed means a document holds both.

Price, and what is never billed

• The search is billed exactly like a live search on the main API. The call at the base per-call rate, plus $0.02 per live source that completes, to the usual $2.00 ceiling.
• Plus $0.25 per registry document that completes. The evidence charge for one search never exceeds $5.00 — a price ceiling, not a document limit.
• Incomplete documents bill nothing. Whatever the reason, an incomplete entry reports billed: false; a registry that cannot be printed yet is never billed as a document.
• Read it off the response. usage.liveEvidence is the count of billed documents and usage.liveEvidenceUsd the charge, beside the usual liveChecks and liveChargeUsd; each entry in evidence[] carries its own billed and chargeUsd.

Limits

Endpoints

All three live on https://evidence.offendersearch.app, not on the main API’s base URL. The main API’s endpoints are unchanged.

The EvidenceDocument object — one registry's printed page

One registry's live evidence document: the registry's own public website, printed as shown to a PDF behind a cover page. One entry per registry named in live.jurisdictions, in evidence[]. A complete document carries the capture and download fields; an incomplete one carries incompleteReason and detail and is never billed.

Returned or accepted by GET /v1/evidence/searches/{searchId}.

The EvidenceLiveUsage object — live evidence charge fields

The usage block of a live evidence search: every LiveUsage field — the live check is billed exactly as on the main API — plus the evidence documents.

Every field of the LiveUsage object, plus: