Skip to content

Create request

Method POST
Path /v1/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.

Retrieve GET /v1/packages/{id}/schema before creating a request to determine the provider-specific fields required for the selected package.

Request

Headers

X-Xref-API-Key: <api-key>
X-Xref-User-Email: <user@yourcompany.com>
Content-Type: application/json

Attributes

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

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 Product Manager"
      }
    },
    {
      "code": "ncc_police_check",
      "fields": {
        "reason": "Senior Product Manager",
        "place_work": "Acme Technologies"
      }
    }
  ]
}

Response

201 — application/json

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

400 — application/json

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

Response fields

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.

Errors

Status status_message Description
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, does not have package access for the package, 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 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 or request processing failure occurred. See Idempotency and retries before retrying the request.

See Errors and status codes for more information.

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 IN_PROGRESS and PARTIAL before reaching COMPLETED.

If further activity occurs on the same request — for example, a completed reference check is replaced with a new one — the overall request status may return to PARTIAL until all associated checks are complete and the request returns to COMPLETED.

ERROR and CANCELLED are terminal statuses. Once reached, the overall request status does not change.

The progress of a request 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.