#Search Bitrix24 users

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

Searches for users in the Bitrix24 account by first name, last name, or email — returns userId, name, position, and photo for each match. 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 to the linked application's personal key. If neither source yields credentials (the app is not yet authorized on the account, or the key was revoked), 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 (fallback). If that is also unavailable (no application, key revoked/expired, or owner blocked), 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 — add a found user to the access list.
• Access list — see the users and departments already added.
• Access policy — switch to NAMED_USERS.