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

Create an activity for a CRM record

POST /v1/deals/:id/activities

POST /v1/leads/:id/activities

POST /v1/contacts/:id/activities

POST /v1/companies/:id/activities

Creates an activity for the deal, lead, contact or company selected in the URL. The owner comes from the URL, so the body needs no owner fields.

Parameters

Parameter Type Required Description
Parameterid (path) Typenumber Requiredyes DescriptionID of the activity owner. The URL sets the owner type: deals — deal, type 2, leads — lead, type 1, contacts — contact, type 3, companies — company, type 4. IDs come from the deal, lead, contact or company lists

Request fields (body)

Field Type Required Description
Fieldsubject Typestring Requiredyes DescriptionActivity subject. Without it — 422 BITRIX_ERROR
FieldTYPE_ID Typeinteger Requiredyes DescriptionNumeric activity type: 1 — meeting, 2 — call, 3 — task, 4 — email. The field name is passed in upper case; typeId is not recognized. Without the field — 422 BITRIX_ERROR
FieldCOMMUNICATIONS Typearray Requiredyes DescriptionActivity communications, an array of objects. The field name and nested keys are passed in upper case; communications is not recognized. Without the field — 422 BITRIX_ERROR
FieldCOMMUNICATIONS[].VALUE Typestring Requiredyes DescriptionPhone or email. Without it — 422 BITRIX_ERROR
FieldCOMMUNICATIONS[].ENTITY_TYPE_ID Typeinteger Requiredno DescriptionType of the CRM record the communication belongs to: 3 — contact, 4 — company
FieldCOMMUNICATIONS[].ENTITY_ID Typeinteger Requiredno DescriptionID of that record. From the contact list or the company list
Fieldtype Typestring Requiredno DescriptionActivity kind: email, call, meeting or task. This is not the numeric TYPE_ID. Any other value — 400 INVALID_ACTIVITY_TYPE
Fielddescription Typestring Requiredno DescriptionActivity description
Fieldcompleted Typeboolean Requiredno DescriptionWhether the activity is completed
FieldresponsibleId Typenumber Requiredno DescriptionResponsible employee. List — GET /v1/users
Fieldpriority Typenumber Requiredno DescriptionActivity priority
Fielddirection Typenumber Requiredno DescriptionActivity direction
Fielddeadline, startTime, endTime Typestring Requiredno DescriptionActivity deadline, start and end. Specify the time zone offset explicitly: 2026-10-20T15:00:00+00:00
Fieldid, createdAt, updatedAt Type— RequiredRO DescriptionSet by the system; do not pass them on creation
FieldOther activity fields Typeany Requiredno DescriptionPassed through unchanged under their original upper-case names, like TYPE_ID

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/deals/575/activities" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "subject": "Call the customer",
  "type": "call",
  "TYPE_ID": 2,
  "completed": false,
  "responsibleId": 1,
  "COMMUNICATIONS": [
    {
      "VALUE": "+12025550123",
      "ENTITY_TYPE_ID": 3,
      "ENTITY_ID": 17
    }
  ]
}'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/deals/575/activities" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "subject": "Call the customer",
  "type": "call",
  "TYPE_ID": 2,
  "completed": false,
  "responsibleId": 1,
  "COMMUNICATIONS": [
    {
      "VALUE": "+12025550123",
      "ENTITY_TYPE_ID": 3,
      "ENTITY_ID": 17
    }
  ]
}'

JavaScript — personal key

javascript 
const response = await fetch('https://vibecode.bitrix24.com/v1/deals/575/activities', {
  method: 'POST',
  headers: {
    "X-Api-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "subject": "Call the customer",
    "type": "call",
    "TYPE_ID": 2,
    "completed": false,
    "responsibleId": 1,
    "COMMUNICATIONS": [
      {
        "VALUE": "+12025550123",
        "ENTITY_TYPE_ID": 3,
        "ENTITY_ID": 17
      }
    ]
  }),
})
const result = await response.json()
if (!response.ok || !result.success) throw new Error(JSON.stringify(result.error))
console.log(result.data.id)

JavaScript — OAuth application

javascript 
const response = await fetch('https://vibecode.bitrix24.com/v1/deals/575/activities', {
  method: 'POST',
  headers: {
    "X-Api-Key": "YOUR_APP_KEY",
    "Authorization": "Bearer USER_SESSION_TOKEN",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "subject": "Call the customer",
    "type": "call",
    "TYPE_ID": 2,
    "completed": false,
    "responsibleId": 1,
    "COMMUNICATIONS": [
      {
        "VALUE": "+12025550123",
        "ENTITY_TYPE_ID": 3,
        "ENTITY_ID": 17
      }
    ]
  }),
})
const result = await response.json()
if (!response.ok || !result.success) throw new Error(JSON.stringify(result.error))
console.log(result.data.id)

Response fields

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue on success, HTTP 201
Fielddata Typeobject DescriptionThe created activity. Only id is returned
Fielddata.id Typenumber DescriptionID of the created activity. The full record — GET /v1/activities/:id

Response example

JSON 
{
  "success": true,
  "data": {
    "id": 8385
  }
}

Error response example

400 — unsupported activity kind in type:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_ACTIVITY_TYPE",
    "message": "Invalid activity type 'sms'. Available: email, call, meeting, task"
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_ACTIVITY_TYPE DescriptionA non-empty type is not one of email, call, meeting, task
HTTP422 CodeBITRIX_ERROR DescriptionA required field is missing, or a communication has no VALUE. The message names the field: The field SUBJECT is not defined or empty., The field TYPE_ID is not defined or invalid., The field COMMUNICATIONS is not defined or invalid.
HTTP422 CodeBITRIX_ERROR DescriptionNo owner with this id: Could not find 'DEAL' with ID: 999999999
HTTP422 CodeBITRIX_ERROR DescriptionAnother Bitrix24 refusal; the text is in error.message
HTTP400 CodeINVALID_PARAMS DescriptionBitrix24 rejected a field value
HTTP404 CodeENTITY_NOT_FOUND DescriptionBitrix24 responded with a "not found" code
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionA read-only key cannot create activities — see access rights
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks the crm scope
HTTP401 CodeTOKEN_MISSING DescriptionThe key has no Bitrix24 tokens configured

The full list of common API errors — Errors.

Known specifics

The URL owner overrides the body. The ownerTypeId, ownerId, OWNER_TYPE_ID and OWNER_ID body fields are replaced with the owner from the URL: the activity is always created for the record in the path.

The contract differs from the main create method. POST /v1/activities accepts typeId and communications in camelCase, the owner in the body, and returns the full activity. This method accepts TYPE_ID and COMMUNICATIONS in upper case and returns only data.id.

See also