Webhooks & events
Signed, retried, identifiers-only events — and the list to poll if one is missed.
Livehttps://api.offendersearch.appSandboxhttps://sandbox.offendersearch.appConfiguration
Set your webhook URL with PUT /v1/fcra/webhook-endpoint and { "url": "https://…" } (from the dashboard, an account admin only). The response contains the signing secret — shown only when the endpoint is created or when you send "rotateSecret": true, so store it then. GET shows whether an endpoint is configured; DELETE removes it. A callbackUrl on an order sends that order’s events to a different URL, signed with the same secret; it needs a configured endpoint (422 webhook_endpoint_required), and record.corrected always goes to your endpoint.
Set the FCRA webhook URL — PUT /v1/fcra/webhook-endpoint request and response
Sets your webhook URL. The response carries the signing secret when the endpoint is created and when rotateSecret is true — store it then. From the dashboard, only an account admin can call it.
Request
| Field | Type | Description |
|---|---|---|
| url required | string (uri) | Your webhook URL, https://, up to 2,000 characters.Example "https://your-cra.example/hooks/offendersearch" |
| rotateSecret optional · default false | boolean | true issues a new signing secret, returned once in this response. |
Response
The endpoint.
The body is the WebhookEndpoint object. Your FCRA webhook endpoint. secret appears only in the response that created it or rotated it.
| Status | Code | When |
|---|---|---|
| 401 | — | No valid X-API-Key (the body is { "detail": "…" }, a string). |
| 403 | fcra_not_enabled | This account has no active FCRA partner agreement. |
| 403 | fcra_not_on_trial | FCRA orders are not available on a trial account. |
| 403 | — | A dashboard session of a team member who is not an admin (detail is a string). |
| 422 | — | url is not an absolute https:// URL (the standard validation body). |
The WebhookEndpoint object — FCRA webhook endpoint fields
Your FCRA webhook endpoint. secret appears only in the response that created it or rotated it.
Returned or accepted by GET /v1/fcra/webhook-endpoint, PUT /v1/fcra/webhook-endpoint.
| Field | Type | Description |
|---|---|---|
| configured | boolean | true when an endpoint is set. The other fields are present only then. |
| url | string (uri) | Where events are delivered. |
| createdAt | string (date-time) | When the endpoint was first set. |
| updatedAt | string (date-time) | When it last changed. |
| signatureHeader | string one of "X-Offendersearch-Signature" | The request header that carries each delivery's signature. |
| secret | string | The signing secret (whsec_…). Present only in the PUT response that created the endpoint or rotated the secret; no endpoint returns it again. |
FCRA webhook endpoint — GET /v1/fcra/webhook-endpoint
Whether a webhook endpoint is configured, and where. The secret is never returned here.
Request
No parameters and no body beyond the X-API-Key header.
Response
The endpoint, or { "configured": false }.
The body is the WebhookEndpoint object. Your FCRA webhook endpoint. secret appears only in the response that created it or rotated it.
| Status | Code | When |
|---|---|---|
| 401 | — | No valid X-API-Key (the body is { "detail": "…" }, a string). |
| 403 | fcra_not_enabled | This account has no active FCRA partner agreement. |
| 403 | fcra_not_on_trial | FCRA orders are not available on a trial account. |
Remove the FCRA webhook endpoint — DELETE /v1/fcra/webhook-endpoint
Removes your webhook endpoint. Events are still recorded, with delivery status no_endpoint, and listed by GET /v1/fcra/events.
Request
No parameters and no body beyond the X-API-Key header.
Response
Whether an endpoint was removed.
| Field | Type | Description |
|---|---|---|
| deleted | boolean | true when an endpoint existed and was removed. |
| Status | Code | When |
|---|---|---|
| 401 | — | No valid X-API-Key (the body is { "detail": "…" }, a string). |
| 403 | fcra_not_enabled | This account has no active FCRA partner agreement. |
| 403 | fcra_not_on_trial | FCRA orders are not available on a trial account. |
| 403 | — | A dashboard session of a team member who is not an admin. |
Events
| Event | When |
|---|---|
order.created | An order was accepted. |
search.completed | One search in an order finished, including one that ended in error — read it. |
order.completed | Every search in the order finished. |
order.cancelled | The order was cancelled. |
dispute.created | A dispute was opened on one of your orders — by you or through the consumer portal. |
dispute.updated | A dispute moved to investigating, was extended with new information, or was resolved. |
record.corrected | A record you received was modified or removed by a dispute. |
record.verification_pending | liveScope: "matches": a possible record is held while its source agency confirms it. Sent when a search first holds a record. data: orderId, searchId, status: "pending_verification". Make no decision on the search yet. |
record.verified | liveScope: "matches": a held record was confirmed at its source and is now on the report. data: orderId, searchId (the new search), recordId, status: "verified_at_source". |
record.verification_failed | liveScope: "matches": a held record will not be reported. data: orderId, searchId, status (withheld: gone, sealed or expunged at the source; not_verifiable: not confirmed within five business days) and reason (not_current_at_source, sealed_or_expunged, verification_unavailable). |
The payload carries identifiers and statuses only — never personal data. Fetch the order, search or dispute with your key to read the detail.
{
"id": "fev_5f1e3340306f1d02",
"type": "search.completed",
"createdAt": "2026-10-02T14:04:12Z",
"data": { "orderId": "fo_ee0b34c5b52fd35b", "searchId": "fs_9c03d7e1a4b6f258", "type": "criminal",
"status": "complete", "result": "records_found" }
}The three record.verification_* / record.verified events follow the order’s callbackUrl like the other order events. A held record’s outcome also re-runs the search, so search.completed and order.completed follow for the new search; a record.verification_failed never carries a record id, because a record that is not reported is never identified.
// a possible record is held while its source confirms it
{ "id": "fev_8a10c2d94e5b7f31", "type": "record.verification_pending",
"createdAt": "2026-10-30T14:02:14Z",
"data": { "orderId": "fo_3c9e2b7a1d40f865", "searchId": "fs_7d21c0a9e4b3f516",
"status": "pending_verification" } }
// the source confirmed it: the search was run again and the record is on the report
{ "id": "fev_8a10c3e15f6c8a42", "type": "record.verified",
"createdAt": "2026-10-30T15:03:40Z",
"data": { "orderId": "fo_3c9e2b7a1d40f865", "searchId": "fs_b0e4f7a2c9d15368",
"recordId": "crim:IL-COOK:2019CR118203", "status": "verified_at_source" } }
// not reported: gone, sealed or expunged at the source…
{ "id": "fev_8a10c4f2607d9b53", "type": "record.verification_failed",
"createdAt": "2026-10-30T15:03:40Z",
"data": { "orderId": "fo_3c9e2b7a1d40f865", "searchId": "fs_b0e4f7a2c9d15368",
"status": "withheld", "reason": "sealed_or_expunged" } }
// …or not confirmed within five business days
{ "id": "fev_8a10c5a3718eac64", "type": "record.verification_failed",
"createdAt": "2026-11-06T14:05:02Z",
"data": { "orderId": "fo_3c9e2b7a1d40f865", "searchId": "fs_e2c81d5b7a9f0436",
"status": "not_verifiable", "reason": "verification_unavailable" } }A healthcare search sends the same events as the other searches: search.completed with type: "healthcare", then order.completed. It never holds a record, so it sends none of the record.verification_* events.
The WebhookDelivery object — FCRA webhook payload fields
The JSON body POSTed to your webhook URL (or the order's callbackUrl), signed in X-Offendersearch-Signature.
| Field | Type | Description |
|---|---|---|
| id | string | The event id. Deduplicate on it: a resend delivers the same id again. Example "fev_5f1e3340306f1d02" |
| type | string one of "order.created", "search.completed", "order.completed", "order.cancelled", "dispute.created", "dispute.updated", "record.corrected", "record.verification_pending", "record.verified", "record.verification_failed" | The event type, also in X-Offendersearch-Event. |
| createdAt | string (date-time) | When the event happened. |
| data | EventData | Its identifiers and statuses. Fetch the order, search or dispute with your key to read the detail. |
The EventData object — webhook event data fields
The identifiers and statuses an event carries — never personal data. Which keys are present depends on the event type (see the table under Events).
Returned or accepted by GET /v1/fcra/events, POST /v1/fcra/events/{event_id}/resend.
| Field | Type | Description |
|---|---|---|
| orderId | string | The order. Present on every event except record.corrected. |
| searchId | string | search.completed and the record.verification_* / record.verified events: the search. |
| disputeId | string | dispute.created, dispute.updated and record.corrected: the dispute. |
| recordId | string | record.corrected: the record that was corrected or removed. record.verified: the record now furnished. |
| type | string one of "sex_offender", "criminal", "healthcare" | search.completed only: the search type. |
| status | string | The object's status at the time: the order's (received, complete, error, cancelled), the search's (complete, unavailable, error) or the dispute's. Absent on record.corrected. |
| result | string one of "records_found", "clear", "incomplete" | search.completed only, when the search did not error: its result. |
| origin | string one of "partner", "consumer_portal" | dispute.created only: where the dispute was opened. |
| outcome | string one of "verified", "modified", "deleted", "unable_to_verify" | record.corrected only: the dispute outcome that changed the record. |
| reason | string | record.verification_failed only: why the possible record is not reported, as a withheld reason code (not_current_at_source, sealed_or_expunged, verification_unavailable …). |
Verifying the signature
Each delivery carries X-Offendersearch-Signature: t=<unix time>,v1=<hex HMAC-SHA256>, computed over t. followed by the raw request body with your webhook secret, plus X-Offendersearch-Event (the type) and X-Offendersearch-Event-Id. Reject a delivery whose signature does not match or whose timestamp is more than five minutes old.
import crypto from 'node:crypto';
// header: X-Offendersearch-Signature: t=1791000252,v1=5d41402a…
export function verify(rawBody, header, secret) {
const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
const expected = crypto
.createHmac('sha256', secret)
.update(`${parts.t}.${rawBody}`)
.digest('hex');
const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
return fresh && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}Retries, resends and polling
Respond with any 2xx. Each event is delivered at once; a failed delivery is retried a minute apart for the first ten attempts, then hourly, until 24 hours after the event was created; after that its delivery status is failed. Each attempt waits 10 seconds for your response. POST /v1/fcra/events/{id}/resend delivers an event again, and GET /v1/fcra/events?after=<eventId>&limit= (100 by default, up to 500) returns { events, nextAfter } — every event for your account in order, each with its delivery status (pending, delivered, failed, or no_endpoint when none is configured) — so a missed delivery is never lost. Events can arrive out of order; read the object’s current status rather than inferring it from the event sequence.
FCRA events API — GET /v1/fcra/events polling response
Every event for your account in the order it happened, each with its delivery status, so a missed delivery is never lost.
Request
| Field | Type | Description |
|---|---|---|
| after optional | string | An event id; only events after it are returned. |
| limit optional · default 100 | integer | Events per page, 1 to 500. |
Response
One page of events, oldest first.
| Field | Type | Description |
|---|---|---|
| events | array of Event | The events. |
| nextAfter | string or null | The last event id on this page — send it as after for the next page. On an empty page it repeats the after you sent (null when you sent none). |
| Status | Code | When |
|---|---|---|
| 401 | — | No valid X-API-Key (the body is { "detail": "…" }, a string). |
| 403 | fcra_not_enabled | This account has no active FCRA partner agreement. |
| 403 | fcra_not_on_trial | FCRA orders are not available on a trial account. |
The Event object — FCRA event fields
One FCRA event on your account, with its delivery status. GET /v1/fcra/events lists them, oldest first.
Returned or accepted by GET /v1/fcra/events, POST /v1/fcra/events/{event_id}/resend.
| Field | Type | Description |
|---|---|---|
| id | string | The event id (fev_…). Also sent as X-Offendersearch-Event-Id.Example "fev_5f1e3340306f1d02" |
| type | string one of "order.created", "search.completed", "order.completed", "order.cancelled", "dispute.created", "dispute.updated", "record.corrected", "record.verification_pending", "record.verified", "record.verification_failed" | The event type. |
| createdAt | string (date-time) | When the event happened. |
| data | EventData | Its identifiers and statuses. |
| delivery | object | How delivery to your webhook went. |
| delivery.status | string one of "pending", "delivered", "failed", "no_endpoint" | pending (a retry is scheduled), delivered (your endpoint answered 2xx), failed (no 2xx within 24 hours of the event) or no_endpoint (no webhook endpoint was configured). |
| delivery.attempts | integer | Delivery attempts so far. |
| delivery.deliveredAt | string (date-time) or null | When your endpoint answered 2xx. null until then. |
| delivery.nextAttemptAt | string (date-time) or null | When the next retry runs. null unless status is pending. |
| delivery.lastStatus | integer or null | The HTTP status of the last attempt; 0 when the connection itself failed. null before the first attempt. |
Resend an FCRA webhook event — POST /v1/fcra/events/{event_id}/resend
Delivers one event to your webhook again, now, and returns it with the result of that attempt.
Request
| Field | Type | Description |
|---|---|---|
| event_id required | string | The event id (fev_…).Example "fev_5f1e3340306f1d02" |
Response
The event after the attempt.
The body is the Event object. One FCRA event on your account, with its delivery status. GET /v1/fcra/events lists them, oldest first.
| Status | Code | When |
|---|---|---|
| 401 | — | No valid X-API-Key (the body is { "detail": "…" }, a string). |
| 403 | fcra_not_enabled | This account has no active FCRA partner agreement. |
| 403 | fcra_not_on_trial | FCRA orders are not available on a trial account. |
| 404 | not_found | No such event on this account. |