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
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.