Audit Report API Documentation

How the Verification Report API works

The Audit Report API records what our data and live checks found when you ran it. Every request gets a new report ID. The API returns immediately; your application polls for completion, then retrieves the structured report or branded PDF. The PDF includes a Report ID and a link to check the exact issued file.

A report is evidence for review. It is not an identity adjudication, background-check decision, or determination of eligibility. Historical database records remain visible even when no current official source confirms registration.

Base URL: https://api.offenders.io. Authenticate private endpoints with X-API-Key or Authorization: Bearer. Keep API keys on your server. The public receipt grants no access to the private report.

Create a report

Send JSON with either a record uuid returned by Search, or firstName and lastName with optional dob, state, city, zipcode, and address. Do not mix UUID and name fields. The broad query checks indexed candidates and fresh registry sources; the UUID request checks that one indexed record against live sources where supported.

Broad search

Exact record UUID

A successful create returns 202 Accepted. It does not wait for the report or include the final evidence.

Poll status and list reports

Poll resource_uri with the same account's API key. A queued or running report returns 200 with report_id, status, created_at, and resource_uri. A completed report also returns completed_at, the complete snapshot, signed_manifest, SHA-256 hashes, and pdf_uri. The completed JSON may be large. Read it as the full result; there is no candidate pagination within one report.

GET /sexoffender/report/live?limit=10 lists only your account's report metadata. The optional limit is 1–20 (default 10). When next_cursor is present, send it as cursor for the next page. List rows contain status, timestamps, resource URI, and a PDF URI when complete; open one report to read its evidence.

Polling is the complete default integration. A configured webhook may notify you of completion, but the authenticated GET remains authoritative. A webhook event contains no report body.

Download the PDF

After the report is completed, call pdf_uri with your API key. Success is 200 with Content-Type: application/pdf. Save the returned bytes as provided so the file hash remains verifiable. Before completion the endpoint returns 409; poll the JSON resource and try again.

There is no public or permanent PDF download URL. The QR code on a report opens the public verification page; it does not expose the PDF.

Understand the evidence

The snapshot contains the submitted query, generated time, source coverage, and all returned candidates. Each candidate contains public record fields, candidate_origin, and separate sources.nsopw and sources.state execution states. attempted_verified indicates a live observation by that source; attempted_not_found, attempted_unavailable, not_attempted_budget, and not_attempted_unsupported describe other outcomes. An indexed record alone does not establish current registration.

The report preserves matching historical evidence, including records no longer observed by a live source. State checks have a server-managed safety budget; any candidates not checked because of that budget are marked not_attempted_budget. If the indexed search is too broad to generate a complete report, the report fails with indexed_scope_too_large rather than silently truncating candidates. Narrow the query and create a new report.

Public PDF verification

The public receipt endpoint returns only receipt, signature, and public_key_pem. The receipt includes Report ID, issuance time, PDF SHA-256, signing key ID, and algorithm. It does not return names, searches, accounts, candidates, or PDF bytes. Only completed reports have public receipts. The Report ID is a locator, not proof that a particular PDF is genuine.

To verify a file, open Verification Report verification. Your browser extracts the Report ID and computes the selected PDF's SHA-256 locally, then checks the signed receipt; it does not upload the PDF. A green Verified result requires the entire file hash to match. A QR scan without the file confirms only that Offenders.io issued the Report ID.

Errors, privacy, and usage

HTTP errors use {"code": number, "message": string, "action": string}, except the intentionally opaque 404 for an unknown or other-account report. Missing authentication returns 401; invalid or unsupported create inputs return 400; ineligible testing or internal credentials and durable-retention restrictions return 403; rate limits return 429; a temporary service or artifact problem returns 503 with retry guidance. A completed report cannot be modified; rerun the request to obtain a new Report ID.

A failed job remains a 200 status resource with status: "failed", failure_code, message, and action. Narrow a search for indexed_scope_too_large, check the UUID for uuid_not_found, and follow the returned action for other failures. Do not interpret a failed job as a clean registry result.