Skip to content

Xref API

Welcome to the public documentation for the Xref API, hosted at https://api.xref.com. This API lets your systems trigger Xref reference and background checks, retrieve their status, and receive asynchronous updates via webhooks.

This documentation describes API v1.

What you can do with the API

  • List the packages available to the organisation and user account.
  • Inspect the input schema for a package to determine the required recipient and partner-specific fields for the request.
  • Create a request for a recipient using a selected package. Requests are accepted immediately and processed asynchronously.
  • Retrieve a request to view its overall status and the status of its associated reference and background checks.
  • Download reports for completed reference and background checks.
  • Receive webhook notifications when a request changes state.

Quick start

  1. Generate an API key. An organisation Owner can enable the Xref API in Organisation Settings → Xref API and generate an API key. The API key is displayed only once and should be stored securely.
  2. Configure a webhook (optional but recommended) from the same settings page.
  3. Retrieve available packages using the API key and the email address of an active Xref user within the organisation.
  4. Select a package, inspect its input schema, then create a request for a recipient.
  5. Monitor request status using webhook notifications, or poll GET /v1/requests/{request_id}. Processing usually ends at COMPLETED, but the status can transition again if checks are replaced or disputed. ERROR and CANCELLED do not change.

API overview

Property Value
Base URL https://api.xref.com
API version v1 (path-prefixed: /v1/...)
Transport HTTPS only
Content type application/json
Auth API key and user email headers. See Authentication.
Throttling 60 requests per minute and 1,000 requests per hour, per API key. 429 responses include a Retry-After header.
Health check GET /v1/ping — authentication not required

All responses use the standard envelope:

{
  "data": {},
  "status_message": "ok",
  "message": ""
}

Sections