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 account ID. Works through the server's Bitrix24 credentials: the webhook key from apiKey.webhookUrl, or — when the server key is an OAuth app without a user token — an automatic fallback: first the linked application's personal key, then the server owner's own personal keys, newest to oldest, until one actually grants Bitrix24 access. If neither source yields credentials (the app is not authorized on the account, the key was revoked, or the managing key has no Bitrix24 access — for example, no webhook or required scope), the endpoint returns an empty data together with a hint field explaining why.

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

• Empty data with a hint field when no Bitrix24 credentials resolve. If the server key is an OAuth app without a user token, the platform first tries the linked application's personal key, then walks the server owner's own personal keys, newest to oldest. If none of them grants access (no application, keys revoked/expired, owner blocked, or no key has a webhook/the required scope), the endpoint returns data: [] and a hint string with the reason — instead of a mute empty array. The client can show the hint to the user or switch to an alternative tool.
• The search runs through the user.search method in the Bitrix24 account. That means matching follows 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. Logically it is needed for NAMED_USERS, but the endpoint does not restrict the call by mode.

See also

• Add user/department
• Access list
• Access policy