Skip to content

List packages

Method GET
Path /v1/packages

Returns the packages available to the organisation and Xref user associated with the request. Each package defines the reference and/or background checks that will be included in a request.

Package availability is determined by the Xref user's role and survey permissions within the organisation. See package access for more information.

Request

Headers

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

Parameters

Name Example / default Required Type Description
status active No string Filters packages by status. Supported values are active, inactive, and disabled.
id "" No integer Filters the response by package ID.

Response

200 — application/json

{
  "data": {
    "packages": [
      {
        "id": 1123,
        "name": "Pre-employment full check",
        "status": "ACTIVE",
        "details": {
          "reference_survey": {
            "id": 412,
            "name": "Standard Reference Check",
            "min_referees": 2
          },
          "background_checks": [
            {
              "check_name": "Australian Criminal History Check",
              "partner_name": "ncc"
            }
          ]
        }
      },
      {
        "id": 1124,
        "name": "International screening",
        "status": "ACTIVE",
        "details": {
          "reference_survey": {
            "id": 305,
            "name": "Standard Reference Check",
            "min_referees": 2
          },
          "background_checks": [
            {
              "check_name": "International Criminal Record Check",
              "partner_name": "certn"
            },
            {
              "check_name": "AML (Global Lists)",
              "partner_name": "rapidid"
            }
          ]
        }
      }
    ]
  },
  "status_message": "ok",
  "message": ""
}

Response fields

Field Type Description
data.packages array Packages available to the organisation and Xref user.
data.packages[].id integer Unique package ID. Used as package_id when creating a request and as {id} in GET /v1/packages/{id}/schema.
data.packages[].name string Package name displayed in Xref.
data.packages[].status string Package status: ACTIVE, INACTIVE, or DISABLED. Only ACTIVE packages can be used to create new requests.
data.packages[].details.reference_survey object | null Reference check configuration for the package, or null if no reference check is included.
data.packages[].details.reference_survey.id integer Reference survey ID.
data.packages[].details.reference_survey.name string | null Reference survey name.
data.packages[].details.reference_survey.min_referees integer Minimum number of references required.
data.packages[].details.background_checks array Background checks included in the package.
data.packages[].details.background_checks[].check_name string | null Name of the background check.
data.packages[].details.background_checks[].partner_name string | null Name of the Trust Marketplace partner providing the background check.

Errors

Status status_message Description
401 client_error Required authentication headers are missing or invalid.
403 client_error The user email does not match an active Xref user in the organisation associated with the API key.
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

  • INACTIVE and DISABLED packages are returned for inventory purposes only. Creating a request with one returns 404 with Package not found or unavailable.