Skip to content

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

Headers

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.