For AI agents: markdown of this page — /docs-content-en/entities/activities/create.md documentation index — /llms.txt

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 Req. 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/e-mail; 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
priority number Priority: 1 — low, 2 — medium, 3 — high
direction number Direction: 1 — incoming, 2 — outgoing
completed boolean Completed
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

¹ The ownerTypeId + ownerId pair is needed 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()

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

See also