List users¶
| Method | GET |
| Path | /v1/users |
Lists Xref users within the organisation, including each user's role, team, and product permissions where applicable.
Use this endpoint to identify users that can be supplied as
X-Xref-User-Email in other Xref API requests.
Request¶
Headers¶
Response¶
200 — application/json¶
{
"data": {
"users": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"first_name": "Sam",
"last_name": "Taylor",
"email": "sam.taylor@example.com",
"role": "member",
"permissions": [
"bgc.contributor",
"pulse.contributor",
"reference.administrator"
],
"teams": [
{
"id": "9e2e0f4a-1234-5678-9abc-def012345678",
"name": "Talent Acquisition - APAC"
}
],
"job_title": "Senior Recruiter"
},
{
"id": "a1b2c3d4-1111-2222-3333-444455556666",
"first_name": "Alex",
"last_name": "Morgan",
"email": "alex.morgan@example.com",
"role": "owner",
"teams": [
{
"id": "9e2e0f4a-1234-5678-9abc-def012345678",
"name": "Talent Acquisition - APAC"
}
],
"job_title": "Head of People & Culture"
}
]
},
"status_message": "ok",
"message": ""
}
Response fields¶
| Field | Type | Description |
|---|---|---|
data.users |
array | Active Xref users associated with the organisation. |
data.users[].id |
string (UUID) | Unique identifier for the Xref user. |
data.users[].first_name |
string | User first name. |
data.users[].last_name |
string | User last name. |
data.users[].email |
string | Primary verified email address for the user. |
data.users[].role |
string | Assigned Xref role, such as owner, support, or member. |
data.users[].permissions |
array of strings | Only present when role = member. Per-product permissions in the format <product>.<level> (see below). Omitted for non-member roles. |
data.users[].teams |
array | Teams the user is currently assigned to. Each entry includes the team id and name. |
data.users[].job_title |
string | Job title associated with the user. Returns an empty string when not set. |
permissions format (Member role only)¶
The permissions field is returned for users with the member role. Each permission uses the format: <product>.<level>
Possible levels: administrator, requestor, contributor, analyst.
For example:
reference.requestor
bgc.administrator
pulse.contributor
| Product | <product> |
|---|---|
Reference |
reference |
Background check |
bgc |
Exit |
exit |
Pulse |
pulse |
Integration |
integration |
Integration User permissions are not returned in the permissions field.
Permissions are returned in alphabetical order.
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 associated with the API key. |
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 endpoint returns the full list of users and does not support pagination.
- Only users associated with the organisation identified by the API key are returned.
- Users associated with multiple organisations are scoped to the organisation identified by the API key.
- Inactive users and inactive teams are excluded from the response.