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 via the Xref API.
  • 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 current status and the status of any associated checks, such as reference or 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:

    curl -X GET https://api.xref.com/v1/packages \
  -H "X-Xref-API-Key: <api-key>" \
  -H "X-Xref-User-Email: <user@company.com>"

  4. Select a package, inspect its input schema, then create a request for a recipient:

    curl -X POST https://api.xref.com/v1/requests \
  -H "X-Xref-API-Key: <api-key>" \
  -H "X-Xref-User-Email: <user@company.com>" \
  -H "Content-Type: application/json" \
  -d '{
    "package_id": 1123,
    "recipient": {
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "jane.doe@example.com",
      "phone": "+61400000000"
    },
    "additional_information": [
      {
        "code": "reference",
        "fields": {
          "internal_reference": "Senior Software Engineer"
        }
      }
    ]
  }'

  5. Monitor request status using webhook notifications, or poll GET /v1/requests/{request_id} until the request reaches a terminal status of COMPLETED, ERROR, or CANCELLED.

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