{request_id}`¶

Returns the current status of a request, including the overall request status and the status of each associated reference and background check.

Request¶

GET /v1/requests/9b2a14ee-9d0e-4d3a-aff2-7f68c19f3f3a HTTP/1.1
Host: api.xref.com
X-Xref-API-Key: <api-key>
X-Xref-User-Email: <user@yourcompany.com>

Path parameters¶

Name	Type	Description
`request_id`	string (UUID)	The `request_id` returned by `POST /v1/requests`.

Headers¶

Header	Required	Description
`X-Xref-API-Key`	Yes	API key associated with the organisation.
`X-Xref-User-Email`	Yes	Email address of the Xref user the request is made on behalf of.

Response¶

200 OK

{
  "data": {
    "request_id": "9b2a14ee-9d0e-4d3a-aff2-7f68c19f3f3a",
    "package_id": 1123,
    "status": "IN_PROGRESS",
    "created_at": "2026-05-06T01:23:45+00:00",
    "requester": { "email": "jane.smith@yourcompany.com" },
    "recipient": {
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "jane.doe@example.com",
      "phone": "+61400000000"
    },
    "checks": [
      {
        "id": "5f0c2d8e-0000-0000-0000-000000000000",
        "type": "reference",
        "status": "IN_PROGRESS",
        "references": [
          {
            "referee_id": "1234567",
            "referee_name": "Bob Manager",
            "referee_email": "bob@example.com",
            "status": "COMPLETED",
            "report_pdf_url": "https://api.xref.com/v1/reports/5f0c2d8e-0000-0000-0000-000000000000/referees/1234567?t=token_value"
          },
          {
            "referee_id": "1234568",
            "referee_name": "Alice Director",
            "referee_email": "alice@example.com",
            "status": "IN_PROGRESS",
            "report_pdf_url": null
          }
        ]
      },
      {
        "id": "a91b34c2-0000-0000-0000-000000000000",
        "type": "background",
        "status": "COMPLETED",
        "partner_name": "Certn",
        "check_name": "Employment Verification",
        "report_pdf_url": "https://api.xref.com/v1/reports/a91b34c2-0000-0000-0000-000000000000?t=token_value"
      }
    ]
  },
  "status_message": "ok",
  "message": ""
}

Response fields¶

Field	Type	Description
`data.request_id`	string (UUID)	Unique identifier for the request.
`data.package_id`	integer	ID of the package used to create the request.
`data.status`	string	Overall request status. See Request lifecycle.
`data.created_at`	string (ISO 8601)	Timestamp when the request was accepted.
`data.requester.email`	string	Email address of the Xref user associated with the request.
`data.recipient`	object	Recipient details, including first name, last name, email address, and phone number.
`data.checks`	array	Reference and background checks associated with the request.
`data.checks[].id`	string (UUID) \| null	Unique identifier for the check. `null` until the check has been created.
`data.checks[].type`	string	Check type: `reference` or `background`.
`data.checks[].status`	string	Current check status: `RECEIVED`, `IN_PROGRESS`, `COMPLETED`, `CANCELLED`, or `ERROR`.
`data.checks[].partner_name`	string \| null	Background checks only. Name of the provider completing the check.
`data.checks[].check_name`	string \| null	Background checks only. Display name of the check.
`data.checks[].report_pdf_url`	string \| null	Background checks only. Signed URL for the completed PDF report. The URL includes a token valid for 1 hour and is `null` until the report is available.
`data.checks[].references`	array	Reference checks only. Referees associated with the reference check. Returns an empty array if no referees have been nominated.
`data.checks[].references[].referee_id`	string	Unique identifier for the referee.
`data.checks[].references[].referee_name`	string \| null	Referee name.
`data.checks[].references[].referee_email`	string \| null	Referee email address.
`data.checks[].references[].status`	string	Current referee status: `IN_PROGRESS`, `COMPLETED`, or `CANCELLED`.
`data.checks[].references[].report_pdf_url`	string \| null	Signed URL for the individual referee report. The URL includes a token valid for 1 hour and is `null` until the report is available.

Request lifecycle¶

The overall request status progresses through the following states:

Status	Meaning
`RECEIVED`	Initial status. The request has been accepted, but associated checks have not yet started.
`IN_PROGRESS`	At least one associated check is in progress and no checks have completed.
`PARTIAL`	At least one associated check has completed while others are still in progress.
`COMPLETED`	Terminal. All associated checks have finished and at least one completed successfully.
`ERROR`	Terminal. The request could not be processed and no associated checks were created.
`CANCELLED`	Terminal. All associated checks have finished without any reaching `COMPLETED`, such as when checks are expired, declined, deleted, or stopped.

A request may transition from IN_PROGRESS to PARTIAL, COMPLETED, ERROR, or CANCELLED. Terminal statuses do not transition further.

When the overall request status changes, Xref sends a request.updated webhook notification. This can be used instead of polling for status changes.

Example request¶

curl -s https://api.xref.com/v1/requests/9b2a14ee-9d0e-4d3a-aff2-7f68c19f3f3a \
  -H "X-Xref-API-Key: $XREF_API_KEY" \
  -H "X-Xref-User-Email: $XREF_USER_EMAIL"

Errors¶

Status	`status_message`	When
`401`	`client_error`	Required authentication headers are missing or invalid.
`403`	`client_error`	The Xref user is not an active member of the organisation associated with the API key.
`404`	`client_error`	The request could not be found or is not available to the organisation.
`429`	`client_error`	API key rate limit exceeded. The response includes a `Retry-After` header.
`5xx`	`server_error`	An internal server error occurred.

See Errors and status codes for more information.

Notes¶

This endpoint is read-only and idempotent.
Webhooks are recommended for monitoring status changes. Polling can be used where webhook delivery is not available.
report_pdf_url is a short-lived signed URL. Retrieve the request again to obtain a new URL after the previous one expires.

GET /v1/requests/{request_id}¶