Platform
The conventions every product shares, written once. Product pages document only their exceptions.
One platform, several APIs
Every product — Sex Offender Search, Criminal Records, Monitoring, the Map API and the FCRA Partner API — is served from the same host with the same key, the same authentication header, the same error body and the same sandbox. Learn these once.
| Convention | Value |
|---|---|
| Live base URL | https://api.offendersearch.app |
| Sandbox base URL | https://sandbox.offendersearch.app — test keys only, never billed |
| Base path | /v1 on every endpoint |
| Authentication | X-API-Key: <key> request header |
| Key prefixes | os_live_… for production, os_test_… for the sandbox |
| Content type | JSON request bodies and responses; PDFs for reports and evidence |
| Errors | HTTP status + a JSON body with detail (string, list or object — see errors) |
In this section
- Getting started in five minutes — account, key, first request, first response
- Authentication & keys — the header, key lifecycle, rotation, organisation credentials, secure handling
- Sandbox & production — the two hosts, test keys, fixed test names, going live
- Requests & responses — versions, pagination, timeouts, deadlines, request identifiers, billing events
- Errors, rate limits & retries — the error body, 429 and Retry-After, what to retry and what never to
- Async jobs & webhooks — 202 + poll, webhookUrl, signing, idempotency
- Data model rules — normalized vs original values, provenance, completeness, missing vs null vs empty, dates
- Operations — usage, billing, production checklist, health, troubleshooting, support