For AI agents: markdown of this page — /docs-content-en/entities/users/list.md documentation index — /llms.txt

List employees

GET /v1/users

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

Parameters

Parameter Type Default Description
limit number 50 Number of records (up to 5000). With limit > 50 Vibecode automatically requests several pages from Bitrix24
offset number 0 Skip N records. With offset > 0, limit ≤ 500 is recommended
order object — Sorting by any record field. Example: ?order[name]=asc
filter object — Filtering by GET /v1/users/fields fields.
Filtering syntax. Example: ?filter[name]=John

Examples

curl — personal key

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

curl — OAuth application

Terminal 
curl "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

javascript 
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

javascript 
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

Field Type Description
success boolean Always true on success
data array Array of employees. Each element contains all fields — see Employee fields
meta.total number Total number of records matching the filter
meta.hasMore boolean Whether there are more records beyond limit

The card URL of any employee from the data array is its id:

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

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

Response example

JSON 
{
  "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:

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

Errors

HTTP Code Description
400 INVALID_FILTER_FIELD Filter by a nonexistent field — the field list is in GET /v1/users/fields
401 TOKEN_MISSING The API key has no configured tokens
403 SCOPE_DENIED The API key lacks the user scope

Full list of common API errors — Errors.

Known specifics

Semantics of filter[active]. active: true excludes deactivated ones. active: false is not interpreted by Bitrix24 as "deactivated only" — all are returned. To get only deactivated ones, sift 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, PERSONAL_NOTES — in their original Bitrix24 names. Bitrix24 account UF fields also keep their names. Standard fields (name, email, active, timeZone, userType, departmentId, etc.) — 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