List employees

GET /v1/users

Returns the list of employees in your Bitrix24 account with support for filtering, sorting, and auto-pagination. The method does not return bots, mail users, or Open Channels users.

Besides the user scope, the method requires a Bitrix24 plan that includes Vibecode. On a Bitrix24 account without such a plan, the call returns 422 BITRIX_ERROR with error.b24Code set to FEATURE_NOT_AVAILABLE_ON_CURRENT_PLAN, and retrying the request does not help. You can check the account's plan before the call: it is returned in the data.tariff field of GET /v1/me.

Parameters

UF_* fields keep their passthrough behavior only for one page of results from Bitrix24: limit ≤ 50 and offset = 0. Vibecode forwards such a field as-is but does not guarantee that a particular Bitrix24 account applies the order. With limit > 50 or offset > 0, Vibecode replaces a UF_* sort with ascending id order and adds one SORT_FALLBACK_TO_ID warning for the sort field to meta.warnings. The same warning is returned for multiple recognized sort fields.

Examples

curl — personal key

curl -g "https://vibecode.bitrix24.com/v1/users?limit=10&filter[active]=true" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

curl -g "https://vibecode.bitrix24.com/v1/users?limit=10&filter[active]=true" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

const res = await fetch('https://vibecode.bitrix24.com/v1/users?limit=10&filter[active]=true', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data, meta } = await res.json()
console.log(`Found ${meta.total} employees`)

JavaScript — OAuth application

const res = await fetch('https://vibecode.bitrix24.com/v1/users?limit=10&filter[active]=true', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { success, data, meta } = await res.json()

Response fields

The profile URL of any employee in the data array is built from their id:

https://<portal>.bitrix24.com/company/personal/user/<id>/

<portal> — the Bitrix24 portal domain. Access is restricted by the employee's permissions in Bitrix24.

Related data

To retrieve the employees' departments together with the list, use the include parameter in the GET request:

GET /v1/users?limit=2&include=department

Available include: department. The result is in the _included.departments field of each element of the data array: the departments from the employee's departmentId that GET /v1/departments returns. A department from departmentId that this list does not contain is left out of the array:

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Maria",
      "departmentId": [1, 107],
      "_included": {
        "departments": [
          { "id": 107, "name": "Sales", "sort": 800, "parentId": 1, "headId": 1 }
        ]
      }
    },
    {
      "id": 29,
      "name": "John",
      "departmentId": [],
      "_included": {
        "departments": []
      }
    }
  ],
  "meta": {
    "total": 64,
    "hasMore": true
  }
}

For more on includes, including the limit on selection size, see Related data.

Response example

{
  "success": true,
  "data": [
    {
      "id": 1,
      "xmlId": "28889266",
      "active": true,
      "name": "Maria",
      "lastName": null,
      "secondName": "Middle name",
      "email": "maria@example.com",
      "lastLogin": "2026-05-05T08:25:11.000Z",
      "dateRegister": "2020-04-20T00:00:00.000Z",
      "timeZone": "UTC",
      "isOnline": false,
      "timestampX": {},
      "lastActivityDate": {},
      "personalGender": "F",
      "personalPhoto": "https://cdn.bitrix24.com/.../photo.jpg",
      "personalMobile": "+12025550123",
      "workPosition": null,
      "departmentId": [1, 107, 47],
      "userType": "employee"
    },
    {
      "id": 29,
      "xmlId": "28936832",
      "active": true,
      "name": "John",
      "lastName": "Brown",
      "email": "john.brown@example.com",
      "departmentId": [1],
      "userType": "employee"
    }
  ],
  "meta": {
    "total": 30,
    "hasMore": true
  }
}

The main fields are shown. For the full list, see Employee fields.

Error response example

403 — no scope:

{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "This endpoint requires 'user' scope"
  }
}

Errors

For the full list of common API errors, see Errors.

Known specifics

Sorting. Vibecode guarantees employee order only by id. The id and -id values preserve the requested direction and add no warning. A single-page UF_* sort keeps its passthrough behavior for backward compatibility. With multiple recognized fields or a multi-page UF_* sort, the request succeeds with ascending id order and one SORT_FALLBACK_TO_ID warning. A single ordinary field other than id still returns UNKNOWN_SORT_FIELD. A Bitrix24 error remains an error response.

Semantics of filter[active]. active: true excludes deactivated employees. Bitrix24 does not interpret active: false as "deactivated only" — it returns all employees. To get only deactivated ones, filter the result on the client side by the active field.

WORK_* fields and some PERSONAL_* fields arrive in UPPER_SNAKE_CASE. WORK_COMPANY, WORK_DEPARTMENT, WORK_WWW, WORK_FAX, WORK_CITY, WORK_STATE, WORK_ZIP, WORK_COUNTRY, and the like. PERSONAL_STATE, PERSONAL_ZIP, PERSONAL_COUNTRY, PERSONAL_MAILBOX, and PERSONAL_NOTES arrive with their original Bitrix24 names. UF fields of the Bitrix24 account also keep their names. Standard fields (name, email, active, timeZone, userType, departmentId, etc.) use camelCase.

The lastActivityDate field (declared datetime). In practice it arrives as an empty object {}, or the key is absent altogether — an ISO string for this field has not been observed in checks. {} is a truthy value in JS, so if (u.lastActivityDate) gives a false positive. Same for timestampX (always {}). Do not parse it as a date and do not rely on a truthy check. Compare the type (typeof x === 'string'). See the summary of "empty" values in datetime fields in the entity overview (item 7).

See also

• Get employee
• Search employees
• Employee fields
• Filtering syntax
• Entity API
• Limits and optimization