Get package schema
|
|
| Method |
GET |
| Path |
/v1/packages/{id}/schema |
Packages can include checks from multiple providers and each check may
require different input fields. This endpoint returns the required and
optional fields for the selected package so you can build a valid
POST /v1/requests payload for that package.
The response includes recipient and check-specific fields in
additional_information. Each field includes a required property that
indicates whether it must be included in the request.
Request
X-Xref-API-Key: <api-key>
X-Xref-User-Email: <user@yourcompany.com>
Parameters
| Name |
Example / default |
Required |
Type |
Description |
id |
1123 |
Yes |
integer |
Package ID from GET /v1/packages (the id field). |
Response
200 — application/json
{
"data": {
"id": 1123,
"fields": {
"recipient": {
"first_name": { "type": "string", "required": true },
"last_name": { "type": "string", "required": true },
"email": { "type": "string", "required": true },
"phone": { "type": "string", "required": true }
},
"additional_information": [
{
"display_name": "Reference Check",
"code": "reference",
"fields": {
"internal_reference": {
"type": "string",
"required": true,
"description": "Role or position title for the reference check."
}
}
},
{
"display_name": "Australian Criminal History Check",
"code": "ncc_police_check",
"fields": {
"reason": {
"type": "string",
"required": true,
"description": "Role or reason for the police check."
},
"place_work": {
"type": "string",
"required": true,
"description": "Hiring organisation or workplace name."
}
}
}
]
}
},
"status_message": "ok",
"message": ""
}
Response fields
| Field |
Type |
Description |
data.id |
integer |
Package ID. |
data.fields.recipient |
object |
Recipient fields required to create a request, including first name, last name, email, and phone. Phone numbers must use E.164 format. |
data.fields.additional_information |
array |
Check-specific field definitions for the package. Checks that do not require additional information are omitted. Returns an empty array when no additional information is required. |
data.fields.additional_information[].display_name |
string |
Display name of the check. |
data.fields.additional_information[].code |
string |
Check code used in POST /v1/requests, such as reference, ncc_police_check, or icrc. |
data.fields.additional_information[].fields |
object |
Fields available for the check. |
data.fields.additional_information[].fields.<field_name>.type |
string |
Expected data type: string, integer, number, boolean, array, or object. |
data.fields.additional_information[].fields.<field_name>.required |
boolean |
Indicates whether the field is required when creating a request. |
data.fields.additional_information[].fields.<field_name>.description |
string |
Additional information or guidance for the field, which can be displayed as help text in the integrating platform. |
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, or does not have package access for the package. |
404 |
client_error |
The package could not be found, is inactive, is disabled, or is not exposed to the API. |
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
- After a user selects a package from
GET /v1/packages,
call this endpoint to determine which fields to collect before
creating a request.
- Schema responses may be cached. If
POST /v1/requests
returns a 400 client_error for an unknown or missing field, retrieve the
schema again before retrying the request.