Changelog¶
All notable changes to the Xref API will be documented here. Versions follow
Semantic Versioning and are advertised via the URL
prefix (/v1/, /v2/, ...).
v1.0.0 — 2026-09-17¶
Initial public release of the Xref API.
Added¶
- Authentication. API-key + user-email header flow.
Unauthenticated
GET /v1/pingfor health checks. - Endpoints:
GET /v1/ping— health check; no authentication requiredGET /v1/packages— list packages available to the organisation; optionalstatusandidfiltersGET /v1/packages/{id}/schema— required and optional fields for a create-request payloadPOST /v1/requests— create a request asynchronously; returns201 Createdwithrequest_idGET /v1/requests/{id}— request status, checks, referee details, and signedreport_pdf_urlvaluesGET /v1/reports/{check_id}— download a background check PDF via headers or signed?t=tokenGET /v1/reports/{check_id}/referees/{referee_id}— download a referee PDF via headers or signed?t=tokenGET /v1/users— list organisation users, roles, teams, and product permissions
- Webhooks. Single configurable webhook per organisation. Payloads are
HMAC-SHA256-signed via the
X-Xref-Signatureheader. v1 emits a single event:request.updated. - Errors. Uniform
{data, status_message, message}envelope. Throttling (per-API-key, per-minute and per-hour windows) returning429withRetry-After.