Sex Offender Search API · v1.0.0

Async search, webhooks & idempotency

Submit and collect without holding a connection open. Webhook delivery and safe retries.

Livehttps://api.offendersearch.appSandboxhttps://sandbox.offendersearch.app

Choosing sync or async

Use POST /v1/search when a person is waiting on the answer — it is the interactive endpoint and returns in one round trip, with per-jurisdiction status in sourceStatus. Use POST /v1/searches for batch and high-volume work: submit the search, then collect the result by polling GET /v1/searches/{searchId} or by supplying a webhookUrl. Both return the same envelope — the choice is about how you collect the result. A live re-verification of more than two sources is collected through GET /v1/searches/{searchId} the same way.

SynchronousAsynchronous
EndpointPOST /v1/searchPOST /v1/searches
ShapeOne round trip; elapsedMs on every responseSubmit now, collect when ready
ScopeBounded by deadlineMsNot tied to an open connection; a jurisdiction that does not finish is labelled in sourceStatus
DataIdentical — same response envelope and Record schema
DeliveryIn the responsePoll or webhook
Best forInteractive checks, anything user-facingBulk screening, periodic re-screens, backfills, scheduled jobs

For many independent lookups in a single HTTP call — a roster, a CSV export — see Batch & CSV search, which is the third shape and returns one result per input row.

POST/v1/searchesAuth: X-API-Key

Asynchronous search — built for batch and high volume

The batch endpoint. Submit the search, get a job id back immediately, and collect the result when it is ready. Built for bulk screening, periodic re-screens, backfills and unattended scheduled jobs.

The async endpoint accepts the same request body as the synchronous search, plus an optional webhookUrl. Instead of waiting, it returns 202 Accepted with a searchId and a resultsUrl right away and runs the search in the background; when it finishes, every jurisdiction is reported in sourceStatus, exactly as on a synchronous search. A live block is accepted here but not run: send it to POST /v1/search, which runs a live check of more than two registries as a job you poll.

Because you are not holding a connection open, nothing on your side waits on the search — which is what makes this the right endpoint for bulk screening a roster, re-screening a population on a schedule, backfills, and unattended jobs. The search works to the same per-jurisdiction time limits as a synchronous one, and a jurisdiction that does not finish is labelled in sourceStatus, never left out silently.

Retrieve results by polling GET /v1/searches/{searchId} until status is complete, or supply a webhookUrl and we will POST the finished SearchResponse to it — no polling required.

Reach for POST /v1/search instead when a person is waiting on the answer: that is the interactive endpoint and it returns in one round trip. Both endpoints return the same envelope and Record schema — the choice is about how you collect the result. A live re-verification of more than two sources is collected through GET /v1/searches/{searchId} the same way.

Every accepted request is a new job and is billed as one search, so keep the searchId you were given and poll it rather than submitting the same search again. See Idempotency.

What you can do
  • Built for volume. Nothing waits on an open connection. Submit many, collect the results as they finish.
  • Webhook or poll. Get notified via webhookUrl, or poll the results URL on your own schedule.
  • Same query surface. All query fields, jurisdictions, match and include carry over. A live block is accepted but not run on this endpoint.
  • One job per request. Each accepted request is its own job and its own search; store the searchId and poll it rather than resubmitting.
Request
curl https://api.offendersearch.app/v1/searches \
  -H "X-API-Key: $OFFENDERSEARCH_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": { "lastName": "Doe" },
    "jurisdictions": null,
    "webhookUrl": "https://acme.example/hooks/os"
  }'
Response
200 OK
{
  "searchId": "srch_9f2a7c",
  "status": "pending",
  "jurisdictionsQueried": 58,
  "estimatedCompletionSec": 20,
  "resultsUrl": "/v1/searches/srch_9f2a7c"
}

Returns 202 Accepted with status "pending"; poll resultsUrl or wait for the webhook.

Async search API request and response fields

POST/v1/searchesAuth: X-API-Key

Submit a search and collect the result later, by polling or by webhook. Accepts every SearchRequest field plus webhookUrl, including a live block (the named registries are re-verified live inside the job and billed as on POST /v1/search), and returns 202 with a job id immediately.

Request

Body · application/json

Every field of the SearchRequest object, plus:

FieldTypeDescription
webhookUrl
optional
string (uri) or nullA URL to receive the finished result. One POST with the same body GET /v1/searches/{searchId} returns, sent once with a 10-second timeout and not retried. Poll resultsUrl for the authoritative result. Must be an https:// URL on a public host name or public IP; anything else (a malformed URL, http://, localhost, a private, loopback or link-local address) is refused with 422. Redirects are not followed.

Response

202 · application/json

The job was accepted and is billed as one search. Poll resultsUrl.

FieldTypeDescription
searchId
stringThe job id. Poll GET /v1/searches/{searchId}.
Example "srch_9f2c1a7b"
status
string
one of "pending", "running"
pending on acceptance.
jurisdictionsQueried
integerHow many registries the job will search.
estimatedCompletionSec
integerSeconds until the job is expected to finish (20).
Example 20
resultsUrl
stringThe path to poll for status and results.
Example "/v1/searches/srch_9f2c1a7b"
Errors
StatusCodeWhen
401—The X-API-Key header is missing or the key is not valid.
402—The account has no active subscription and no free-trial searches left. detail says which.
402—The request sent proof and billing is not enabled on the account.
422—A field is malformed or unrecognised (an unknown jurisdiction code, an unknown match value, a filter placed outside query), or the query narrows on nothing. detail says which.

Get an async search: status and result fields

GET/v1/searches/{searchId}Auth: X-API-Key

Read an async job's status and, once it has finished, its full result.

Request

Path parameters
FieldTypeDescription
searchId
required
stringThe id returned by POST /v1/searches (or by a live search's acknowledgement).
Example "srch_9f2c1a7b"

Response

200 · application/json

When the job has finished, the full search response. While it is pending or running, a short body: searchId, status, counts (records: 0, sourcesQueried, sourcesIncomplete: 0), sourceStatus: [], records: [] and proof: {"status": "none"}. When the job failed: searchId, status: "error", error and records: [].

The body is the SearchResponse object. The body every sex offender search returns: the matched records, how many registries answered, and a per-registry status for each one.

Errors
StatusCodeWhen
401—The X-API-Key header is missing or the key is not valid.
402—The account has no active subscription and no free-trial searches left. detail says which.
404—No search with this id on this account (a search run by another account answers the same 404). The body is an Error.

Stored search results API: re-open a past search

GET/v1/searches/{searchId}/resultsAuth: X-API-Key or session

Re-open a past search on this account and get back exactly the records it returned. The search is not run again and the call is not billed.

Request

Path parameters
FieldTypeDescription
searchId
required
stringThe searchId of a search on this account.
Example "srch_9f2c1a7b"

Response

200 · application/json

The stored results.

FieldTypeDescription
searchId
stringThe search's id.
ranAt
string (date-time)When the search ran.
status
string or nullThe search's status when it ran.
query
objectThe query that was sent, with empty fields removed.
records
array of RecordThe records the search returned, as they were returned.
storedCount
integerRecords filed with the search.
totalCount
integerRecords the search matched. Higher than storedCount when the search matched more records than are filed per search.
retentionDays
integerHow many days results are kept before they are erased.
202 · application/json

The async search is still running. Poll GET /v1/searches/{searchId}; the results are filed here when it completes.

FieldTypeDescription
searchId
stringThe search's id.
status
string
one of "pending", "running"
The job's status.
detail
stringWhat to do next, as a sentence.
Errors
StatusCodeWhen
401—The X-API-Key header is missing or the key is not valid.
402—The account has no active subscription and no free-trial searches left. detail says which.
410—The results are past the retention window and have been erased, or this account has no such search. Run the search again.

Webhooks

Supply a webhookUrl on an async search and the finished SearchResponse is POSTed to it when the search completes — no polling required. The body is the same search response that GET /v1/searches/{searchId} returns. Delivery is one attempt with a 10-second timeout: it is not retried and not signed. Treat it as a notification, then confirm the result by fetching GET /v1/searches/{searchId} with your API key — that response is the source of truth, and polling it always works even if the webhook never arrives.

Delivery
POST to your webhookUrl
{
  "searchId": "srch_9f2a7c",
  "status": "complete",
  "counts": { "records": 3, "sourcesQueried": 58,
              "sourcesComplete": 58, "sourcesIncomplete": 0 },
  "sourceStatus": [ /* one entry per jurisdiction */ ],
  "records": [ /* … scored, de-duplicated records … */ ]
}
Confirming the result
Express handler
app.post("/hooks/os", express.json(), async (req, res) => {
  res.sendStatus(200);             // acknowledge promptly

  // The webhook is a notification: it is unsigned and sent once.
  // Fetch the search with YOUR key and trust that response instead.
  const { searchId } = req.body;
  const r = await fetch(
    `https://api.offendersearch.app/v1/searches/${searchId}`,
    { headers: { "X-API-Key": process.env.OS_API_KEY } });
  if (r.ok) enqueue(searchId, await r.json());   // de-duplicate on searchId
});
Async-search webhooks are unsigned and sent once, so never act on the payload alone: fetch GET /v1/searches/{searchId} with your API key to confirm, and keep polling as the fallback. (Monitoring alert webhooks are different: each is signed with the monitor's own secret — see the Monitoring API's Delivery page.)

Idempotency

Every request POST /v1/searches accepts is a new job, billed as one search at acceptance. The API does not read an idempotency header, so make retries safe on your side: persist the searchId from the 202 the moment you receive it, and recover by polling that id rather than submitting the same search again.

Submit once, then poll the stored id
let searchId = await jobs.get(orderId);          // your own store
if (!searchId) {
  const res = await fetch("https://api.offendersearch.app/v1/searches", {
    method: "POST",
    headers: { "X-API-Key": process.env.OFFENDERSEARCH_KEY,
               "Content-Type": "application/json" },
    body: JSON.stringify({ query: { lastName: "Doe" } }),
  });
  ({ searchId } = await res.json());
  await jobs.set(orderId, searchId);               // persist before anything else
}
// A retry after a crash lands here and polls the same job.

A dropped connection on the submit itself is the one case this cannot cover: when no 202 arrived, you cannot know whether the job was accepted. For 429 handling and backoff, see Errors & rate limits.

Product overview