Verification reports
A timestamped PDF of a search you already ran, with a source citation on every record.
Livehttps://api.offendersearch.appSandboxhttps://sandbox.offendersearch.appA defensible artifact for your audit file
A verification report is a branded, timestamped PDF rendered from a search you already ran — the same name and identifiers are re-read against the stored data at render time, so the report carries its own timestamp, and parameters that do not apply to a document (radius, free text, match tuning, live, clearances) are not carried — showing every matching offender and every field of the standard record, with each record’s photo where the registry publishes one and a source citation on every record. It is your report of public-record data, clearly labeled as OffenderSearch output; it does not reproduce, mirror, or impersonate any government website. It is a separate, callable endpoint any valid key can use — there is no per-key entitlement — billed at $0.02 per document.
Request one with POST /v1/report by passing the searchId of a prior /v1/search or /v1/searches call on your account — up to 7 days afterward — plus, optionally, the viewerName and viewerEmail of whoever is viewing it, printed at the top of the report as a record of the viewer. Because the search call was already billed, the report meters only the +$0.02 PDF. The response is a single consolidated PDF for the whole search, with a source attribution section and the report id in the X-Report-Id header.
{
"searchId": "srch_9f2c1a7b3e4d",
"viewerName": "Jane Doe, ACME HR",
"viewerEmail": "jane@acme.example",
"purpose": "Volunteer background screening",
"reference": "req-4821"
}- The search criteria, and when the report was generated.
- Every matching record with every field of the standard record (not the extended
stateDatablock), its photo where one is published, and the labelledmatchState. - A source-attribution section citing the publishing jurisdiction for each record.
- The viewer identity and stated purpose, where you supplied them.
- The report id, printed on the document and returned in a header.
- A legal disclaimer.
searchId and runs them against the data at that moment, so the document reflects that moment rather than replaying the original response; filters beyond those (county, radius, address, free text, prefix or match settings) are not carried over. To keep the exact records a search returned, read them back with GET /v1/searches/{searchId}/results, and read counts and sourceStatus on the search before you file the PDF.Verification report
A branded, timestamped PDF report of a search you already ran, with a source citation on every record — a defensible artifact for your audit file. One consolidated document per search: your report of public-record data, clearly labeled as OffenderSearch output; it does not reproduce, mirror, or impersonate any government website.
Pass the searchId of a search you already ran — up to 7 days afterward — and you get back one consolidated PDF, never a separate document per source. The report runs that search’s name, date of birth, age, city, state, ZIP and jurisdiction criteria again when you request it (an async search records only its name, date of birth, state and jurisdictions), so it reflects the data at that moment. Other filters on the original search — county, radius, address, free text, prefix or match settings — are not carried into the report, and a search whose only criteria were among them (a radius on its own, say) returns 422. A one-shot mode is also supported: send an inline query instead of a searchId and the endpoint runs the search itself, which meters a search call as well as the PDF.
The report captures who viewed it (the optional viewerName / requesterName) and when, the search criteria, each matching offender, and a source-attribution section that cites the source of the data — plus a legal disclaimer. It is available to every account and billed at $0.02 per document; because the underlying search was already billed, the searchId path meters only the PDF. Omit the call and there is no extra charge.
The response is application/pdf, delivered as a file attachment. The generated report id is returned in the X-Report-Id header and printed on the document.
- One consolidated document. A single PDF for the whole search — not one document per source.
- Full source attribution. Cites the source of every record, with a citation on each.
- Every standard field. Each matching record with every field of the standard record and its photo where the registry publishes one. The extended stateData block is not included.
- Names the viewer. viewerName / requesterName, plus optional viewerEmail, purpose and reference, are printed on the report for your audit file. All are optional — the viewer identity is a record, not an access gate.
- Audit-ready & clearly labeled. Clearly labeled as OffenderSearch output and carries a legal disclaimer; it does not reproduce or impersonate any government site.
curl -X POST https://api.offendersearch.app/v1/report \
-H "X-API-Key: $OFFENDERSEARCH_KEY" \
-H "Content-Type: application/json" \
-o report.pdf -D - \
-d '{
"searchId": "srch_9f2c1a7b3e4d",
"viewerName": "Jane Doe, ACME HR",
"purpose": "Volunteer background screening"
}'
# -o writes the PDF to report.pdf; -D - prints the response headers,
# including X-Report-Id, to stdout.HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Disposition: attachment; filename="offendersearch-verification-rpt_9f2c1a7b.pdf"
X-Report-Id: rpt_9f2c1a7b
%PDF-1.7 …(binary PDF body: cover, search criteria, matching
records, a source-attribution section, and
the legal disclaimer)…Returns application/pdf as a file attachment; the report id is in the X-Report-Id header. 400 when neither a searchId nor a query was supplied; 401 for a missing or invalid key or session; 404 when the searchId is unknown on this account; 410 when the search is older than the 7-day report window; 422 when the query is invalid (e.g. faceId).
Verification report API request and response fields
One consolidated PDF for a search you already ran, with a source citation on every record. The search's recorded criteria are run again when you request it.
Request
| Field | Type | Description |
|---|---|---|
| searchId optional | string or null | The searchId of a POST /v1/search or POST /v1/searches call on this account, up to 7 days old. The report runs that search's recorded name, date of birth, age, city, state, ZIP and jurisdiction criteria again, and only the PDF is billed.Example "srch_9f2c1a7b3e4d" |
| query optional | Query | One-shot mode: run this search now and report on it. Ignored when searchId is sent. See the Query object. |
| jurisdictions optional | array of string or null | One-shot mode only: registry codes to search. Ignored when searchId is sent. |
| locationScoped optional · default false | boolean | One-shot mode only: same meaning as on POST /v1/search. |
| viewerName optional | string or null | Who is viewing the report. Printed at the top of the PDF as a record; it does not control access. Example "Jane Doe, HR Compliance" |
| viewerEmail optional | string or null | The viewer's email. Printed on the PDF. Example "jane@acme.example" |
| requesterName optional | string or null | Alias of viewerName. |
| purpose optional | string or null | The stated purpose of the lookup. Printed on the PDF. Example "Volunteer background screening" |
| reference optional | string or null | Your own case or reference id. Printed on the PDF. Example "case-2026-0417" |
Response
The report PDF, sent as an attachment. The X-Report-Id response header carries the report id, which is also printed on the document.
| Status | Code | When |
|---|---|---|
| 400 | — | Neither searchId nor query was sent. |
| 401 | — | The X-API-Key header is missing or the key is not valid. |
| 402 | — | The account has no active subscription and no free-trial searches left. detail says which. |
| 404 | — | The searchId is not a search on this account. |
| 410 | — | The search is older than the 7-day report window. Run the search again. |
| 422 | — | A field is malformed, or the criteria the report can run narrow on nothing (a search whose only filter was a radius, for example). |
Proof documents API request and response fields
Render per-registry proof documents for a search you already ran. Needs billing on the account.
Request
| Field | Type | Description |
|---|---|---|
| searchId required | string | The searchId of a search on this account.Example "srch_9f2c1a7b" |
The body is the ProofRequest object. Asks for per-registry proof documents: the registries to render and the format. Billing must be enabled on the account. Each rendered document is billed as one PDF, at the same rate as a verification report.
Response
The documents rendered for the requested registries.
The body is the ProofBundle object. The proof documents rendered for a search. {"status": "none"} when no proof was requested.
| Status | Code | When |
|---|---|---|
| 401 | — | The X-API-Key header is missing or the key is not valid. |
| 402 | — | Billing is not enabled on the account. |
| 404 | — | No search with this id on this account (a search run by another account answers the same 404). The body is an Error. |
| 422 | — | registries is missing or empty, or the body carries an unknown field. |
The ProofRequest object — proof document request fields
Asks for per-registry proof documents: the registries to render and the format. Billing must be enabled on the account. Each rendered document is billed as one PDF, at the same rate as a verification report.
Returned or accepted by POST /v1/search, POST /v1/search, POST /v1/searches/{searchId}/proof.
| Field | Type | Description |
|---|---|---|
| registries required | array of string | Registry codes to render proof for, at least one (["IL", "IN"]). A registry with no proof template is skipped and noted. |
| format optional · default "pdf" | string one of "pdf", "html" | Document format: pdf or html. |
The ProofBundle object — proof document response fields
The proof documents rendered for a search. {"status": "none"} when no proof was requested.
Returned or accepted by POST /v1/search, GET /v1/searches/{searchId}, POST /v1/search, POST /v1/searches/{searchId}/proof.
| Field | Type | Description |
|---|---|---|
| status | string one of "none", "rendering", "ready" | ready: at least one document rendered. none: nothing was rendered. rendering is reserved and not returned today. |
| billedDocuments | integer | Documents rendered and billed on this request, one PDF each. A registry with no proof template is not counted and not billed. |
| documents | array of object | One entry per requested registry. |
| documents[].registry | string | The registry code. |
| documents[].format | string one of "pdf", "html" | pdf or html. |
| documents[].url | string | Where to fetch the document (GET /v1/proof-docs/{token}). |
| documents[].note | string | Why a document was not rendered, when it was not. |
Fetch a proof document
Download one rendered proof document by the token in its documents[].url.
Request
| Field | Type | Description |
|---|---|---|
| token required | string | The token from a ProofBundle document URL. |
Response
The document, in the format it was requested in.
| Status | Code | When |
|---|---|---|
| 401 | — | The X-API-Key header is missing or the key is not valid. |
| 402 | — | The account has no active subscription and no free-trial searches left. detail says which. |
| 404 | — | No document with this token. |