Search employees

POST /v1/users/search

Search employees with filters in the request body and auto-pagination. Similar to GET /v1/users, but via POST — more convenient for complex requests and large arrays of filter values.

Request fields (body)

UF_* fields keep their passthrough behavior only for one Bitrix24 page: limit ≤ 50, offset = 0, and no automatic date-window splitting. Vibecode forwards such a field as-is but does not guarantee that a particular Bitrix24 account applies the order. With limit > 50, offset > 0, or automatic date-window splitting, 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. Combining offset > 0 with automatic date-window splitting still returns UNSTABLE_OFFSET_PAGINATION without a successful response.

Examples

curl — personal key

curl -X POST "https://vibecode.bitrix24.com/v1/users/search" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "active": true },
    "limit": 10
  }'

curl — OAuth application

curl -X POST "https://vibecode.bitrix24.com/v1/users/search" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "active": true },
    "limit": 10
  }'

JavaScript — personal key

const res = await fetch('https://vibecode.bitrix24.com/v1/users/search', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: { active: true },
    limit: 10,
  }),
})

const { success, data } = await res.json()
console.log('Found:', data.length)

JavaScript — OAuth application

const res = await fetch('https://vibecode.bitrix24.com/v1/users/search', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: { active: true },
    limit: 10,
  }),
})

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

Response fields

The meta fields sit next to data, not inside it. Paginate using meta.hasMore: a data length equal to limit does not rule out the last page.

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 account domain. Access is restricted by the employee's permissions in Bitrix24.

Response example

{
  "success": true,
  "data": [
    {
      "id": 1,
      "active": true,
      "name": "Maria",
      "lastName": null,
      "email": "maria@example.com",
      "departmentId": [1, 107, 47]
    },
    {
      "id": 29,
      "active": true,
      "name": "John",
      "lastName": "Brown",
      "email": "john.brown@example.com",
      "departmentId": [1]
    }
  ],
  "meta": {
    "total": 59,
    "hasMore": true,
    "durationMs": 186
  }
}

With a date-range filter wider than 14 days, meta additionally returns autoWindowed, windowCount, and batchWaves:

{
  "success": true,
  "data": [],
  "meta": {
    "total": 0,
    "hasMore": false,
    "autoWindowed": true,
    "windowCount": 131,
    "batchWaves": 3,
    "durationMs": 1189
  }
}

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 and time-window splitting. 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, offset, or windowed 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 date-range filter wider than 14 days is automatically split into weekly windows executed in parallel waves, so the result set bypasses the ceiling of 5000 records per call. meta then returns autoWindowed: true, the number of windows windowCount, and the number of waves batchWaves. The autoWindow: false parameter disables splitting. While splitting is active, an offset greater than zero is rejected with UNSTABLE_OFFSET_PAGINATION. Ascending id order is applied inside each window, but the merged result stays chronological and is not globally re-sorted. A Bitrix24 error remains an error response.

Semantics of filter[active]: false. Returns all employees, not only deactivated ones — Bitrix24 interprets ACTIVE = "Y" as "exclude deactivated" and other values as "no filter by status". To get only deactivated ones, filter the result on the client side by the active field.

When to use search instead of list. POST-search is more convenient for long lists of filter values ({ "id": [1, 5, 12, 27, 99] }) — a GET request's query string has length limits, while the POST body does not. For short filters both forms are equivalent.

See also

• List employees
• Employee fields
• Filtering syntax
• Batch
• Limits and optimization