Para agentes de IA: markdown de esta página — /docs-content-en/entities/activities.md índice de la documentación — /llms.txt

Los artículos de la documentación están disponibles actualmente en inglés.

Activities

CRM activity management: calls, meetings, tasks, email. Linked to deals, leads, contacts and other entities.

Bitrix24 API: crm.activity.* Scope: crm

A single activity can appear in the timeline of several CRM entities at once — see Activity bindings.

An activity with a custom layout in the timeline — icon, header, blocks, buttons — is created through Configurable activities.

The AI transcript of a client call — a Call-type activity — is returned by CRM call transcripts.

Create to-dos through CRM to-dos, then read and list them here with providerId=CRM_TODO.

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
subject string yes Activity subject
typeId number yes Type: 1 — meeting, 2 — call, 3 — task, 4 — email, 5 — action, 6 — custom action
communications object[] yes Activity 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
ownerTypeId number yes¹ Parent entity type: 1 — lead, 2 — deal, 3 — contact, 4 — company
ownerId number yes¹ Parent entity ID. Lookup: GET /v1/deals, GET /v1/leads, GET /v1/contacts, GET /v1/companies
responsibleId number Responsible person. Defaults to the current user. List: GET /v1/users
description string Description. For an email, the email body
descriptionType number Format of description: 1 — plain text, 2 — BBCode, 3 — HTML
priority number Priority: 1 — low, 2 — medium, 3 — high
direction number Direction: 1 — incoming, 2 — outgoing
completed boolean Completed. For an email with direction: 2, true sends the email when the activity is created, false creates the activity without sending
settings object Activity 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
startTime datetime Start date
endTime datetime End date
deadline datetime Deadline. 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
id number ID of the created activity
typeId number Activity type
ownerTypeId number Parent entity type
ownerId number Parent entity ID
subject string Subject
responsibleId number Responsible person
settings object Activity 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
createdAt datetime Creation date
updatedAt datetime Modification date

The response contains all activity fields.

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."
  }
}

403 — no scope:

JSON 
{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "This endpoint requires 'crm' scope"
  }
}

Errors

HTTP Code Description
400 MISSING_REQUIRED_FIELDS One of the required fields is missing: subject, typeId, communications (checked before the Bitrix24 call)
400 INVALID_REQUEST Invalid field values
404 ENTITY_NOT_FOUND An 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"
403 SCOPE_DENIED The API key lacks the crm scope
401 TOKEN_MISSING The 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