Verification Report API Documentation

How the Verification Report API works

Create a report to save the matches, source checks, and results from a search. A report can also show that the search found no matches. Each request gets a new Report ID. The API returns immediately; check its status, then open the JSON report or PDF.

The PDF includes the Report ID and a link where someone can check whether their PDF matches the file Offenders.io issued.

Base URL: https://api.offenders.io. Send your API key in X-API-Key or Authorization: Bearer for private endpoints. The public verification receipt does not include the report or PDF.

Recommended screening workflow

1. Search first. Use Extensive Search to screen the person and review returned candidates.
2. Resolve the screening result. No confirmed match: use the same supported identity criteria for the report, such as name, DOB, and state. Confirmed match: use that record's UUID to target the specific person you identified.
3. Preserve the evidence. The Verification Report performs live source checks and preserves the result, source status, timestamps, and available official-source evidence in a signed PDF.

Verification Reports document a screening decision; they do not replace candidate review and identity resolution.

Create a report

Send JSON with either a Search record uuid, or firstName and lastName. Name searches can also include dob, state, city, zipcode, or address. Do not mix a UUID with name fields.

You can add notes in request_metadata: purpose (up to 500 characters), reference (255), and requested_by (255). These are details you supply; Offenders.io does not verify them. They stay in the private report. Set include_in_pdf to true to also show them in an Internal reference section on page one. It defaults to false.

No-match report — use the search criteria

When your screening search returns no confirmed match, generate the report using the same supported identity criteria used for that screening.

Confirmed-match report — use the record UUID

When you have reviewed the search results and confirmed a specific match, use that record's UUID rather than running another broad name report.

The API returns 202 Accepted with a Report ID. The report continues generating in the background.

Poll status and list reports

Use resource_uri to check whether the report is queued, running, completed, or failed. When complete, the same URL returns the full snapshot, signed_manifest, file hashes, pdf_uri, and any request_metadata you supplied.

GET /sexoffender/report/live?limit=10 lists your reports, newest first. Set limit from 1 to 20; the default is 10. If the response has next_cursor, pass it as cursor to get the next page. The list shows status and dates; open a report for its full results.

Polling is enough to integrate. You can also configure a webhook to notify your app when a report completes; it does not include the report contents.

Download the PDF

When the report is complete, open pdf_uri with your API key. It returns application/pdf for browser viewing or download. Save the file without changing it if you want others to verify its hash. If the PDF is not ready, the endpoint returns 409.

The PDF URL requires your API key. The QR code opens a public verification page, not the PDF.

Understand the evidence

sources.nsopw and sources.state tell you what happened during the live checks. attempted_verified means that source found the record. attempted_not_found means the check ran but did not find it. attempted_unavailable means the source could not be checked.

not_attempted_budget means the live source check was not attempted for that candidate because the report exceeded the supported verification scope. Earlier saved records may still appear even when a live check does not find them. If a search is too broad to list all indexed results, the report fails with indexed_scope_too_large; narrow the search and create another report.

field_provenance shows whether a field came from a saved record, NSOPW, or a state registry. Use sources to see what the current live checks found; a field's origin alone does not mean it was checked live.

Public PDF verification

The public endpoint returns a signed receipt with the Report ID, issue time, and PDF hash. It does not return the report, customer details, or PDF file. Only completed reports have a receipt.

To check a PDF, open the PDF verification tool and choose the file. The browser checks the file against the signed receipt without uploading it. Scanning the QR code confirms the Report ID was issued; checking the file confirms whether that PDF matches it.

Retention

Verification Reports and their associated evidence are retained for seven years by default.

Errors

Errors include a code and message; many also include a suggested action.

Common HTTP status codes

• 400 Bad Request — Invalid or conflicting input.
• 401 Unauthorized — Missing or invalid API key.
• 403 Forbidden — The API key is not eligible to use Verification Reports.
• 404 Not Found — The report does not exist or belongs to another account.
• 405 Method Not Allowed — The endpoint does not support the requested HTTP method.
• 409 Conflict — The PDF is not ready yet.
• 429 Too Many Requests — Rate limit exceeded.
• 500 Internal Server Error — An unexpected error occurred.
• 503 Service Unavailable — The service is temporarily unavailable.

A failed report remains available through its status endpoint and includes a failure_code and suggested action.

Common report failure codes

• indexed_scope_too_large — Narrow the search and create a new report.
• uuid_not_found — Check the UUID and try again.

Access and privacy

Creating, listing, retrieving, and downloading Verification Reports requires an eligible production API key. Testing keys cannot create or retrieve reports.

Public verification exposes only the signed verification receipt. It does not expose the report contents, customer details, or PDF.

For HIPAA/PHI workflows, follow the separately enabled HIPAA workflow for your account.

Billing