Machine-readable public contract.Integration PDF
Printable Search and History guide.Offender History Overview
See capabilities, use cases, and PDF workflows.
Endpoints
Choose the response format your workflow needs. Both endpoints are available to all API accounts and use your existing API key.
| Endpoint | Methods | Successful response | Use it for |
|---|---|---|---|
/sexoffender/history | GET / POST | application/json | Display available history in your application, one page at a time. |
/sexoffender/report/history | GET / POST | application/pdf | Download a formatted report to print or keep with your review. |
Base URL: https://api.offenders.io. Authenticate with X-API-Key or Authorization: Bearer. Send the record uuid returned by Search.
Use GET or POST. History is available to all API accounts. Use your existing API key; normal account and usage rules apply.
From Search to History
- Find a candidate with your enabled Offenders.io search tools.
- Pass the returned record
uuidto either History endpoint. - Use JSON for an interactive history view, or request a PDF for a printable report.
In the Dashboard, open a result and select View History. Select View Details on a history entry to inspect that record. Sign in with your existing API account.
JSON History Request
Send a record uuid. You may also send page; if omitted, it defaults to 1.
GET
X-API-Key: {YOUR_API_KEY}
POST
Content-Type: application/json
X-API-Key: {YOUR_API_KEY}
{
"uuid": "5893a310-37ce-58d8-b101-39e76a60e94a",
"page": 1
}
uuid: The record UUID returned by a regular Search API request. Use it to open History from that record.page: Which page to return. It must be 1 or higher. Each page contains up to 50 records.
JSON History Response
The response contains offenders, page, and totalPages. Each page contains up to 50 records, shown from newest to oldest. If no history is available, this endpoint returns 200 with an empty offenders list.
"offenders": [ ... ],
"page": 1,
"totalPages": 1
}
Each result uses the same fields as a Search API result. In History, uuid identifies a record and createdAt is a saved-record observation date, not a move date or registration date. When available, locationHistory lists addresses previously recorded for that result.
Download a PDF Report
Use GET or POST and send a record uuid. A successful request downloads an application/pdf file containing the available History timeline for that record, rather than one API page.
Reports support up to 500 displayed entries and 200 PDF pages. The API returns a structured 422 error if the complete report exceeds its synchronous generation limits; it never returns a truncated report. Do not send page, perPage, filters, or formatting options.
Each PDF page includes the lookup identifier, retrieval time, total entry count, and physical page number. Registry links use the official record URL. Missing photos use a placeholder; saved observation dates do not establish move dates.
GET
X-API-Key: {YOUR_API_KEY}
Accept: application/pdf
POST
Content-Type: application/json
Accept: application/pdf
X-API-Key: {YOUR_API_KEY}
{
"uuid": "5893a310-37ce-58d8-b101-39e76a60e94a"
}
Success returns the PDF directly with Content-Type: application/pdf and a download filename. Validation, access, not-found, and generation failures remain JSON using the existing {"code": number, "message": string} error shape. Normal account authentication and usage rules apply.
Content-Type: application/json
{"code":404,"message":"No history found for this ID"}
Check the HTTP status and Content-Type before saving the response as a PDF. A valid identifier with no available History returns 404; invalid input returns 400. Requests beyond the supported report limits return 422, and rate-limited requests return 429. A temporary lookup failure returns 502; temporary service unavailability returns 503; a generation timeout returns 504. Other generation failures return 500. All use the same JSON error shape. The OpenAPI specification lists all response codes.
One successful live report is billed as one base API call. Synthetic reports produced with a Testing API key use fake History data and add no billed API usage.
Location History (locationHistory)
locationHistory lists addresses previously recorded for a result, when available.
| Field | Type | Description |
|---|---|---|
address | string | Street address. |
addressFull | string | Full formatted address, when available. |
city | string | City. |
state | string | State code. |
zipcode | string | ZIP code. |
lat / lng | number | Coordinates, when available. |
observedAt | ISO date | When this address was recorded in Offenders.io. |
basis | string | Address reference category. See the values below. |
basis values
source: The address came from a public registry record.vendor: An address reference.legacy: An earlier saved address record.synthetic: Fake address data returned by a testing API key.
Testing API Keys
Testing API keys can use the synthetic record uuid returned by a synthetic Search response. They return the same fake records each time and never query live registry data.
Account & Usage
Use an active API account and your existing API key. History does not require a separate approval. Normal usage charges and limits apply.
Offenders.io links public registry records that may belong to the same person. A link does not confirm identity, and public registry data may be incomplete or incorrect. Verify identity and important details with the official registry before relying on these results.