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¶

GET /v1/users HTTP/1.1
Host: api.xref.com
X-Xref-API-Key: <api-key>
X-Xref-User-Email: <user@yourcompany.com>

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.

Query parameters¶

None in v1.

Response¶

200 OK

{
  "data": {
    "users": [
      {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "first_name": "Sam",
        "last_name": "Taylor",
        "email": "sam.taylor@example.com",
        "role": "member",
        "permissions": [
          "bgc.contributor",
          "exit.none",
          "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>

For example:

reference.requestor bgc.administrator integration.none

Product (`UserRole.roles.products` key)	`<product>`
`References`	`reference`
`Exits`	`exit`
`Background Checks`	`bgc`
`Pulses`	`pulse`
`Integrations`	`integration`

Product level	`<level>`
`0`	`none`
`2`	`administrator`
`3`	`requestor`
`4`	`contributor`
`5`	`analyst`

Level 1 (Integration User) is not returned in the permissions field. Permissions are returned in alphabetical order.

Example request¶

curl -s https://api.xref.com/v1/users \
  -H "X-Xref-API-Key: $XREF_API_KEY" \
  -H "X-Xref-User-Email: $XREF_USER_EMAIL"

Errors¶

Status	`status_message`	When
`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.

GET /v1/users¶