Skip to content

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

X-Xref-API-Key: <api-key>
X-Xref-User-Email: <user@yourcompany.com>

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 receives 403 for requests they did not create.
  • report_pdf_url is a short-lived signed URL. Retrieve the request again to obtain a new URL after the previous one expires.
  • references may be [] on an in-progress or completed check. Treat empty as "no referee details available right now", not as a terminal "no referees".