Пригласить пользователя user.add

Выберите инструмент для разработки с AI-агентом:

  • используйте Битрикс24 Вайбкод, чтобы создать приложение для Битрикс24 по описанию задачи без знания языков программирования. Агент напишет код и разместит приложение на сервере без ручной настройки хостинга
  • используйте MCP-сервер, чтобы разрабатывать интеграцию через REST API в своем проекте. Агент будет обращаться к официальной REST-документации

Scope: user

Кто может выполнять метод: администратор, а в облачном Битрикс24 — также пользователь с правом приглашать сотрудников

Метод user.add приглашает пользователя в Битрикс24 и отправляет приглашение на EMAIL. Сотруднику нужно передать подразделение в UF_DEPARTMENT, внешнему пользователю экстранета — EXTRANET и SONET_GROUP_ID.

Метод работает только в версии скоупа user. В версиях user_brief и user_basic вызов вернет ошибку insufficient_scope — подробнее в статье Версии скоупа user. Событие onUserAdd придет не сразу, а когда приглашенный пользователь впервые войдет в Битрикс24 и завершит регистрацию.

Параметры метода

Обязательные параметры отмечены *

Название
тип

Описание

EMAIL*
string

E-mail пользователя. На него придет приглашение. Адрес должен пройти проверку Битрикс24.Network

NAME
string

Имя

LAST_NAME
string

Фамилия

SECOND_NAME
string

Отчество

PERSONAL_GENDER
string

Пол:

  • M — мужской
  • F — женский

PERSONAL_PROFESSION
string

Профессия

PERSONAL_WWW
string

Личный сайт

PERSONAL_BIRTHDAY
date

Дата рождения в формате ISO 8601, например 1990-05-20

PERSONAL_PHOTO
array

Фотография — массив из двух строк: имени файла и содержимого в Base64, например ["photo.png", "iVBORw0KGgo..."]

PERSONAL_ICQ
string

ICQ

PERSONAL_PHONE
string

Личный телефон

PERSONAL_FAX
string

Личный факс

PERSONAL_MOBILE
string

Личный мобильный

PERSONAL_PAGER
string

Пейджер

PERSONAL_STREET
string

Улица проживания

PERSONAL_CITY
string

Город проживания

PERSONAL_STATE
string

Область или край проживания

PERSONAL_ZIP
string

Почтовый индекс

PERSONAL_COUNTRY
string

Числовой код страны проживания из справочника стран Битрикс24. Код уже заданной страны возвращает поле PERSONAL_COUNTRY в ответе user.get

PERSONAL_MAILBOX
string

Почтовый ящик

PERSONAL_NOTES
string

Дополнительные заметки

WORK_PHONE
string

Рабочий телефон

WORK_COMPANY
string

Компания

WORK_POSITION
string

Должность

WORK_DEPARTMENT
string

Отдел — текстовое поле. Подразделение из структуры компании передавайте в UF_DEPARTMENT

WORK_WWW
string

Сайт компании

WORK_FAX
string

Рабочий факс

WORK_PAGER
string

Рабочий пейджер

WORK_STREET
string

Улица места работы

WORK_MAILBOX
string

Рабочий почтовый ящик

WORK_CITY
string

Город работы

WORK_STATE
string

Область или край места работы

WORK_ZIP
string

Почтовый индекс места работы

WORK_COUNTRY
string

Числовой код страны места работы из справочника стран Битрикс24. Код уже заданной страны возвращает поле WORK_COUNTRY в ответе user.get

WORK_PROFILE
string

Направление деятельности компании

WORK_LOGO
array

Логотип компании. Передавайте массив из имени файла и строки в Base64, как для PERSONAL_PHOTO

WORK_NOTES
string

Заметки о месте работы

UF_SKYPE_LINK
string

Ссылка на чат в Skype

UF_ZOOM
string

Zoom

UF_DEPARTMENT
integer[]

Идентификаторы подразделений из структуры компании. Получить подразделения можно методом department.get.

Обязателен для сотрудника, если не передан EXTRANET = Y. Без него метод вернет ошибку no_extranet_field

UF_INTERESTS
string

Интересы

UF_SKILLS
string

Навыки

UF_WEB_SITES
string

Другие сайты

UF_XING
string

Xing

UF_LINKEDIN
string

LinkedIn

UF_FACEBOOK
string

Facebook**

UF_TWITTER
string

Twitter

UF_SKYPE
string

Microsoft Teams. Код поля сохранился от Skype

UF_DISTRICT
string

Район

UF_PHONE_INNER
string

Внутренний телефон

EXTRANET
string

Пригласить внешнего пользователя экстранета:

  • Y — пригласить в экстранет

Другое значение или отсутствие параметра — приглашение сотрудника, для которого нужен UF_DEPARTMENT. Вместе с EXTRANET = Y обязательно передайте SONET_GROUP_ID. Значение UF_DEPARTMENT в этом случае не учитывается. Работает, если в Битрикс24 установлен модуль экстранета

SONET_GROUP_ID
integer[]

Идентификаторы рабочих групп, в которые приглашается пользователь экстранета. Можно передать одно число. Получить группы можно методом sonet_group.get.

Обязателен, если передан EXTRANET = Y. Без него метод вернет ошибку no_sonet_group_for_extranet

MESSAGE_TEXT
string

Текст приглашения. Если не передан, используется стандартный текст


*Принадлежит компании Meta Platforms, Inc., которая признана экстремистской и запрещена на территории Российской Федерации.

Примеры кода

Как использовать примеры в документации

Пригласить сотрудника

curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
    "EMAIL": "newuser1@example.com",
    "UF_DEPARTMENT": [1]
}' \
https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/user.add
curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
    "EMAIL": "newuser1@example.com",
    "UF_DEPARTMENT": [1],
    "auth": "**put_access_token_here**"
}' \
https://**put_your_bitrix24_address**/rest/user.add
// This snippet is an ES module: top-level await requires type="module" or a bundler.
// $b24 is an already-initialized SDK instance (see the SDK "Get started" guide).
import { Text } from '@bitrix24/b24jssdk'
import type { B24Frame } from '@bitrix24/b24jssdk'

declare const $b24: B24Frame

try {
  const response = await $b24.actions.v2.call.make<number>({
    method: 'user.add',
    params: {
      EMAIL: 'newuser1@example.com',
      UF_DEPARTMENT: [1]
    },
    requestId: Text.getUuidRfc4122()
  })

  // The payload is available only on a successful response
  if (!response.isSuccess) {
    console.error(response.getErrorMessages().join('; '))
  } else {
    const result = response.getData()!.result
    console.info('New user ID:', result)
  }
} catch (error) {
  // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
  console.error(error)
}
<!-- Load the SDK (UMD build); it is exposed as the global B24Js -->
<script src="https://unpkg.com/@bitrix24/b24jssdk@1/dist/umd/index.min.js"></script>
<script>
  async function addUser() {
    try {
      // Initialize the SDK inside a Bitrix24 frame
      const $b24 = await B24Js.initializeB24Frame()

      const response = await $b24.actions.v2.call.make({
        method: 'user.add',
        params: {
          EMAIL: 'newuser1@example.com',
          UF_DEPARTMENT: [1]
        },
        requestId: B24Js.Text.getUuidRfc4122()
      })

      // The payload is available only on a successful response
      if (!response.isSuccess) {
        console.error(response.getErrorMessages().join('; '))
        return
      }

      const result = response.getData().result
      console.info('New user ID:', result)
    } catch (error) {
      // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
      console.error(error)
    }
  }

  document.addEventListener('DOMContentLoaded', addUser)
</script>
from b24pysdk.errors import BitrixAPIError, BitrixSDKException

try:
    bitrix_response = client.user.add(
        fields={
            "EMAIL": "newuser1@example.com",
            "UF_DEPARTMENT": [
                1,
            ],
        },
    ).response
    result = bitrix_response.result
    print(result)
except BitrixAPIError as error:
    print(
        "Ошибка Bitrix API",
        f"error: {error.error}",
        f"error_description: {error.error_description}",
        sep="\n",
    )
except BitrixSDKException as error:
    print(f"Ошибка Bitrix SDK: {error.message}")
except Exception as error:
    print(f"Непредвиденная ошибка: {error}")
try {
    $response = $b24Service
        ->core
        ->call(
            'user.add',
            [
                'EMAIL'        => 'newuser1@example.com',
                'UF_DEPARTMENT' => [1],
            ]
        );

    $result = $response
        ->getResponseData()
        ->getResult();

    print_r($result);
} catch (Throwable $e) {
    echo $e->getMessage();
}
BX24.callMethod(
    "user.add",
    {
        "EMAIL": "newuser1@example.com",
        "UF_DEPARTMENT": [1]
    },
    function(result)
    {
        if(result.error())
            console.error(result.error());
        else
            console.dir(result.data());
    }
);
require_once('crest.php');

$result = CRest::call(
    'user.add',
    [
        'EMAIL' => 'newuser1@example.com',
        'UF_DEPARTMENT' => [1]
    ]
);

echo '<PRE>';
print_r($result);
echo '</PRE>';
// client и ctx уже созданы — см. раздел «SDK для Go»
res, err := client.Core().Call(ctx, "user.add", b24.Params{
	"EMAIL":         "newuser1@example.com",
	"UF_DEPARTMENT": []int{1},
})
if err != nil {
	return fmt.Errorf("user.add: %w", err)
}

var newID b24.ID
if err := json.Unmarshal(res.Result, &newID); err != nil {
	return fmt.Errorf("разбор ответа: %w", err)
}
fmt.Println("идентификатор:", newID)

Пригласить пользователя экстранета

Пользователь получит приглашение в рабочую группу 7. Подразделение UF_DEPARTMENT для него не передается.

curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
    "EMAIL": "partner@example.com",
    "EXTRANET": "Y",
    "SONET_GROUP_ID": [7]
}' \
https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/user.add
curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
    "EMAIL": "partner@example.com",
    "EXTRANET": "Y",
    "SONET_GROUP_ID": [7],
    "auth": "**put_access_token_here**"
}' \
https://**put_your_bitrix24_address**/rest/user.add
// This snippet is an ES module: top-level await requires type="module" or a bundler.
// $b24 is an already-initialized SDK instance (see the SDK "Get started" guide).
import { Text } from '@bitrix24/b24jssdk'
import type { B24Frame } from '@bitrix24/b24jssdk'

declare const $b24: B24Frame

try {
  const response = await $b24.actions.v2.call.make<number>({
    method: 'user.add',
    params: {
      EMAIL: 'partner@example.com',
      EXTRANET: 'Y',
      SONET_GROUP_ID: [7]
    },
    requestId: Text.getUuidRfc4122()
  })

  // The payload is available only on a successful response
  if (!response.isSuccess) {
    console.error(response.getErrorMessages().join('; '))
  } else {
    const result = response.getData()!.result
    console.info('New user ID:', result)
  }
} catch (error) {
  // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
  console.error(error)
}
<!-- Load the SDK (UMD build); it is exposed as the global B24Js -->
<script src="https://unpkg.com/@bitrix24/b24jssdk@1/dist/umd/index.min.js"></script>
<script>
  async function addUser() {
    try {
      // Initialize the SDK inside a Bitrix24 frame
      const $b24 = await B24Js.initializeB24Frame()

      const response = await $b24.actions.v2.call.make({
        method: 'user.add',
        params: {
          EMAIL: 'partner@example.com',
          EXTRANET: 'Y',
          SONET_GROUP_ID: [7]
        },
        requestId: B24Js.Text.getUuidRfc4122()
      })

      // The payload is available only on a successful response
      if (!response.isSuccess) {
        console.error(response.getErrorMessages().join('; '))
        return
      }

      const result = response.getData().result
      console.info('New user ID:', result)
    } catch (error) {
      // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
      console.error(error)
    }
  }

  document.addEventListener('DOMContentLoaded', addUser)
</script>
from b24pysdk.errors import BitrixAPIError, BitrixSDKException

try:
    bitrix_response = client.user.add(
        fields={
            "EMAIL": "partner@example.com",
            "EXTRANET": "Y",
            "SONET_GROUP_ID": [
                7,
            ],
        },
    ).response
    result = bitrix_response.result
    print(result)
except BitrixAPIError as error:
    print(
        "Ошибка Bitrix API",
        f"error: {error.error}",
        f"error_description: {error.error_description}",
        sep="\n",
    )
except BitrixSDKException as error:
    print(f"Ошибка Bitrix SDK: {error.message}")
except Exception as error:
    print(f"Непредвиденная ошибка: {error}")
try {
    $response = $b24Service
        ->core
        ->call(
            'user.add',
            [
                'EMAIL'        => 'partner@example.com',
                'EXTRANET' => 'Y',
                'SONET_GROUP_ID' => [7],
            ]
        );

    $result = $response
        ->getResponseData()
        ->getResult();

    print_r($result);
} catch (Throwable $e) {
    echo $e->getMessage();
}
BX24.callMethod(
    "user.add",
    {
        "EMAIL": "partner@example.com",
        "EXTRANET": "Y",
        "SONET_GROUP_ID": [7]
    },
    function(result)
    {
        if(result.error())
            console.error(result.error());
        else
            console.dir(result.data());
    }
);
require_once('crest.php');

$result = CRest::call(
    'user.add',
    [
        'EMAIL' => 'partner@example.com',
        'EXTRANET' => 'Y',
        'SONET_GROUP_ID' => [7]
    ]
);

echo '<PRE>';
print_r($result);
echo '</PRE>';
// client и ctx уже созданы — см. раздел «SDK для Go»
res, err := client.Core().Call(ctx, "user.add", b24.Params{
	"EMAIL":         "partner@example.com",
	"EXTRANET":      "Y",
	"SONET_GROUP_ID": []int{7},
})
if err != nil {
	return fmt.Errorf("user.add: %w", err)
}

var newID b24.ID
if err := json.Unmarshal(res.Result, &newID); err != nil {
	return fmt.Errorf("разбор ответа: %w", err)
}
fmt.Println("идентификатор:", newID)

Обработка ответа

HTTP-статус: 200

    {
        "result":12,
        "time":{
            "start":1721733827.713938,
            "finish":1721733828.286292,
            "duration":0.5723540782928467,
            "processing":0.5508849620819092,
            "date_start":"2024-07-23T11:23:47+00:00",
            "date_finish":"2024-07-23T11:23:48+00:00",
            "operating":0.5508630275726318
        }
    }

Возвращаемые данные

Название
тип

Описание

result
integer

Идентификатор нового пользователя

time
time

Информация о времени выполнения запроса

Обработка ошибок

HTTP-статус: 400

{
    "error": "ERROR_ARGUMENT",
    "error_description": "no_extranet_field",
    "argument": ""
}

Название
тип

Описание

error
string

Строковый код ошибки. Состоит из цифр, латинских букв и знака подчеркивания. Может прийти пустым — тогда причину показывает только error_description

error_description
string

Текст ошибки для разработчика. Не показывайте его конечному пользователю без обработки

Возможные коды ошибок

Статус

Код

Описание

Значение

400

ERROR_ARGUMENT

wrong_email

Не передан EMAIL или передан некорректный e-mail

400

ERROR_ARGUMENT

no_extranet_field

Не передан UF_DEPARTMENT для сотрудника и не передан EXTRANET = Y

400

ERROR_ARGUMENT

no_sonet_group_for_extranet

Передан EXTRANET = Y, но не передан SONET_GROUP_ID

400

ERROR_ARGUMENT

invalid_type_field

В текстовое поле передан массив или объект. Код поля приходит в ключе argument ответа

400

ERROR_ARGUMENT

Не удалось выполнить проверку Битрикс24.Network. Попробуйте позже или обратитесь в поддержку.

E-mail не прошел проверку Битрикс24.Network

400

ERROR_ARGUMENT

Пользователь с таким email уже существует

Пользователь с этим e-mail уже есть в Битрикс24

400

ERROR_ARGUMENT

user_count_exceeded

Превышен лимит пользователей на тарифе

400

ERROR_CORE

access_denied

У пользователя нет права приглашать сотрудников

400

ERROR_CORE

Текст ошибки зависит от причины

Не удалось отправить приглашение через Битрикс24.Network или добавить пользователя в группу из SONET_GROUP_ID

401

insufficient_scope

The request requires higher privileges than provided by the access token

У приложения или вебхука версия скоупа user_brief или user_basic. Метод работает только в версии user

Статусы и коды системных ошибок

HTTP-статус: 4xx, 5xx

Описанные ниже ошибки возвращает сам REST API, а не логика конкретного метода. Они могут прийти в ответ на любой метод.

Статус

Код
Текст ошибки

Описание

500

INTERNAL_SERVER_ERROR
Internal server error

Возникла внутренняя ошибка сервера. Повторите вызов, а если ошибка сохраняется, обратитесь к администратору сервера или в техническую поддержку Битрикс24

500

ERROR_UNEXPECTED_ANSWER
Server returned an unexpected response

Сервер вернул неожиданный ответ. Повторите вызов, а если ошибка сохраняется, обратитесь к администратору сервера или в техническую поддержку Битрикс24

503

QUERY_LIMIT_EXCEEDED
Too many requests

Превышен лимит на интенсивность запросов

429

OPERATION_TIME_LIMIT
Method is blocked due to operation time limit

Метод заблокирован из-за превышения лимита на ресурсоемкость запросов. Блокировка снимается автоматически, когда накопленное время выполнения метода перестает превышать лимит

401

NO_AUTH_FOUND
Wrong authorization data

В запросе нет авторизационных данных: не передан ни access-токен, ни код вебхука

401

INVALID_REQUEST
Https required

Методы вызываются только по протоколу HTTPS

401

OVERLOAD_LIMIT
REST API is blocked due to overload

REST API заблокирован из-за перегрузки. Это ручная индивидуальная блокировка. Чтобы ее снять, обратитесь в техническую поддержку Битрикс24

401

ACCESS_DENIED
REST is available only on commercial plans

REST API доступен только на коммерческих тарифах. У вебхука текст ошибки другой — REST is available only by subscription

401

INVALID_CREDENTIALS
Invalid request credentials

Не найден активный вебхук с указанным идентификатором пользователя и секретным кодом

404

ERROR_METHOD_NOT_FOUND
Method not found!

Метод с таким именем не найден. Имя написано с ошибкой, метода нет в REST API или он недоступен без нужного скоупа

401

insufficient_scope
The request requires higher privileges than provided by the webhook token

Запрос требует более широких прав, чем есть у токена: у вебхука это выданные ему права, у приложения — скоуп. У приложения текст ошибки заканчивается на provided by the access token

401

expired_token
The access token provided has expired

Срок действия access-токена истек

401

user_access_error
The user does not have access to the application

Приложение установлено, но администратор Битрикс24 открыл доступ к нему только конкретным пользователям

403

PORTAL_DELETED
Portal was deleted

Публичная часть сайта закрыта. Чтобы открыть ее на коробочной установке, отключите опцию «Временное закрытие публичной части сайта». Путь к настройке: Рабочий стол > Настройки > Настройки продукта > Настройки модулей > Главный модуль > Временное закрытие публичной части сайта

Продолжите изучение