GET /v1/packages

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

Package availability is determined by the Xref user's role within the organisation.

Request

GET /v1/packages?status=active HTTP/1.1
Host: api.xref.com
X-Xref-API-Key: <api-key>
X-Xref-User-Email: <user@yourcompany.com>

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.

Query parameters

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

Response

200 OK

{
  "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": "Intl Criminal Record Check", "partner_name": "certn" },
            { "check_name": "Right to Work Check",  "partner_name": "certn" }
          ]
        }
      },
      {
        "id": 1124,
        "name": "Standard reference",
        "status": "ACTIVE",
        "details": {
          "reference_survey": {
            "id": 305,
            "name": "Standard Reference Check",
            "min_referees": 2
          },
          "background_checks": []
        }
      }
    ]
  },
  "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} when retrieving a package 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.

Example request

curl -s https://api.xref.com/v1/packages?status=active \
  -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 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

• v1 returns the full list — there is no pagination. Most organisations have fewer than 50 packages so this is not a practical concern; pagination is tracked for a future version.
• Inactive (INACTIVE) and disabled (DISABLED) packages are returned for inventory purposes only. Attempting to use a non-ACTIVE package in POST /v1/requests returns 400 client_error.