# 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](../activities.md).

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

## Operations

- [Create a to-do](./todos/create.md) — `POST /v1/activity-todos`
- [Update a to-do](./todos/update.md) — `PATCH /v1/activity-todos/:id`

## Key fields

| Field | Type | Description |
|------|-----|---------|
| `ownerTypeId`, `ownerId` | number | CRM object the activity belongs to. For a deal, `ownerTypeId` is `2` and `ownerId` is an ID from [`GET /v1/deals`](/docs/entities/deals/list). Set only on create |
| `deadline` | string | Activity deadline in ISO 8601 format. Returned in UTC |
| `title` | string | Activity title. Returned in the `subject` field |
| `description` | string | Activity description |
| `responsibleId` | number | ID of the responsible user. List: [`GET /v1/users`](/docs/entities/users/list) |
| `parentActivityId` | number | ID of the activity the new one is linked to. List of the object's activities: [`GET /v1/activities`](/docs/entities/activities/list) filtered by `ownerTypeId` and `ownerId` |
| `pingOffsets` | number[] | Reminders: how many minutes before the deadline to remind |
| `colorId` | string | Activity color: `default` or `1` through `7` |

Full set of response fields — [Activity fields](/docs/entities/activities/fields).

## Before you start

1. **To-dos are read through CRM activities.** This section has no read or list operations: use [`GET /v1/activities/:id`](/docs/entities/activities/get) or [`GET /v1/activities`](/docs/entities/activities/list) with the filter `providerId=CRM_TODO`. The create and update responses have the same shape as `GET /v1/activities/:id`.
2. **Linking to a parent completes the parent.** A new activity with `parentActivityId` is linked to an existing one, and the parent activity is marked as completed. The parent must belong to the same CRM object.
3. **A completed to-do cannot be changed.** `PATCH` on it returns `422 ACTIVITY_TODO_COMPLETED`.
4. **Color is set only on create.** `PATCH` with a palette `colorId` returns `422 UNSUPPORTED_ACTIVITY_BLOCKS`; a color outside the palette returns `400 INVALID_PARAMS`.

## Typical scenario

1. Find a deal: [`GET /v1/deals`](/docs/entities/deals/list).
2. Create a to-do on the deal: [`POST /v1/activity-todos`](./todos/create.md) with `ownerTypeId: 2`, `ownerId` and `deadline`.
3. Move the deadline or change the text: [`PATCH /v1/activity-todos/:id`](./todos/update.md).
4. Check the activity: [`GET /v1/activities/:id`](/docs/entities/activities/get).
5. Complete the activity: [`POST /v1/activities/:id/complete`](/docs/entities/activities/complete).

## Limits

| Limit | Value |
|-------|----------|
| Pagination | not applicable — this section has no list operations |
| Batch calls | not supported: [`POST /v1/batch`](/docs/batch) returns `UNKNOWN_ENTITY` for `activity-todos`; call the section's endpoints one at a time |
| Rate limits | shared across the Vibecode API — see [Limits and optimization](/docs/optimization) |

## See also

- [Activities](../activities.md)
- [Complete an activity](/docs/entities/activities/complete)
- [Change an activity deadline](/docs/entities/activities/deadline)
- [Deals](../deals.md)
- [Entity reference](/docs/entity-api)