Async search, webhooks & idempotency
Submit and collect without holding a connection open. Webhook delivery and safe retries.
Livehttps://api.offendersearch.appSandboxhttps://sandbox.offendersearch.appChoosing 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.
| Synchronous | Asynchronous | |
|---|---|---|
| Endpoint | POST /v1/search | POST /v1/searches |
| Shape | One round trip; elapsedMs on every response | Submit now, collect when ready |
| Scope | Bounded by deadlineMs | Not tied to an open connection; a jurisdiction that does not finish is labelled in sourceStatus |
| Data | Identical — same response envelope and Record schema | |
| Delivery | In the response | Poll or webhook |
| Best for | Interactive checks, anything user-facing | Bulk 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.
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.
- 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.
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"
}'{
"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
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
Every field of the SearchRequest object, plus:
| Field | Type | Description |
|---|---|---|
| webhookUrl optional | string (uri) or null | A 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
The job was accepted and is billed as one search. Poll resultsUrl.
| Field | Type | Description |
|---|---|---|
| searchId | string | The job id. Poll GET /v1/searches/{searchId}.Example "srch_9f2c1a7b" |
| status | string one of "pending", "running" | pending on acceptance. |
| jurisdictionsQueried | integer | How many registries the job will search. |
| estimatedCompletionSec | integer | Seconds until the job is expected to finish (20). Example 20 |
| resultsUrl | string | The path to poll for status and results. Example "/v1/searches/srch_9f2c1a7b" |
| Status | Code | When |
|---|---|---|
| 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 a search
Fetch the current status and results of an asynchronous search.
Once the job finishes, returns the same SearchResponse the synchronous endpoint returns, with status complete or partial. While it is pending or running, records and sourceStatus are empty and counts.records is 0; poll again until the status changes.
Poll on your own cadence (a few seconds is typical), or skip polling entirely by supplying a webhookUrl on the original request.
curl https://api.offendersearch.app/v1/searches/srch_9f2a7c \
-H "X-API-Key: $OFFENDERSEARCH_KEY"{
"searchId": "srch_9f2a7c",
"status": "complete",
"elapsedMs": 41230,
"counts": { "records": 3 },
"sourceStatus": [ /* … per-jurisdiction status … */ ],
"records": [ /* … scored, de-duplicated records … */ ]
}Returns 404 if the searchId does not exist. status stays pending or running until the job finishes.
Get an async search: status and result fields
Read an async job's status and, once it has finished, its full result.
Request
| Field | Type | Description |
|---|---|---|
| searchId required | string | The id returned by POST /v1/searches (or by a live search's acknowledgement).Example "srch_9f2c1a7b" |
Response
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.
| Status | Code | When |
|---|---|---|
| 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
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
| Field | Type | Description |
|---|---|---|
| searchId required | string | The searchId of a search on this account.Example "srch_9f2c1a7b" |
Response
The stored results.
| Field | Type | Description |
|---|---|---|
| searchId | string | The search's id. |
| ranAt | string (date-time) | When the search ran. |
| status | string or null | The search's status when it ran. |
| query | object | The query that was sent, with empty fields removed. |
| records | array of Record | The records the search returned, as they were returned. |
| storedCount | integer | Records filed with the search. |
| totalCount | integer | Records the search matched. Higher than storedCount when the search matched more records than are filed per search. |
| retentionDays | integer | How many days results are kept before they are erased. |
The async search is still running. Poll GET /v1/searches/{searchId}; the results are filed here when it completes.
| Field | Type | Description |
|---|---|---|
| searchId | string | The search's id. |
| status | string one of "pending", "running" | The job's status. |
| detail | string | What to do next, as a sentence. |
| Status | Code | When |
|---|---|---|
| 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.
{
"searchId": "srch_9f2a7c",
"status": "complete",
"counts": { "records": 3, "sourcesQueried": 58,
"sourcesComplete": 58, "sourcesIncomplete": 0 },
"sourceStatus": [ /* one entry per jurisdiction */ ],
"records": [ /* … scored, de-duplicated records … */ ]
}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
});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.
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.