RegistryRadar
Get the app

API reference

The published contract for the metered developer API. Every path below sits under /v1/api, is GET, returns JSON, and requires an API key.

Base URL https://api.registryradar.app · Machine-readable at /api/openapi.json · Narrative documentation, examples and error handling on the documentation page.

Rendered from the running API. This page read the spec from https://api.registryradar.app/v1/api/openapi.json and is as current as the deployment serving it.

Authentication

Present the key in a header. Never in a query string — a request whose URL carries one is rejected with 400 even when the key is valid, because URLs reach access logs, browser history and referrer headers.

Authorization: Bearer rr_live_YOUR_KEY
# or
X-API-Key: rr_live_YOUR_KEY

POST/v1/developers/signup

Create a developer account

Responses

201
Default Response
400
Default Response
401
Default Response
409
Default Response

POST/v1/developers/signin

Sign in

Responses

200
Default Response
401
Default Response

GET/v1/developers/me

Current developer account and usage

Responses

200
Default Response
401
Default Response

GET/v1/developers/keys

List API keys (never returns secrets)

Responses

200
Default Response
401
Default Response

POST/v1/developers/keys

Create an API key — the secret is returned ONCE and never again

Responses

201
Default Response
401
Default Response
403
Default Response

DELETE/v1/developers/keys/{id}

Revoke an API key

Parameters

idpath · required

Responses

204
Default Response
404
Default Response

GET/v1/developers/usage

Usage for the current billing period

Responses

200
Default Response
401
Default Response

GET/v1/api/records/{id}

One record in full

Everything the source registry published for a single record: address, offences, demographics, aliases and the link back to the originating registry. Search returns a lean shape so a wide query stays small; this is where the rest lives. A record your purpose may not receive answers **403 `record_withheld`**, NOT 404. Those are different facts — 404 says the record does not exist, and reporting a record we are holding back as one that does not exist is the exact confusion between "no data" and "no risk" this API refuses to make anywhere else.

Parameters

idpath · required

Responses

200
Default Response
400
Default Response
401
Default Response
403
Default Response
404
Default Response
429
Default Response
500
Default Response

GET/v1/api/quota

What this key has left

The same numbers as the `X-Quota-*` response headers, as a body — because a client that wants to check before a batch should not have to make a billable call and read its headers to find out. `limit` and `remaining` are **null** on an unmetered key (every test key, and negotiated enterprise plans). Null is not zero: rendering it as zero would report an unlimited key as an exhausted one. This call is itself metered, so `remaining` already accounts for it.

Responses

200
Default Response
400
Default Response
401
Default Response
403
Default Response
429
Default Response
500
Default Response

GET/v1/api/status

Dataset sizes and data freshness

What we actually hold right now, so a buyer can verify the numbers on the pricing page rather than take them on trust — the counts here are computed from the loaded datasets, not written down. `liveRecords` and `lastSyncedAt` are **null**, not zero, when the record store cannot be reached. An integration that treats a degraded read as "0 records" would report an outage as an all-clear, which is the one failure this API exists to prevent. Reference datasets are compiled in and stay available either way. For liveness probes use the unauthenticated `GET /healthz` instead: it needs no key and costs no quota.

Responses

200
Default Response
400
Default Response
401
Default Response
403
Default Response
429
Default Response
500
Default Response

GET/v1/api/atlas

Registry law and coverage for every country

Our own research: 176 countries, each with its legal position, the operating body, and how an ordinary person checks. Not derived from any registry feed, so it carries no third-party use restriction.

Parameters

statusquery
limitquery
offsetquery

Responses

200
Default Response
400
Default Response
401
Default Response
403
Default Response
429
Default Response
500
Default Response

GET/v1/api/jurisdictions/us

How each of the 56 US registries works

All 50 states, DC and the five territories. `addressPrecision` records what the public site PUBLISHES, not what the state knows — several publish only a ZIP or a block, and Oregon publishes about 6% of its registrants at all. Null means we could not establish it, never that the state publishes nothing.

Parameters

limitquery
offsetquery

Responses

200
Default Response
400
Default Response
401
Default Response
403
Default Response
429
Default Response
500
Default Response

GET/v1/api/jurisdictions/tribal

Tribal registries

About 152 federally recognised tribes elected to be SORNA registration jurisdictions in their own right. 123 publish their own search, and for those the surrounding state registry does NOT hold their records — so a state-only integration silently misses that land.

Parameters

limitquery
offsetquery

Responses

200
Default Response
400
Default Response
401
Default Response
403
Default Response
429
Default Response
500
Default Response

GET/v1/api/policy

What your key may be used for, by jurisdiction

The permitted-use position for every jurisdiction we serve, and what your own key's declared purpose can receive. Published because no competitor tells you this and because getting it wrong is your liability as well as ours.

Responses

200
Default Response
400
Default Response
401
Default Response
403
Default Response
429
Default Response
500
Default Response

GET/v1/api/safeguarding

What a parent or employer can actually do, per country

For the 120 countries with no public registry, this is the practical answer: the vetting certificate or barred list that does exist, and crucially WHO may request it. That last field is the one most often got wrong — in Croatia the individual legally cannot request their own, in Canada the hiring organisation must initiate it. `independentlyVerified` says whether a second agent re-read the primary document; treat false as unaudited rather than wrong.

Parameters

kindquery
limitquery
offsetquery

Responses

200
Default Response
400
Default Response
401
Default Response
403
Default Response
429
Default Response
500
Default Response

GET/v1/api/safeguarding/{country}

One country's safeguarding check in full

Parameters

countrypath · required

Responses

200
Default Response
400
Default Response
401
Default Response
403
Default Response
404
Default Response
429
Default Response
500
Default Response

GET/v1/api/jurisdictions/us/{code}

One US jurisdiction in full

Parameters

codepath · required

Responses

200
Default Response
400
Default Response
401
Default Response
403
Default Response
404
Default Response
429
Default Response
500
Default Response

GET/v1/api/openapi.json

OpenAPI 3.1 document for this API

The machine-readable contract for `/v1/api/*` and `/v1/developers/*`. No API key required — you need this before you have one. Feed it to Postman, `openapi-generator`, or your own tooling.

Responses

200
Default Response

Before you build on a response

Two fields on the record search determine whether what you build tells your users the truth. covered says whether we mirror any registry covering that point — false with an empty list means we cannot see there, not that nobody is there. withheldsays how many records we hold for that area but did not serve for your key's declared purpose, because several jurisdictions restrict by statute what their records may be used for. Neither an empty list nor a filtered one is an all-clear.

The per-jurisdiction position is published at GET /v1/api/policy and summarised on the datasets page.