Search Bitrix24 users

GET /v1/infra/servers/:id/b24-users

Searches for active employees in the Bitrix24 account by first name, last name, or email — returns userId, name, position, and photo for each match. Inactive users and other user types are excluded. Used to populate the NAMED_USERS list via POST /access when a person's name is known but not their Bitrix24 user ID. The platform searches for employees with the server key. If that key has no Bitrix24 access or Bitrix24 refuses it for lack of permissions, the platform tries other keys of the same Bitrix24 account — the order is described in "Known specifics". If the list could not be fetched because the keys lack Bitrix24 access or the employee-directory permission, the endpoint returns an empty data array together with a hint field that names the cause.

Parameters

Examples

curl — personal key

curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://vibecode.bitrix24.com/v1/infra/servers/SERVER_ID/b24-users?search=John"

curl — OAuth application

curl -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  "https://vibecode.bitrix24.com/v1/infra/servers/SERVER_ID/b24-users?search=John"

JavaScript — personal key

const q = encodeURIComponent('John')
const res = await fetch(
  `https://vibecode.bitrix24.com/v1/infra/servers/${serverId}/b24-users?search=${q}`,
  { headers: { 'X-Api-Key': 'YOUR_API_KEY' } }
)
const { data: users } = await res.json()
users.forEach(u => console.log(`${u.id}: ${u.name} — ${u.position ?? 'no position'}`))

JavaScript — OAuth application

const res = await fetch(
  `https://vibecode.bitrix24.com/v1/infra/servers/${serverId}/b24-users?search=${q}`,
  {
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
    },
  }
)

Response fields

Response example

{
  "success": true,
  "data": [
    {
      "id": "243",
      "name": "Kate Smith",
      "photo": null,
      "position": null
    }
  ]
}

Error response example

400 — search string shorter than 2 characters:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "search query required (min 2 chars)"
  }
}

Errors

The full list of common API errors — Errors.

Known specifics

• Which keys the platform tries. First, the server key. If it has no Bitrix24 access or Bitrix24 refuses it for lack of permissions, the platform tries the linked application's personal key and, if there is none, the server owner's personal keys, newest to oldest. Last come the keys of active Bitrix24 account administrators that carry the employee-directory permission. If every key tried lacks either the directory permission or Bitrix24 access, the response is data: [] with a hint string. It tells these two cases apart. In the first, the keys lack directory permissions: grant the server or application key the user and department scopes, or ask a Bitrix24 account administrator to create a key with them. In the second, the keys have no Bitrix24 access at all: a personal key with Bitrix24 access and the directory permission is needed.
• The search runs through the user.search method in the Bitrix24 account. Matching therefore works the same way as in the Bitrix24 account UI — the same rules for first name/last name/email.
• Non-ASCII characters in the URL — via encodeURIComponent. In JS: encodeURIComponent('Müller'). In curl: ?search=M%C3%BCller.
• Independent of the server mode. The search works for any server — both BLACKHOLE and OPEN. It is meant for NAMED_USERS, but the endpoint does not restrict the call by mode.

See also

• Add user/department
• Access list
• Access policy