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¶
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.