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

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

CRM to-dos

Create and update to-do activities — activities with provider CRM_TODO on a deal, lead, contact or company. To read and list these activities, see Activities.

Bitrix24 API: crm.activity.todo.* Scope: crm

Create a to-do

POST /v1/activity-todos

Creates a "To-do" activity on a deal, lead, contact or company. Fields are passed flat at the JSON root, without a fields wrapper.

Request fields (body)

Field Type Required Description
FieldownerTypeId Typenumber Requiredyes DescriptionType of the CRM object the activity belongs to. For a deal, 2
FieldownerId Typenumber Requiredyes DescriptionCRM object ID. For a deal, an ID from GET /v1/deals
Fielddeadline Typestring Requiredyes DescriptionActivity deadline in ISO 8601 format, for example 2026-11-02T12:00:00+00:00
Fieldtitle Typestring Requiredno DescriptionActivity title. Returned in the subject field of the response
Fielddescription Typestring Requiredno DescriptionActivity description
FieldresponsibleId Typenumber Requiredno DescriptionResponsible person ID. List: GET /v1/users. If omitted, the key's user becomes the responsible person
FieldparentActivityId Typenumber Requiredno DescriptionID of the activity the new one is linked to. The parent must belong to the same CRM object. Activities of an object: GET /v1/activities filtered by ownerTypeId and ownerId
FieldpingOffsets Typenumber[] Requiredno DescriptionReminders: integer minutes before the deadline, not less than 0
FieldcolorId Typestring Requiredno DescriptionActivity color: default or 1 to 7. The color cannot be changed after creation

The body accepts no other fields: an unknown field is rejected with 400 INVALID_PARAMS.

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/activity-todos" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ownerTypeId": 2,
    "ownerId": 8845,
    "deadline": "2026-11-02T12:00:00+00:00",
    "title": "Review the contract",
    "description": "Call the customer"
  }'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/activity-todos" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ownerTypeId": 2,
    "ownerId": 8845,
    "deadline": "2026-11-02T12:00:00+00:00",
    "title": "Review the contract",
    "description": "Call the customer"
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/activity-todos', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    ownerTypeId: 2,
    ownerId: 8845,
    deadline: '2026-11-02T12:00:00+00:00',
    title: 'Review the contract',
    description: 'Call the customer',
  }),
})

const { data } = await res.json()
console.log('To-do ID:', data.id)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/activity-todos', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    ownerTypeId: 2,
    ownerId: 8845,
    deadline: '2026-11-02T12:00:00+00:00',
    title: 'Review the contract',
    description: 'Call the customer',
  }),
})

const { data } = await res.json()

Response fields

The response is HTTP 201 with the created activity, read back after the write. The shape is the same as in GET /v1/activities/:id.

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue on success
Fielddata Typeobject DescriptionThe created activity, all fields: Activity fields
Fielddata.id Typenumber DescriptionActivity ID. Use it to read the activity via GET /v1/activities/:id and to change it via PATCH /v1/activity-todos/:id
Fielddata.providerId Typestring DescriptionAlways CRM_TODO
Fielddata.subject Typestring DescriptionTitle from the request's title field
Fielddata.deadline Typestring DescriptionActivity deadline in UTC
Fielddata.associatedEntityId Typenumber DescriptionParent activity ID from parentActivityId, or 0 without a parent
Fielddata.completed Typeboolean DescriptionWhether the activity is completed. false for a new activity

Response example

Main fields are shown. Full list: Activity fields.

JSON 
{
  "success": true,
  "data": {
    "id": 8379,
    "ownerId": 8845,
    "ownerTypeId": 2,
    "typeId": 6,
    "providerId": "CRM_TODO",
    "providerTypeId": "TODO",
    "associatedEntityId": 0,
    "subject": "Review the contract",
    "deadline": "2026-11-02T12:00:00.000Z",
    "completed": false,
    "status": 1,
    "responsibleId": 1317,
    "description": "Call the customer"
  }
}

Error response example

400 — the parent activity belongs to a different CRM object:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Parent activity is not bound to the requested CRM owner"
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS DescriptionBody validation failed: ownerTypeId, ownerId or deadline is missing, an ID field is not a positive integer, title or description is not a string, the deadline is not in ISO 8601 format, the color is outside the palette, pingOffsets is not an array of non-negative integers, or the body has an unknown field
HTTP400 CodeINVALID_PARAMS DescriptionThe parent activity from parentActivityId belongs to a different CRM object
HTTP400 CodeMISSING_REQUIRED_FIELDS DescriptionThe request body is not a JSON object
HTTP422 CodeACTIVITY_PARENT_NOT_APPLIED DescriptionThe activity was created, but without the link to the parent. The new activity ID is in error.createdId: check it via GET /v1/activities/:id along with the parent activity instead of sending POST again, since a retry creates a second activity
HTTP404 CodeENTITY_NOT_FOUND DescriptionThe activity in parentActivityId does not exist. No activity is created
HTTP502 CodeBITRIX_ERROR DescriptionThe parent activity's bindings could not be read, or Bitrix24 did not return the created activity's ID. In the second case, check the object's activity list before retrying the request
HTTP502 CodeACTIVITY_CREATED_READ_FAILED DescriptionThe activity was created, but reading it back after the write failed. The new activity ID is in error.createdId: check it via GET /v1/activities/:id instead of sending POST again, since a retry creates a second activity
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is read-only
HTTP403 CodeSCOPE_DENIED DescriptionThe key has no crm scope
HTTP401 CodeTOKEN_MISSING DescriptionThe key has no Bitrix24 connection

Full list of common API errors: Errors.

Known specifics

The parent is completed. The activity specified in parentActivityId becomes completed once the new one is created: completed: true, status: 2.

See also