Поиск пользователей Битрикс24

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

Ищет активных сотрудников на портале Битрикс24 по имени, фамилии или email — возвращает userId, имя, должность и фото для каждого совпадения. Неактивные пользователи и пользователи других типов в результат не попадают. Используется для заполнения списка NAMED_USERS через POST /access, когда известно имя человека, но не его ID на портале. Работает через B24-креды сервера: веб-хук-ключ из apiKey.webhookUrl, а если ключ сервера — OAuth-приложение без пользовательского токена, применяется автоматический фоллбэк: сначала personal-ключ связанного приложения, затем личные ключи владельца сервера — от свежего к старому, до первого, который действительно даёт доступ к Битрикс24. Если ни один источник не даёт креды (приложение ещё не авторизовано на портале, ключ отозван или управляющий ключ не имеет доступа к Битрикс24 — например, нет webhook или нужного скоупа), эндпоинт возвращает пустой data вместе с полем hint, которое объясняет причину.

Параметры

Примеры

curl — личный ключ

curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://vibecode.bitrix24.tech/v1/infra/servers/SERVER_ID/b24-users?search=Иван"

curl — OAuth-приложение

curl -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  "https://vibecode.bitrix24.tech/v1/infra/servers/SERVER_ID/b24-users?search=Иван"

JavaScript — личный ключ

const q = encodeURIComponent('Иван')
const res = await fetch(
  `https://vibecode.bitrix24.tech/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 ?? 'без должности'}`))

JavaScript — OAuth-приложение

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

Поля ответа

Пример ответа

{
  "success": true,
  "data": [
    {
      "id": "243",
      "name": "Катя Иванова",
      "photo": null,
      "position": null
    }
  ]
}

Пример ответа при ошибке

400 — строка поиска короче 2 символов:

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

Ошибки

Полный список общих ошибок API — Ошибки.

Известные особенности

• Пустой data с полем hint, когда B24-кредов нет. Если ключ сервера — OAuth-приложение без пользовательского токена, платформа сначала пробует personal-ключ связанного приложения, а затем перебирает личные ключи владельца сервера от свежего к старому. Если доступа не даёт ни один (приложения нет, ключи отозваны/истекли, владелец заблокирован или ни у одного ключа нет webhook/нужного скоупа), эндпоинт возвращает data: [] и строку hint с причиной — вместо немого пустого массива. Клиент может отобразить hint пользователю или переключиться на альтернативный инструмент.
• Поиск выполняется через метод user.search на портале Битрикс24. То есть логика совпадения с UI портала — те же правила по имени/фамилии/email.
• Кириллица в URL — через encodeURIComponent. На JS: encodeURIComponent('Иван'). На curl: ?search=%D0%98%D0%B2%D0%B0%D0%BD.
• Не зависит от режима сервера. Поиск работает для любого сервера — и BLACKHOLE, и OPEN. Логически он нужен для NAMED_USERS, но эндпоинт не ограничивает вызов по mode.

Смотрите также

• Добавить пользователя/отдел
• Список доступа
• Политика доступа