# Task checklist

Task checklist items are a nested resource of a task. Each item has a title, a completion status, an importance flag, a sort order, members, and (optionally) a parent item for nested checklists. Base path — `/v1/tasks/:taskId/checklist`. Every operation is addressed by the task identifier `:taskId`.

Bitrix24 API: `task.checklistitem.*`
Scope: `task`

> **Why a separate resource.** Bitrix24 **does not accept** the `CHECKLIST` field inside `POST /v1/tasks` (`tasks.task.add`) — a checklist cannot be created together with the task. The only supported way to manage items is the `task.checklistitem.*` family of methods, which this resource wraps. First create the task, then add items one by one.

## Operations

- [List items](./checklist/list.md) — `GET /v1/tasks/:taskId/checklist`
- [Get an item](./checklist/get.md) — `GET /v1/tasks/:taskId/checklist/:itemId`
- [Add an item](./checklist/create.md) — `POST /v1/tasks/:taskId/checklist`
- [Update an item](./checklist/update.md) — `PATCH /v1/tasks/:taskId/checklist/:itemId`
- [Delete an item](./checklist/delete.md) — `DELETE /v1/tasks/:taskId/checklist/:itemId`
- [Mark complete](./checklist/complete.md) — `POST /v1/tasks/:taskId/checklist/:itemId/complete`
- [Reopen](./checklist/renew.md) — `POST /v1/tasks/:taskId/checklist/:itemId/renew`

## Item fields

| Field | Type | Read-only | Description |
|------|-----|:---:|---------|
| `title` | string | | Item text. **Required on creation.** If `parentId: 0`, `title` becomes the name of the new checklist |
| `sortIndex` | integer | | Sort index. The smaller the value, the higher the item appears in the list |
| `isComplete` | boolean / `Y`,`N` | | Completion status. Accepts `true`/`false` or `"Y"`/`"N"` on write. In the response — `"Y"`/`"N"` |
| `isImportant` | boolean / `Y`,`N` | | Importance flag. Same format as `isComplete` |
| `parentId` | integer | | ID of the parent item for nested checklists. **`0` creates a new checklist** in the task |
| `members` | object (request) / array (response) | | Item members — the write and read shapes differ, see "Known specifics" below |
| `id` | string | yes | Item ID |
| `taskId` | string | yes | Parent task ID |
| `createdBy` | string | yes | Item author |
| `toggledBy` | string | yes | Who last changed the completion status |
| `toggledDate` | string | yes | When the status was last changed |
| `attachments` | array | yes | Attached files (populated in the Bitrix24 UI) |

## Known specifics

- **Not every operation checks that the task exists.** Listing items and getting a single item return `422` when the task `:taskId` is absent from the Bitrix24 account. Update, mark complete, reopen and delete return success in that case and change nothing, so a success status from those four operations does not confirm that the task or the item exists.
- **Case and types in the response.** Responses arrive in camelCase (`id`, `taskId`, `sortIndex`, `isComplete`). Bitrix24 serializes numeric values as **strings** (`"id": "477"`, `"sortIndex": "2"`) — convert via `Number(value)` for arithmetic. The `isComplete` / `isImportant` flags are the strings `"Y"` / `"N"`, not booleans.
- **`members` has different shapes on write and read.** When creating or updating an item, `members` is an object of the form `{ "<userId>": { "type": "A" | "U" } }` (`A` — co-assignee, `U` — observer, employee list — [`GET /v1/users`](/docs/entities/users)). In the response (list, get) `members` is an **array** of enriched member objects: `[{ "id", "type", "name", "personalPhoto", "personalGender", "image", "isCollaber" }]`. Code that reads members from a response must not expect the request shape.
- **An item without an explicit `parentId` can land inside an existing checklist automatically.** If the task already has a checklist container (an item with `parentId: 0`), Bitrix24 assigns that container to items created without an explicit `parentId`, instead of leaving them at the top level.

## Typical scenario

1. Create a task: [`POST /v1/tasks`](../tasks/create.md).
2. (Optional) create a checklist container: [`POST /v1/tasks/:taskId/checklist`](./checklist/create.md) with `parentId: 0`.
3. Add items: [`POST /v1/tasks/:taskId/checklist`](./checklist/create.md) (one at a time).
4. Mark an item complete: [`POST /v1/tasks/:taskId/checklist/:itemId/complete`](./checklist/complete.md).
5. Check progress: [`GET /v1/tasks/:taskId/checklist`](./checklist/list.md).

## See also

- [Tasks](../tasks.md)
- [Time tracking](./time.md)
- [Task comments](/docs/entities/task-comments)
- [Employees](/docs/entities/users)
- [Limits and optimization](/docs/optimization)