## 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 `. Allowed addresses: [`GET /v1/mail/mailboxes/:id/senders`](/docs/mail/mailboxes/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](/docs/entities/activities/fields). ## Examples ### curl — personal key ```bash 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 ```bash 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`. ```bash 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": "

Hello! Please find our supply proposal below.

", "descriptionType": 3, "communications": [ { "type": "EMAIL", "value": "client@example.com", "entityTypeId": 3, "entityId": 17 } ], "settings": { "MESSAGE_FROM": "Sales team ", "DISABLE_SENDING_MESSAGE_COPY": "Y" } }' ``` Bindings of the created activity: [`GET /v1/activities/:id/bindings`](/docs/entities/activities/bindings/list). ## Response fields | Field | Type | Description | |------|-----|---------| | `success` | boolean | Always `true` on success | | `data` | object | The created activity with all fields — see [Activity fields](/docs/entities/activities/fields) | | `data.id` | number | ID of the created activity | | `data.typeId` | number | Activity type | | `data.ownerTypeId` | number | Parent entity type | | `data.ownerId` | number | Parent entity ID | | `data.subject` | string | Subject | | `data.responsibleId` | number | Responsible person | | `data.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 | | `data.createdAt` | datetime | Creation date | | `data.updatedAt` | datetime | Modification 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 | |------|-----|---------| | 400 | `MISSING_REQUIRED_FIELDS` | One of the required fields is missing: `subject`, `typeId`, `communications` (checked before the Bitrix24 call) | | 400 | `INVALID_PARAMS` | A field value does not match its declared type — for example, a string instead of a number in `typeId` | | 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](/docs/errors). ## Known specifics **Signature in the email body.** A Bitrix24 signature line is appended to the email `description` after `

`. 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](/docs/entities/activities/list) by `ownerTypeId` and `ownerId` and [delete it](/docs/entities/activities/delete). **Sender without a connected mailbox.** If the `MESSAGE_FROM` address does not belong to any mailbox in the [mailbox list](/docs/mail/mailboxes/list), the email is sent from `no-reply-crm@`. The recipient sees the name from `MESSAGE_FROM` and that address. `` is the Bitrix24 account domain. **The sender address is not checked against the list.** A `MESSAGE_FROM` value outside the [sender addresses](/docs/mail/mailboxes/senders) 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 - [List activities](/docs/entities/activities/list) - [Activity fields](/docs/entities/activities/fields) - [List bindings](/docs/entities/activities/bindings/list) - [Mailbox sender addresses](/docs/mail/mailboxes/senders) - [Deals](/docs/entities/deals) - [Leads](/docs/entities/leads) - [Entity API](/docs/entity-api) - [Limits and optimization](/docs/optimization)