لوكلاء AI: ملف markdown لهذه الصفحة — /docs-content-en/entities/activities.md فهرس التوثيق — /llms.txt

مقالات التوثيق متاحة حاليًا باللغة الإنجليزية فقط.

Activities

CRM activity management: calls, meetings, tasks, emails. Activities are linked to deals, leads, contacts and other entities.

Bitrix24 API: crm.activity.* Scope: crm

Create activity

POST /v1/activities

Creates a new CRM activity: a call, meeting, task or email. The activity is linked to a CRM entity via ownerTypeId + ownerId.

Request fields (body)

The minimum set to create an activity is subject, typeId, communications plus a binding to a CRM entity. The binding is provided either by the ownerTypeId + ownerId pair, or by the entityTypeId + entityId keys inside a communications item. If neither is provided, Bitrix24 cannot bind the communication and returns an error about communications.

Parameter Type Required Description
Parametersubject Typestring Requiredyes DescriptionActivity subject
ParametertypeId Typenumber Requiredyes DescriptionType: 1 — meeting, 2 — call, 3 — task, 4 — email, 5 — action, 6 — custom action
Parametercommunications Typeobject[] Requiredyes DescriptionActivity communications. An array of objects: [{ "value": "+1…", "entityTypeId": 3, "entityId": 17 }]. Nested keys are accepted in camelCase (type, value, entityTypeId, entityId) — consistent with the rest of the API — or in Bitrix24 UPPER case (TYPE, VALUE, ENTITY_TYPE_ID, ENTITY_ID). value is a phone number or email address; entityTypeId + entityId is the CRM entity the communication belongs to (provides the binding when ownerTypeId/ownerId are omitted). When an owner is set, [{ "value": "+1…" }] is enough
ParameterownerTypeId Typenumber Requiredyes¹ DescriptionParent entity type: 1 — lead, 2 — deal, 3 — contact, 4 — company
ParameterownerId Typenumber Requiredyes¹ DescriptionParent entity ID. Lookup: GET /v1/deals, GET /v1/leads, GET /v1/contacts, GET /v1/companies
ParameterresponsibleId Typenumber Required DescriptionResponsible person. Defaults to the current user. List: GET /v1/users
Parameterdescription Typestring Required DescriptionDescription. For an email, the email body
ParameterdescriptionType Typenumber Required DescriptionFormat of description: 1 — plain text, 2 — BBCode, 3 — HTML
Parameterpriority Typenumber Required DescriptionPriority: 1 — low, 2 — medium, 3 — high
Parameterdirection Typenumber Required DescriptionDirection: 1 — incoming, 2 — outgoing
Parametercompleted Typeboolean Required DescriptionCompleted. For an email with direction: 2, true sends the email when the activity is created, false creates the activity without sending
Parametersettings Typeobject Required DescriptionActivity settings; the structure depends on typeId. To send an email, set MESSAGE_FROM to the sender address, either sales@example.com or Sales team <sales@example.com>. Allowed addresses: GET /v1/mail/mailboxes/:id/senders. DISABLE_SENDING_MESSAGE_COPY: "Y" turns off the copy of the email sent to the sender address. Keys inside settings are passed in UPPER case
ParameterstartTime Typedatetime Required DescriptionStart date
ParameterendTime Typedatetime Required DescriptionEnd date
Parameterdeadline Typedatetime Required DescriptionDeadline. On create, Bitrix24 ignores the provided value and derives deadline from startTime/endTime — it cannot be set separately on POST

¹ Pass ownerTypeId and ownerId together, and only if the binding is not provided via entityTypeId/entityId inside communications. If the binding comes through a communication, both fields may be omitted.

The nested communications keys are accepted in two forms: camelCase (type, value, entityTypeId, entityId) — consistent with the rest of the API — and Bitrix24 UPPER case (TYPE, VALUE, ENTITY_TYPE_ID, ENTITY_ID). If both forms of the same key appear in one object, the UPPER-case one wins.

Full list of fields: GET /v1/activities/fields.

Examples

curl — personal key

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/activities \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "typeId": 2,
    "ownerTypeId": 3,
    "ownerId": 17,
    "subject": "Call the client",
    "description": "Discuss delivery terms",
    "responsibleId": 1,
    "priority": 2,
    "direction": 2,
    "communications": [
      { "value": "+12025550123", "entityTypeId": 3, "entityId": 17 }
    ],
    "startTime": "2026-04-16T10:00:00+00:00",
    "endTime": "2026-04-16T10:15:00+00:00"
  }'

curl — OAuth application

Terminal 
curl -X POST https://vibecode.bitrix24.com/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": "Call the client",
    "description": "Discuss delivery terms",
    "responsibleId": 1,
    "priority": 2,
    "direction": 2,
    "communications": [
      { "value": "+12025550124", "entityTypeId": 3, "entityId": 17 }
    ],
    "startTime": "2026-04-16T10:00:00+00:00",
    "endTime": "2026-04-16T10:15:00+00:00"
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/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: 'Call the client',
    description: 'Discuss delivery terms',
    responsibleId: 1,
    priority: 2,
    direction: 2,
    communications: [
      { value: '+12025550125', entityTypeId: 3, entityId: 17 },
    ],
    startTime: '2026-04-16T10:00:00+00:00',
    endTime: '2026-04-16T10:15:00+00:00',
  }),
})

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

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/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: 'Call the client',
    description: 'Discuss delivery terms',
    responsibleId: 1,
    priority: 2,
    direction: 2,
    communications: [
      { value: '+12025550126', entityTypeId: 3, entityId: 17 },
    ],
    startTime: '2026-04-16T10:00:00+00:00',
    endTime: '2026-04-16T10:15:00+00:00',
  }),
})

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

curl — sending an email from a deal

The email to contact 17 is sent when the activity is created. The activity is bound to deal 575 and to the contact from communications.

Terminal 
curl -X POST https://vibecode.bitrix24.com/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": "Commercial proposal",
    "description": "<p>Hello! Please find our supply proposal below.</p>",
    "descriptionType": 3,
    "communications": [
      { "type": "EMAIL", "value": "client@example.com", "entityTypeId": 3, "entityId": 17 }
    ],
    "settings": {
      "MESSAGE_FROM": "Sales team <sales@example.com>",
      "DISABLE_SENDING_MESSAGE_COPY": "Y"
    }
  }'

Bindings of the created activity: GET /v1/activities/:id/bindings.

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typeobject DescriptionThe created activity with all fields — see Activity fields
Fielddata.id Typenumber DescriptionID of the created activity
Fielddata.typeId Typenumber DescriptionActivity type
Fielddata.ownerTypeId Typenumber DescriptionParent entity type
Fielddata.ownerId Typenumber DescriptionParent entity ID
Fielddata.subject Typestring DescriptionSubject
Fielddata.responsibleId Typenumber DescriptionResponsible person
Fielddata.settings Typeobject DescriptionActivity settings. For a sent email: MESSAGE_FROM, IS_MESSAGE_SENT: true and MESSAGE_HEADERS with the Message-Id header. If IS_MESSAGE_SENT is absent, the email was not sent
Fielddata.createdAt Typedatetime DescriptionCreation date
Fielddata.updatedAt Typedatetime DescriptionModification date

Response example

JSON 
{
  "success": true,
  "data": {
    "id": 3894,
    "typeId": 2,
    "ownerTypeId": 3,
    "ownerId": 17,
    "subject": "Call the client",
    "description": "Discuss delivery terms",
    "responsibleId": 1,
    "priority": 2,
    "direction": 2,
    "completed": false,
    "startTime": "2026-04-16T10:00:00+00:00",
    "endTime": "2026-04-16T10:15:00+00:00",
    "deadline": "2026-04-16T10:00:00+00:00",
    "createdAt": "2026-04-15T14:30:00+00:00",
    "updatedAt": "2026-04-15T14:30:00+00:00"
  }
}

Error response example

400 — a required field is missing (subject, typeId or communications):

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

Errors

HTTP Code Description
HTTP400 CodeMISSING_REQUIRED_FIELDS DescriptionOne of the required fields is missing: subject, typeId, communications (checked before the Bitrix24 call)
HTTP400 CodeINVALID_PARAMS DescriptionA field value does not match its declared type — for example, a string instead of a number in typeId
HTTP404 CodeENTITY_NOT_FOUND DescriptionAn email (typeId: 4, completed: true) without settings.MESSAGE_FROM; the message is Email send error. "From" is not found. The activity is still created, see "Known specifics"
HTTP403 CodeSCOPE_DENIED DescriptionThe API key lacks the crm scope
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no configured tokens

Full list of common API errors — Errors.

Known specifics

Signature in the email body. A Bitrix24 signature line is appended to the email description after <br/><br/>. The recipient sees it, and it is returned in the description of the response.

A repeated request sends the email again. Every call with the same body creates a new activity and sends a new email; an identical originId does not prevent this. Do not repeat the request after a 201 response.

On a send error the activity stays in the record. The 404 ENTITY_NOT_FOUND response to an email without MESSAGE_FROM arrives after the activity has been created: the email is not sent, but the activity exists. Before retrying, find it in the activity list by ownerTypeId and ownerId and delete it.

Sender without a connected mailbox. If the MESSAGE_FROM address does not belong to any mailbox in the mailbox list, the email is sent from no-reply-crm@<portal>. The recipient sees the name from MESSAGE_FROM and that address. <portal> is the Bitrix24 account domain.

The sender address is not checked against the list. A MESSAGE_FROM value outside the sender addresses list also returns 201 and IS_MESSAGE_SENT: true. Take the address from that list.

The service identifier is only in the header. The email subject and body carry no service markers. The activity identifier is sent in the Message-Id header; its value is in settings.MESSAGE_HEADERS of the response.

See also