Verification reports

A timestamped PDF of a search you already ran, with a source citation on every record.

Base URL https://api.offendersearch.appThis page as Markdown/docs/reports.md

A defensible artifact for your audit file

A verification report is a branded, timestamped PDF of a search you already ran — showing every matching offender and every field on file (photos included), with 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 call — 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.

Request

POST /v1/report

{
  "searchId": "srch_9f2c1a7b3e4d",
  "viewerName": "Jane Doe, ACME HR",
  "viewerEmail": "jane@acme.example",
  "purpose": "Volunteer background screening",
  "reference": "req-4821"
}

What the document contains

The search criteria, verbatim, and when the search ran.
Every matching record with every field on file, including photos and the labelled matchState.
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.

The report is a snapshot of one search, not a live query. It renders the result set of the searchId you name, so the completeness the search reported is the completeness the document reflects — read counts and sourceStatus on the search before you file the PDF.

POST/v1/reportAuth: X-API-Key

Verification report

A branded, timestamped PDF report of your FULL search results 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 covering that entire result set, never a separate document per source. 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.

What you can do

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.
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.

Body

Send a searchId (the normal path), or — in the legacy one-shot mode — every field POST /v1/search accepts (query, jurisdictions, freshness, locationScoped, …). Supply one or the other; neither is a 422.

Field	Type	Description
searchId optional	string	The id returned by a prior POST /v1/search or /v1/searches call, up to 7 days old. This is the normal path and it bills only the PDF. A searchId that is unknown, older than 7 days, or belongs to another account is a 404/422.
viewerName optional	string	Optional. Who is viewing the report; printed at the top of the PDF. requesterName is accepted as an alias.
viewerEmail optional	string	Optional email of the viewer. Printed on the PDF.
purpose optional	string	Optional stated purpose for the lookup. Printed on the PDF.
reference optional	string	Optional caller reference / case id. Printed on the PDF.

Request

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.

Response

200 OK

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. 401 for a missing/invalid key or session; 404 when the searchId is unknown on this account; 422 when neither a searchId nor a query was supplied, when the search is older than the 7-day retention window, or when the query is invalid (e.g. faceId).