Async search, webhooks & idempotency

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 within deadlineMs, 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 read the same corpus and return the same envelope — the choice is about how you collect the result, not how current it is. A live re-verification of more than two sources is collected here the same way.

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.

Webhooks

Supply a webhookUrl on an async search and the finished SearchResponse is POSTed to it when the search completes — no polling required. Delivery is a single best-effort 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
});

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 that key has been seen before, the original job is returned instead of a new one being created, so a dropped-connection retry is safe.

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

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. For 429 handling and backoff, see Errors & rate limits.