Sex Offender Search API · v1.0.0

Verification reports

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

Livehttps://api.offendersearch.appSandboxhttps://sandbox.offendersearch.app

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

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, and when the report was generated.
  • Every matching record with every field of the standard record (not the extended stateData block), its photo where one is published, 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 runs the search again when you request it. It takes the name, date of birth, age, city, state, ZIP and jurisdiction criteria recorded with the 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.
POST/v1/reportAuth: X-API-Key

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.

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

POST/v1/reportAuth: X-API-Key or session

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

Body · application/json
FieldTypeDescription
searchId
optional
string or nullThe 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
QueryOne-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 nullOne-shot mode only: registry codes to search. Ignored when searchId is sent.
locationScoped
optional · default false
booleanOne-shot mode only: same meaning as on POST /v1/search.
viewerName
optional
string or nullWho 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 nullThe viewer's email. Printed on the PDF.
Example "jane@acme.example"
requesterName
optional
string or nullAlias of viewerName.
purpose
optional
string or nullThe stated purpose of the lookup. Printed on the PDF.
Example "Volunteer background screening"
reference
optional
string or nullYour own case or reference id. Printed on the PDF.
Example "case-2026-0417"

Response

200 · application/pdf

The report PDF, sent as an attachment. The X-Report-Id response header carries the report id, which is also printed on the document.

Errors
StatusCodeWhen
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

POST/v1/searches/{searchId}/proofAuth: X-API-Key (billing enabled)

Render per-registry proof documents for a search you already ran. Needs billing on the account.

Request

Path parameters
FieldTypeDescription
searchId
required
stringThe searchId of a search on this account.
Example "srch_9f2c1a7b"
Body · application/json

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

200 · application/json

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.

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

FieldTypeDescription
registries
required
array of stringRegistry 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.

FieldTypeDescription
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
integerDocuments rendered and billed on this request, one PDF each. A registry with no proof template is not counted and not billed.
documents
array of objectOne entry per requested registry.
documents[].registry
stringThe registry code.
documents[].format
string
one of "pdf", "html"
pdf or html.
documents[].url
stringWhere to fetch the document (GET /v1/proof-docs/{token}).
documents[].note
stringWhy a document was not rendered, when it was not.

Fetch a proof document

GET/v1/proof-docs/{token}Auth: X-API-Key

Download one rendered proof document by the token in its documents[].url.

Request

Path parameters
FieldTypeDescription
token
required
stringThe token from a ProofBundle document URL.

Response

200 · application/pdf or text/html

The document, in the format it was requested in.

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

Product overview