Sex Offender Search API

Introduction

The Offendersearch API is a REST API for national sex-offender screening. It aggregates official state, territory, and national sources behind one endpoint, offers full offenders.io field parity, and adds scored matches, per-source provenance, freshness tiers, and per-registry verification reports. Every request is authenticated with an API key; every response is JSON.

• One call, every registry. Omit jurisdictions to sweep all 57 sources, or name a subset.
• Sync-first. A typical POST /v1/search is a cache read and returns in well under a second.
• Provenance built in. Every record links back to the official registry record with a lastCheckedAt.
• Additive contract. New data (e.g. criminal records) lands as a new recordType — the response shape never breaks.

Quickstart

Create a key in your dashboard, export it, and make your first search. Passing jurisdictions: null (or omitting it) searches all 57 registries at once.

curl https://api.offendersearch.com/v1/search \
  -H "X-API-Key: $OFFENDERSEARCH_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": {
      "firstName": "John",
      "lastName": "Doe",
      "dob": "1980-04-12"
    },
    "jurisdictions": null,
    "freshness": "standard",
    "match": "balanced",
    "include": ["stateData"]
  }'

Authentication

Authenticate every request with your secret key in the X-API-Key header. Keys are created, named, scoped, rotated, and revoked from the API keys page. A key’s secret is shown in full only once, at creation, and is hashed at rest — store it in a secret manager, never in client-side code.

curl https://api.offendersearch.com/v1/sources \
  -H "X-API-Key: os_live_9f2a…"

Key scopes

Each key can be scoped to the freshness tiers it may request (standard, weekly, daily) and whether it may generate billable verification reports. A request that exceeds a key’s scope is rejected with 401.

Errors & status codes

The API uses conventional HTTP status codes. Note that a 200 can still be a partial result: when a slow registry can’t beat your deadlineMs, its last-known rows are returned and flagged in sourceStatus rather than failing the whole call. Billing must be enabled on every account before the API returns live results.

Error response body

Every non-2xx response returns a JSON body with a stable error.code you can switch on and a human-readable error.message.

{
  "error": {
    "code": "invalid_request",
    "message": "query requires at least one of lastName, q, or a lat/lng radius."
  }
}

Rate limits & quotas

Requests are rate limited per API key. When you exceed your plan’s sustained rate or monthly quota the API responds with 429 Too Many Requests and a Retry-After header (seconds) telling you when to try again. Every response also carries the current limit state so you can throttle proactively.

Concurrency and monthly volume are set by your plan. For large batch jobs, prefer the asynchronous endpoint and spread submissions rather than firing thousands of synchronous calls at once. Need a higher ceiling? Contact us and we’ll raise your limits. Handle 429 with exponential backoff that respects Retry-After.

How a search works

Every search moves through the same four stages, so the response is predictable:

1. Fan-out. Your query is dispatched in parallel to every registry you targeted (all 57 by default, or the codes in jurisdictions).
2. Match & verify. Each registry’s rows are filtered by your match mode, then checked against any dob/age you supplied to confirm identity.
3. De-duplicate & score. The same person found in multiple registries is merged into one record whose sources[] lists every corroborating registry, and each record gets a matchConfidence and matchBasis.
4. Return. You get records, a per-registry sourceStatus, and counts — with status: "complete" or "partial".

Per-source status

Every registry the sweep touched appears in sourceStatus[] with its own status — so a slow or unavailable jurisdiction is transparent, never a silent gap:

Matching & confidence

The match field sets the fuzzy-match tolerance applied uniformly across every registry, so behavior is consistent no matter which states you hit. Whatever mode you choose, providing a dob or age is the strongest lever on accuracy — it verifies identity and pushes matchConfidence toward 1.0.

Read matchBasis to see exactly why a record matched (for example ["dob_match", "exact_name"] vs ["surname_only"]) so you can set your own confidence threshold for auto-accept vs manual review.

Freshness tiers

Freshness is a per-call field that sets the maximum acceptable data age. Fresher data means more re-verification on our side, so higher tiers carry a per-call uplift. Every record returns a lastCheckedAt so you can see exactly how current it is.

Base is $0.10 per search (Standard tier = base only); Weekly freshness adds $0.01 and Daily adds $0.035 per search. See pricing for full details.

Jurisdictions & codes

The jurisdictions array controls which registries run. Omit it or send null to search every registry — the default and common case. Naming codes narrows the sweep to exactly those registries.

• jurisdictions: null → all registries (default).
• ["IL"] → the Illinois dedicated registry only.
• ["IL", "NSOPW"] → Illinois and the national NSOPW source.

Registry codes

National source: NSOPW. State & territory codes are the standard USPS abbreviations:

Sync, async & webhooks

Use POST /v1/search for the fast, common path — it returns within deadlineMs and marks any registry that couldn’t finish as stale. Use POST /v1/searches when you need a guaranteed-complete sweep including slow, browser-gated states; then poll GET /v1/searches/{searchId} or supply a webhookUrl to be notified on completion.

Webhooks

Supply a webhookUrl on an async search and we POST the finished SearchResponse to it when the sweep completes — no polling required. Respond 2xx promptly to acknowledge; non-2xx responses are retried with exponential backoff for several attempts. Deliveries are signed so you can verify authenticity.

{
  "event": "search.completed",
  "searchId": "srch_9f2a7c",
  "status": "complete",
  "counts": { "records": 3, "sourcesQueried": 57, "sourcesStale": 0 },
  "records": [ /* … scored, de-duplicated records … */ ]
}

Idempotency

Network retries should never start — or bill — a second search. Send an Idempotency-Key header (any unique client-generated string, e.g. a UUID or your order id) on POST /v1/searches. If we’ve already seen that key, we return the original job instead of creating a new one, so a timeout-and-retry is safe.

curl https://api.offendersearch.com/v1/searches \
  -H "X-API-Key: $OFFENDERSEARCH_KEY" \
  -H "Idempotency-Key: 7f0c2e14-order-4821" \
  -H "Content-Type: application/json" \
  -d '{ "query": { "lastName": "Doe" }, "freshness": "daily" }'

Reuse the same key when retrying the same logical request; use a fresh key for a genuinely new search. Keys are scoped to your account and retained long enough to cover normal retry windows.

Pagination

POST /v1/search returns the full, de-duplicated result set for a query in a single response — there is no page cursor to manage for a normal identity search, because matches are already scored and merged across registries.

• Broad geographic sweeps. A wide lat/lng + radiusMiles query can match many registrants. Narrow the radius or add name filters, or run it as an async search for a guaranteed-complete set.
• offenders.io compatibility. The compat endpoint preserves their paged envelope — pass page and read page / totalPages from the response exactly as before.

Verification report

A branded, timestamped PDF/HTML report of your search results that cites the originating registry and links back to the official record — a defensible artifact for your audit file. 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 available to every account and billed per document, for only the registries you explicitly name. Request it inline on a search via the proof field, or after the fact via POST /v1/searches/{searchId}/proof.

{
  "registries": ["NJ", "NSOPW"],
  "format": "pdf"
}

Security & HIPAA

Offendersearch is built for compliance-sensitive customers. All API traffic is served over TLS and data is encrypted at rest; API keys are per-account and stored only as one-way hashes; access to production data is least-privilege; and every request is logged for audit. A Business Associate Agreement (BAA) is available to eligible enterprise accounts that process PHI through the API.

• Encryption. TLS in transit, AES-256 at rest for stored records and reports.
• Per-key hashing. Secrets are hashed at rest — a database read can never expose a usable key.
• Access controls & tenant isolation. Data is scoped per account; one customer can never read another’s keys, usage, or reports.
• Audit logging. Requests are logged with account, timestamp, and endpoint; usage is visible to account owners.
• Honest posture. BAA available and a formal SOC 2 examination is in progress — we don’t claim certifications we don’t hold.

Migrating from offenders.io

Point existing integrations at POST /v1/compat/sexoffender. It accepts offenders.io’s exact parameters and returns their exact { offenders, page, totalPages } envelope — switch by changing only the base URL and key, with no changes to your request or response handling. When you’re ready, move to /v1/search for scored matches, provenance, freshness tiers, and verification reports.

Parameter map

Every offenders.io input has a home in our contract:

What you gain

Moving from compat to /v1/search adds capabilities offenders.io doesn’t offer:

• Scored matches. Every record carries matchConfidence (0–1) and matchBasis. offenders.io returns raw rows with no score.
• Identity verification. dobVerification and unverified tell you exactly how each record was checked against your DOB/age.
• De-duplicated people. One record per person with a sources[] array of every corroborating registry — not repeated rows.
• Per-source status + partial results. sourceStatus reports each registry (ok / stale / error / …) instead of a silent black box.
• Freshness tiers. standard / weekly / daily control data age; every record reports its true lastCheckedAt.
• Verification reports. Branded, timestamped PDF/HTML audit artifacts per registry, on demand.
• Sync-first speed. One blocking call returns scored results — typically sub-second — with async available for deep sweeps.

The Record object

Every match in a search response is a normalized Record. The same schema is returned by /v1/search and /v1/records/{id}. Key fields:

{
  "recordId": "rec_4b1e",
  "recordType": "sex_offender",
  "matchConfidence": 0.98,
  "matchBasis": ["dob_match", "exact_name"],
  "name": { "first": "John", "middle": "A", "last": "Doe", "full": "John A. Doe" },
  "dob": "1980-04-12",
  "dobPrecision": "exact",
  "sex": "male",
  "addresses": [
    { "type": "residence", "city": "Trenton", "state": "NJ" }
  ],
  "offense": { "tier": "II", "statute": "2C:14-2" },
  "flags": { "absconder": false, "predator": false },
  "dobVerification": "dob_match",
  "unverified": false,
  "source": {
    "jurisdiction": "NJ",
    "registryName": "NJ Sex Offender Internet Registry",
    "recordUrl": "https://www.icrimewatch.net/...",
    "lastCheckedAt": "2026-07-25T09:14:00Z"
  },
  "sources": [
    {
      "jurisdiction": "NJ",
      "registryName": "NJ Sex Offender Internet Registry",
      "recordUrl": "https://www.icrimewatch.net/...",
      "lastCheckedAt": "2026-07-25T09:14:00Z"
    }
  ]
}