Skip to content

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

X-Xref-API-Key: <api-key>
X-Xref-User-Email: <user@yourcompany.com>

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.