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 employees in your Bitrix24 account with support for filtering 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). When limit > 50, Vibecode automatically requests several pages from Bitrix24
offset number 0 Skip N records. When offset > 0, limit ≤ 500 is recommended
order object — Sorting is silently ignored — the request returns the records in the same order as without the parameter. The same goes for the short form ?sort=-id. Order the result set on the client side
filter object — Filtering by the fields from GET /v1/users/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 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

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
429 RATE_LIMITED Rate limit exceeded: 300 requests per minute per portal, all API keys of the portal share one limit. The exact value arrives in the x-ratelimit-limit header (the cap is divided across replicas). Retry after the delay in the Retry-After header

Full list of common API errors — Errors.

Known specifics

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, PERSONAL_NOTES — in their original Bitrix24 names. UF fields of the Bitrix24 account 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