GET /v1/packages/{id}/schema

Returns the input schema for a package, including the recipient and check-specific fields available when creating a request.

Each field includes a required property that indicates whether it must be included in the request. Use the schema to construct and validate request payloads rather than hard-coding field requirements.

Request

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

Path parameters

Name	Type	Description
id	integer	Package ID from GET /v1/packages (the id field).

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.

Response

200 OK

{
  "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": "NCC ACIC Police Check",
          "code": "ncc_acic",
          "fields": {
            "police_check_state": {
              "type": "string",
              "required": true,
              "description": "Australian state or territory."
            }
          }
        }
      ]
    }
  },
  "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_acic, 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.

Example request

curl -s https://api.xref.com/v1/packages/1123/schema \
  -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 Xref user is not an active member of the organisation, or does not have access to the package.
404	client_error	The package could not be found or is not available to the organisation and Xref user.
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

• The schema remains stable for the lifetime of a package version. If a new required field is introduced, a new package version is created with a new id.
• Retrieve the schema when configuring an integration to determine the fields required for a package.
• 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.