FCRA Partner API · v1.0.0 · approved partners

Webhooks & events

Signed, retried, identifiers-only events — and the list to poll if one is missed.

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

Configuration

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

PUT/v1/fcra/webhook-endpointAuth: X-API-Key

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

Body · application/json
FieldTypeDescription
url
required
string (uri)Your webhook URL, https://, up to 2,000 characters.
Example "https://your-cra.example/hooks/offendersearch"
rotateSecret
optional · default false
booleantrue issues a new signing secret, returned once in this response.

Response

200 · application/json

The endpoint.

The body is the WebhookEndpoint object. Your FCRA webhook endpoint. secret appears only in the response that created it or rotated it.

Errors
StatusCodeWhen
401—No valid X-API-Key (the body is { "detail": "…" }, a string).
403fcra_not_enabledThis account has no active FCRA partner agreement.
403fcra_not_on_trialFCRA 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.

FieldTypeDescription
configured
booleantrue 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
stringThe 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

GET/v1/fcra/webhook-endpointAuth: X-API-Key

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

200 · application/json

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.

Errors
StatusCodeWhen
401—No valid X-API-Key (the body is { "detail": "…" }, a string).
403fcra_not_enabledThis account has no active FCRA partner agreement.
403fcra_not_on_trialFCRA orders are not available on a trial account.

Remove the FCRA webhook endpoint — DELETE /v1/fcra/webhook-endpoint

DELETE/v1/fcra/webhook-endpointAuth: X-API-Key

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

200 · application/json

Whether an endpoint was removed.

FieldTypeDescription
deleted
booleantrue when an endpoint existed and was removed.
Errors
StatusCodeWhen
401—No valid X-API-Key (the body is { "detail": "…" }, a string).
403fcra_not_enabledThis account has no active FCRA partner agreement.
403fcra_not_on_trialFCRA orders are not available on a trial account.
403—A dashboard session of a team member who is not an admin.

Events

EventWhen
order.createdAn order was accepted.
search.completedOne search in an order finished, including one that ended in error — read it.
order.completedEvery search in the order finished.
order.cancelledThe order was cancelled.
dispute.createdA dispute was opened on one of your orders — by you or through the consumer portal.
dispute.updatedA dispute moved to investigating, was extended with new information, or was resolved.
record.correctedA record you received was modified or removed by a dispute.
record.verification_pendingliveScope: "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.verifiedliveScope: "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_failedliveScope: "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.

Webhook payload
{
  "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.

Record verification events (one delivery each)
// 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.

FieldTypeDescription
id
stringThe 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
EventDataIts 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.

FieldTypeDescription
orderId
stringThe order. Present on every event except record.corrected.
searchId
stringsearch.completed and the record.verification_* / record.verified events: the search.
disputeId
stringdispute.created, dispute.updated and record.corrected: the dispute.
recordId
stringrecord.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
stringThe 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
stringrecord.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.

Verify a delivery (Node)
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

GET/v1/fcra/eventsAuth: X-API-Key

Every event for your account in the order it happened, each with its delivery status, so a missed delivery is never lost.

Request

Query parameters
FieldTypeDescription
after
optional
stringAn event id; only events after it are returned.
limit
optional · default 100
integerEvents per page, 1 to 500.

Response

200 · application/json

One page of events, oldest first.

FieldTypeDescription
events
array of EventThe events.
nextAfter
string or nullThe 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).
Errors
StatusCodeWhen
401—No valid X-API-Key (the body is { "detail": "…" }, a string).
403fcra_not_enabledThis account has no active FCRA partner agreement.
403fcra_not_on_trialFCRA 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.

FieldTypeDescription
id
stringThe 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
EventDataIts identifiers and statuses.
delivery
objectHow 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
integerDelivery attempts so far.
delivery.deliveredAt
string (date-time) or nullWhen your endpoint answered 2xx. null until then.
delivery.nextAttemptAt
string (date-time) or nullWhen the next retry runs. null unless status is pending.
delivery.lastStatus
integer or nullThe 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

POST/v1/fcra/events/{event_id}/resendAuth: X-API-Key

Delivers one event to your webhook again, now, and returns it with the result of that attempt.

Request

Path parameters
FieldTypeDescription
event_id
required
stringThe event id (fev_…).
Example "fev_5f1e3340306f1d02"

Response

200 · application/json

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.

Errors
StatusCodeWhen
401—No valid X-API-Key (the body is { "detail": "…" }, a string).
403fcra_not_enabledThis account has no active FCRA partner agreement.
403fcra_not_on_trialFCRA orders are not available on a trial account.
404not_foundNo such event on this account.

Product overview