requests`¶

Creates a request for a recipient using a selected package.

Requests are accepted and processed asynchronously. A successful request returns 201 Created with a request_id that can be used to retrieve the request or correlate webhook events.

Request¶

POST /v1/requests HTTP/1.1
Host: api.xref.com
X-Xref-API-Key: <api-key>
X-Xref-User-Email: <user@yourcompany.com>
Content-Type: application/json

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.
`Content-Type`	Yes	`application/json`

Body¶

{
  "package_id": 1123,
  "recipient": {
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "jane.doe@example.com",
    "phone": "+61400000000"
  },
  "additional_information": [
    {
      "code": "reference",
      "fields": {
        "internal_reference": "Senior Software Engineer"
      }
    },
    {
      "code": "ncc_acic",
      "fields": {
        "police_check_state": "NSW"
      }
    }
  ]
}

Field	Type	Required	Description
`package_id`	integer	Yes	ID of an `ACTIVE` package returned by `GET /v1/packages`.
`recipient`	object	Yes	Recipient details required by the selected package.
`recipient.first_name`	string	Yes	Recipient first name.
`recipient.last_name`	string	Yes	Recipient last name.
`recipient.email`	string	Yes	Recipient email address.
`recipient.phone`	string	Yes	Recipient phone number in E.164 format, including the country calling code. Maximum 15 digits.
`additional_information`	array	No	Check-specific information required by the selected package. Fields and requirements are defined by `GET /v1/packages/{id}/schema`.
`additional_information[].code`	string	Yes	Check code returned in the package schema, such as `reference`, `ncc_acic`, or `icrc`. Each code can appear only once.
`additional_information[].fields`	object	Yes	Field values for the check, based on the selected package schema.

Retrieve GET /v1/packages/{id}/schema before creating a request to determine the fields available for the selected package and whether each field is required.

Response¶

201 Created

{
  "data": {
    "request_id": "9b2a14ee-9d0e-4d3a-aff2-7f68c19f3f3a",
    "status": "RECEIVED"
  },
  "status_message": "ok",
  "message": ""
}

Field	Type	Description
`data.request_id`	string (UUID)	Unique identifier for the request. Used with `GET /v1/requests/{id}` and to correlate webhook events.
`data.status`	string	Initial request status. A newly created request returns `RECEIVED` and progresses as its checks are processed. See Request lifecycle.

Example request¶

curl -s -X POST https://api.xref.com/v1/requests \
  -H "X-Xref-API-Key: $XREF_API_KEY" \
  -H "X-Xref-User-Email: $XREF_USER_EMAIL" \
  -H "Content-Type: application/json" \
  -d '{
    "package_id": 1123,
    "recipient": {
      "first_name": "Jane",
      "last_name":  "Doe",
      "email":      "jane.doe@example.com",
      "phone":      "+61400000000"
    },
    "additional_information": [
      {
        "code": "reference",
        "fields": { "internal_reference": "Senior Software Engineer" }
      },
      {
        "code": "ncc_acic",
        "fields": { "police_check_state": "NSW" }
      }
    ]
  }'

Errors¶

Status	`status_message`	When
`400`	`client_error`	The request contains invalid JSON, missing or invalid fields, an invalid phone number, duplicate `additional_information` codes, or missing required schema fields.
`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 the organisation cannot create requests due to insufficient credits, an expired trial, or an inactive subscription.
`404`	`client_error`	The package could not be found, is disabled, 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 or request processing failure occurred. See Idempotency and retries before retrying the request.

See Errors and status codes for more information.

Example `400` body¶

{
  "data": null,
  "status_message": "client_error",
  "message": "recipient.email: enter a valid email address"
}

Asynchronous processing¶

A 201 Created response confirms that the request has been accepted for processing. It does not indicate that the associated checks have started or completed.

The request initially has a status of RECEIVED and progresses as its associated checks are processed. Depending on the package and check outcomes, the request may transition through statuses including IN_PROGRESS and PARTIAL before reaching a terminal status of COMPLETED, ERROR, or CANCELLED.

Request progress can be monitored by:

Retrieving GET /v1/requests/{request_id}, or
Configuring a webhook to receive notifications when the request status changes. Webhooks are recommended where near real-time status updates are required.

Idempotency and retries¶

The API does not currently support an Idempotency-Key header. Retrying a POST /v1/requests request may therefore create a duplicate request.

For 429 responses, wait for the number of seconds specified in the Retry-After header before retrying.

For 4xx responses, resolve the validation or authentication error before retrying.

For 5xx responses, the outcome may be unknown. If a request_id was returned, retrieve the request using GET /v1/requests/{id} before attempting to create another request.

POST /v1/requests¶