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

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

Ищет пользователей на портале Битрикс24 по имени, фамилии или email — возвращает userId, имя, должность и фото для каждого совпадения. Используется для заполнения списка NAMED_USERS через `POST /access` — удобно, когда вы знаете имя человека, но не знаете его ID на портале. Работает через веб-хук-ключ из apiKey.webhookUrl; если у текущего API-ключа webhookUrl отсутствует (например, OAuth-ключ без связанного вебхука), эндпоинт вернёт пустой массив.

#Параметры

Параметр В Тип Обяз. Описание
id path string (UUID) да ID сервера
search query string да Строка поиска, минимум 2 символа. Ищет по имени, фамилии и email

#Примеры

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

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

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

Terminal 
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 — личный ключ

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-приложение

javascript 
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 boolean Всегда true при успехе
data array Массив найденных пользователей
data[].id string ID пользователя Битрикс24 — передавайте в userId при `POST /access`
data[].name string Полное имя (имя + фамилия)
data[].photo string | null URL аватарки (может быть null)
data[].position string | null Должность (может быть null)

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

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

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

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

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

#Ошибки

HTTP Код Описание
400 VALIDATION_ERROR search отсутствует или короче 2 символов
401 MISSING_API_KEY Не передан заголовок X-Api-Key
401 INVALID_API_KEY Неверный или просроченный API-ключ
404 NOT_FOUND Сервер не существует, удалён или принадлежит другому API-ключу
429 RATE_LIMIT_EXCEEDED Превышен общий лимит запросов платформы

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

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

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

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