Retrieve request¶
| Method | GET |
| Path | /v1/requests/{request_id} |
Returns the current status of a request and the checks associated with it.
The response includes the overall request status, recipient and requester
details, and an entry in checks for each reference and background check in
the package. For reference checks, references lists each nominated referee
with their name, email, and individual status.
When a report is available, report_pdf_url is returned on the background
check or on each referee entry. These are pre-signed URLs that can be used
to download the PDF report directly. URLs are valid for one hour. Download
and store the PDF locally if you need a permanent copy. Otherwise, retrieve
the request again to obtain a new report_pdf_url after the previous URL
expires.
For some background checks, report_pdf_url may be available while the
check is still IN_PROGRESS. The PDF can be updated as further results are
received — for example, an International Criminal History Check covering
multiple countries may include a PDF after the first country result is
available. Retrieve the request again when the check status is COMPLETED,
then download and store the final report locally.
Request¶
Headers¶
Parameters¶
| Name | Example / default | Required | Type | Description |
|---|---|---|---|---|
request_id |
9b2a14ee-9d0e-4d3a-aff2-7f68c19f3f3a | Yes | string |
The request_id returned by POST /v1/requests. |
Response¶
200 — application/json¶
{
"data": {
"request_id": "9b2a14ee-9d0e-4d3a-aff2-7f68c19f3f3a",
"package_id": 1123,
"status": "PARTIAL",
"last_completed_at": "2026-05-07T04:55:00+00:00",
"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": "ncc",
"check_name": "Australian Criminal History Check",
"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.last_completed_at |
string (ISO 8601) | null | When the request last reached COMPLETED. null if it never has. Unchanged while the request is PARTIAL after it has left COMPLETED. Updated when the request reaches COMPLETED again. |
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 | null | Recipient details, including first name, last name, email address, and phone number. null while data.status is RECEIVED. |
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. See Background check lifecycle or Reference check lifecycle, depending on type. |
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 | Reference checks only. Unique identifier for the referee. |
data.checks[].references[].referee_name |
string | null | Reference checks only. Referee name. |
data.checks[].references[].referee_email |
string | null | Reference checks only. Referee email address. |
data.checks[].references[].status |
string | Reference checks only. Current referee status: IN_PROGRESS, COMPLETED, DECLINED, UNOBTAINABLE, or CANCELLED. |
data.checks[].references[].report_pdf_url |
string | null | Reference checks only. 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 (data.status) progresses through the following states:
| Status | Description |
|---|---|
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 |
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 declined, deleted, or stopped. |
A request may transition from IN_PROGRESS to PARTIAL, COMPLETED,
ERROR, or CANCELLED. ERROR and CANCELLED do not transition further.
COMPLETED may return to PARTIAL, and may be reached again for the same request.
When the overall request status changes, Xref sends a
request.updated webhook notification.
This can be used instead of polling for status changes.
Background check lifecycle¶
data.checks[].status when type is background:
| Status | Description |
|---|---|
RECEIVED |
Check accepted but not yet started with the provider. |
SENT |
Check has been created by the provider. |
IN_PROGRESS |
Check is being processed by the recipient or the provider. |
COMPLETED |
Check finished successfully. |
FAILED |
Terminal. Check failed during processing. |
CANCELLED |
Terminal. Check was cancelled. |
DECLINED |
Terminal. Check was declined by the recipient or the provider. |
EXPIRED |
Terminal. Check expired before completion. |
Reference check lifecycle¶
data.checks[].status when type is reference:
| Status | Description |
|---|---|
RECEIVED |
Check accepted but not yet started. Returned when no linked check exists yet. |
REQUESTED |
Reference check has been created and delivered to the recipient. |
IN_PROGRESS |
At least one referee has been nominated and the check is underway. |
COMPLETED |
Reference check completed successfully. May return to IN_PROGRESS if a referee is replaced, then back to COMPLETED when the replacement finishes. |
EXPIRED |
Reference check expired before completion. |
STOPPED |
Terminal. Reference check was stopped. |
DELETED |
Terminal. Reference check was deleted. |
Referee lifecycle¶
data.checks[].references[].status on reference checks:
| Status | Description |
|---|---|
IN_PROGRESS |
Referee has been nominated but has not yet completed their reference. |
DECLINED |
Referee declined the reference request. |
UNOBTAINABLE |
Reference could not be obtained from this referee. |
COMPLETED |
Terminal. Referee has completed their reference. |
CANCELLED |
Terminal. Referee request was stopped or detached. |
Errors¶
| Status | status_message |
Description |
|---|---|---|
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, the user cannot access the request's package, or is a Contributor and did not create the request. |
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.
GET /v1/requests/{id}still requires an email that can read that request. For example, a Contributor polling with their own email receives403for requests they did not create. report_pdf_urlis a short-lived signed URL. Retrieve the request again to obtain a new URL after the previous one expires.referencesmay be[]on an in-progress or completed check. Treat empty as "no referee details available right now", not as a terminal "no referees".