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.

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 card URL of any employee from 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.

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. Full list — Employee fields.

Error response example

403 — no scope:

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

Errors

Full list of common API errors — 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_* 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" in datetime fields in the entity overview (item 7).

See also

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