Для AI-агентов: markdown этой страницы — /docs-content/entities/activities/create.md индекс документации — /llms.txt

Создать дело

POST /v1/activities

Создаёт новое CRM-дело: звонок, встречу, задачу или email. Дело привязывается к CRM-сущности через ownerTypeId + ownerId.

Поля запроса (body)

Минимальный набор для создания дела — subject, typeId, communications плюс привязка к CRM-сущности. Привязку задаёт либо пара ownerTypeId + ownerId, либо поля entityTypeId + entityId внутри элемента communications. Если не задано ни одно из двух, Битрикс24 не может привязать коммуникацию и возвращает ошибку про communications.

Параметр Тип Обяз. Описание
Параметрsubject Типstring Обяз.да ОписаниеТема дела
ПараметрtypeId Типnumber Обяз.да ОписаниеТип: 1 — встреча, 2 — звонок, 3 — задача, 4 — письмо, 5 — действие, 6 — пользовательское действие
Параметрcommunications Типobject[] Обяз.да ОписаниеКоммуникации дела. Массив объектов: [{ "value": "+7…", "entityTypeId": 3, "entityId": 17 }]. Вложенные ключи принимаются в camelCase (type, value, entityTypeId, entityId) — как и во всём остальном API — либо в ВЕРХНЕМ регистре Битрикс24 (TYPE, VALUE, ENTITY_TYPE_ID, ENTITY_ID). value — телефон или e-mail. entityTypeId + entityId — CRM-сущность, которой принадлежит коммуникация (задаёт привязку, если не переданы ownerTypeId/ownerId). Когда владелец указан, достаточно [{ "value": "+7…" }]
ПараметрownerTypeId Типnumber Обяз.да¹ ОписаниеТип родительской сущности: 1 — лид, 2 — сделка, 3 — контакт, 4 — компания
ПараметрownerId Типnumber Обяз.да¹ ОписаниеID родительской сущности. Поиск: GET /v1/deals, GET /v1/leads, GET /v1/contacts, GET /v1/companies
ПараметрresponsibleId Типnumber Обяз. ОписаниеОтветственный. По умолчанию — текущий пользователь. Список: GET /v1/users
Параметрdescription Типstring Обяз. ОписаниеОписание. У письма — текст письма
ПараметрdescriptionType Типnumber Обяз. ОписаниеФормат description: 1 — обычный текст, 2 — BB-код, 3 — HTML
Параметрpriority Типnumber Обяз. ОписаниеПриоритет: 1 — низкий, 2 — средний, 3 — высокий
Параметрdirection Типnumber Обяз. ОписаниеНаправление: 1 — входящее, 2 — исходящее
Параметрcompleted Типboolean Обяз. ОписаниеЗавершено. У письма с direction: 2 значение true отправляет письмо при создании дела, false создаёт дело без отправки
Параметрsettings Типobject Обяз. ОписаниеНастройки дела, структура зависит от typeId. Для отправки письма — MESSAGE_FROM: адрес отправителя, строка sales@example.com или Отдел продаж <sales@example.com>. Допустимые адреса — GET /v1/mail/mailboxes/:id/senders. DISABLE_SENDING_MESSAGE_COPY: "Y" отключает копию письма на адрес отправителя. Ключи внутри settings передаются в ВЕРХНЕМ регистре
ПараметрstartTime Типdatetime Обяз. ОписаниеДата начала
ПараметрendTime Типdatetime Обяз. ОписаниеДата окончания
Параметрdeadline Типdatetime Обяз. ОписаниеКрайний срок. При создании Битрикс24 игнорирует переданное значение и вычисляет deadline из startTime/endTime — отдельно задать его при POST нельзя

¹ Пара ownerTypeId + ownerId нужна вместе и только если привязка не задана через entityTypeId/entityId внутри communications. Если привязка идёт через коммуникацию — оба поля можно опустить.

Вложенные ключи communications принимаются в двух формах: camelCase (type, value, entityTypeId, entityId) — единообразно с остальным API — и в ВЕРХНЕМ регистре Битрикс24 (TYPE, VALUE, ENTITY_TYPE_ID, ENTITY_ID). Если в одном объекте заданы обе формы одного ключа, приоритет у ВЕРХНЕГО регистра.

Полный список полей: GET /v1/activities/fields.

Примеры

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

Terminal 
curl -X POST https://vibecode.bitrix24.tech/v1/activities \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "typeId": 2,
    "ownerTypeId": 3,
    "ownerId": 17,
    "subject": "Звонок клиенту",
    "description": "Обсудить условия поставки",
    "responsibleId": 1,
    "priority": 2,
    "direction": 2,
    "communications": [
      { "value": "+7 999 123-45-67", "entityTypeId": 3, "entityId": 17 }
    ],
    "startTime": "2026-04-16T10:00:00+03:00",
    "endTime": "2026-04-16T10:15:00+03:00"
  }'

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

Terminal 
curl -X POST https://vibecode.bitrix24.tech/v1/activities \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "typeId": 2,
    "ownerTypeId": 3,
    "ownerId": 17,
    "subject": "Звонок клиенту",
    "description": "Обсудить условия поставки",
    "responsibleId": 1,
    "priority": 2,
    "direction": 2,
    "communications": [
      { "value": "+7 999 123-45-67", "entityTypeId": 3, "entityId": 17 }
    ],
    "startTime": "2026-04-16T10:00:00+03:00",
    "endTime": "2026-04-16T10:15:00+03:00"
  }'

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/activities', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    typeId: 2,
    ownerTypeId: 3,
    ownerId: 17,
    subject: 'Звонок клиенту',
    description: 'Обсудить условия поставки',
    responsibleId: 1,
    priority: 2,
    direction: 2,
    communications: [
      { value: '+7 999 123-45-67', entityTypeId: 3, entityId: 17 },
    ],
    startTime: '2026-04-16T10:00:00+03:00',
    endTime: '2026-04-16T10:15:00+03:00',
  }),
})

const { success, data } = await res.json()
console.log('Activity ID:', data.id)

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/activities', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    typeId: 2,
    ownerTypeId: 3,
    ownerId: 17,
    subject: 'Звонок клиенту',
    description: 'Обсудить условия поставки',
    responsibleId: 1,
    priority: 2,
    direction: 2,
    communications: [
      { value: '+7 999 123-45-67', entityTypeId: 3, entityId: 17 },
    ],
    startTime: '2026-04-16T10:00:00+03:00',
    endTime: '2026-04-16T10:15:00+03:00',
  }),
})

const { success, data } = await res.json()

curl — отправка письма из сделки

Письмо контакту 17 уходит при создании дела. Дело привязывается к сделке 575 и к контакту из communications.

Terminal 
curl -X POST https://vibecode.bitrix24.tech/v1/activities \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "typeId": 4,
    "direction": 2,
    "completed": true,
    "ownerTypeId": 2,
    "ownerId": 575,
    "subject": "Коммерческое предложение",
    "description": "<p>Добрый день! Направляем предложение по поставке.</p>",
    "descriptionType": 3,
    "communications": [
      { "type": "EMAIL", "value": "client@example.com", "entityTypeId": 3, "entityId": 17 }
    ],
    "settings": {
      "MESSAGE_FROM": "Отдел продаж <sales@example.com>",
      "DISABLE_SENDING_MESSAGE_COPY": "Y"
    }
  }'

Привязки созданного дела — GET /v1/activities/:id/bindings.

Поля ответа

Поле Тип Описание
Полеsuccess Типboolean ОписаниеВсегда true при успехе
Полеdata Типobject ОписаниеСозданное дело со всеми полями — см. Поля дела
Полеdata.id Типnumber ОписаниеID созданного дела
Полеdata.typeId Типnumber ОписаниеТип дела
Полеdata.ownerTypeId Типnumber ОписаниеТип родительской сущности
Полеdata.ownerId Типnumber ОписаниеID родительской сущности
Полеdata.subject Типstring ОписаниеТема
Полеdata.responsibleId Типnumber ОписаниеОтветственный
Полеdata.settings Типobject ОписаниеНастройки дела. У отправленного письма — MESSAGE_FROM, IS_MESSAGE_SENT: true и MESSAGE_HEADERS с заголовком Message-Id. Если IS_MESSAGE_SENT нет, письмо не отправлялось
Полеdata.createdAt Типdatetime ОписаниеДата создания
Полеdata.updatedAt Типdatetime ОписаниеДата изменения

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

JSON 
{
  "success": true,
  "data": {
    "id": 3894,
    "typeId": 2,
    "ownerTypeId": 3,
    "ownerId": 17,
    "subject": "Звонок клиенту",
    "description": "Обсудить условия поставки",
    "responsibleId": 1,
    "priority": 2,
    "direction": 2,
    "completed": false,
    "startTime": "2026-04-16T10:00:00+03:00",
    "endTime": "2026-04-16T10:15:00+03:00",
    "deadline": "2026-04-16T10:00:00+03:00",
    "createdAt": "2026-04-15T14:30:00+03:00",
    "updatedAt": "2026-04-15T14:30:00+03:00"
  }
}

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

400 — не передано обязательное поле (subject, typeId или communications):

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_REQUIRED_FIELDS",
    "message": "Body field \"communications\" is required to create activity."
  }
}

Ошибки

HTTP Код Описание
HTTP400 КодMISSING_REQUIRED_FIELDS ОписаниеНе передано одно из обязательных полей: subject, typeId, communications (проверяется до вызова Битрикс24)
HTTP400 КодINVALID_PARAMS ОписаниеЗначение поля не соответствует объявленному типу — например, строка вместо числа в typeId
HTTP404 КодENTITY_NOT_FOUND ОписаниеПисьмо — typeId: 4, completed: true — без settings.MESSAGE_FROM, сообщение Email send error. "From" is not found. Дело при этом создаётся, см. «Известные особенности»
HTTP403 КодSCOPE_DENIED ОписаниеAPI-ключ не имеет скоупа crm
HTTP401 КодTOKEN_MISSING ОписаниеAPI-ключ не имеет настроенных токенов

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

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

Подпись в тексте письма. К description письма добавляется строка <br/><br/>Отправлено из «Битрикс24». Её видит получатель, она же возвращается в description ответа.

Повторный запрос отправляет письмо ещё раз. Каждый вызов с тем же телом создаёт новое дело и отправляет новое письмо, одинаковый originId этого не предотвращает. После ответа 201 запрос не повторяйте.

При ошибке отправки дело остаётся в карточке. Ответ 404 ENTITY_NOT_FOUND на письмо без MESSAGE_FROM приходит, когда дело уже создано: письмо не отправлено, а дело есть. Перед повторным запросом найдите его в списке дел по ownerTypeId и ownerId и удалите.

Отправитель без подключённого почтового ящика. Если адрес из MESSAGE_FROM не принадлежит ни одному ящику из списка почтовых ящиков, письмо уходит с адреса no-reply-crm@<portal>. Получатель видит имя из MESSAGE_FROM и этот адрес. <portal> — домен портала.

Адрес отправителя не сверяется со списком. Значение MESSAGE_FROM вне списка адресов отправителя тоже даёт 201 и IS_MESSAGE_SENT: true. Берите адрес из этого списка.

Служебный идентификатор — только в заголовке. Тема и текст письма уходят без служебных меток. Идентификатор дела передаётся в заголовке Message-Id, его значение — в settings.MESSAGE_HEADERS ответа.

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