Requests & responses

Versioning, pagination, timeouts, identifiers and billing lines — the same on every product.

View as MarkdownWhole product as one Markdown fileOpenAPI

Base path and versions

Every endpoint lives under /v1. Changes are additive: new fields and new enum values appear, nothing is renamed or removed. Ignore fields you do not know and treat unknown enum values as "other". A breaking change would ship under a new base path and be announced on the changelog first.

Pagination

Product	How	Notes
Sex Offender search	Optional `query.page` / `query.perPage`	Send neither and the whole de-duplicated result comes back in one response (capped at 4,000 records, said in `capped`). A search that names nobody (radius, free text) is always paginated. Details.
Criminal search	Top-level `page` (≥1) / `perPage` (1–200, default 50)	Offset pagination over the ranked set; `totalPages` on every response. Details.
Monitors, alerts, FCRA lists	Per endpoint	See each product's reference.

Timeouts and deadlines

Set your HTTP client timeout to at least 60 seconds for a synchronous search with live re-checks; cached searches usually answer in well under a second.
The Sex Offender search accepts deadlineMs and onDeadline to bound how long it waits for slow jurisdictions, and reports elapsedMs on every response. Details.
Anything long-running — a live check of many sources, evidence documents, a criminal job — answers with an id to poll (a 202, or for a Sex Offender live search that went async a 200 whose status is pending). See Async jobs & webhooks.

Identifiers

Identifier	Shape	Use
`searchId`	`srch_` + hex (sex offender), `crs_` + hex (criminal), `evs_` + hex (live evidence)	Poll an async job, render a report, find it in history. Persist it the moment you receive it.
`recordId` / `externalId`	Per product	Fetch one record again: `GET /v1/records/{recordId}`; `GET /v1/criminal/records/{recordId}?source=` where the path value is the criminal record's `externalId` (a criminal record has no `recordId` field).
`personRef`	Opaque	Stable handle for a person across searches; what a clearance names.
`monitorId`, `alertId`, `orderId`, …	Per product	See each reference.

Billing lines on the response

Responses that charge more than the base call carry meterEvents[]: one entry per meter, with kind (for example criminal_call, live_source, pdf) and quantity. A criminal search always carries them; a Sex Offender search carries them only when a live block ran (a Regular search is one call, counted in Dashboard → Usage and not echoed on the response). Log what you receive and reconcile the rest from the dashboard.