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¶
- 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.
- Configure a webhook (optional but recommended) from the same settings page.
- Retrieve available packages using the API key and the email address of an active Xref user within the organisation.
- Select a package, inspect its input schema, then create a request for a recipient.
- Monitor request status using webhook notifications, or poll
GET /v1/requests/{request_id}. Processing usually ends atCOMPLETED, but the status can transition again if checks are replaced or disputed.ERRORandCANCELLEDdo 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:
Sections¶
- Authentication — required authentication headers and user identification.
- Endpoints
- Webhooks — webhook payloads and signature verification.
- Errors and status codes — error responses and HTTP status codes.
- Changelog — versioned release notes.