# Smart processes (Items)

Managing CRM smart process items: create, retrieve, update, delete, filter.

Bitrix24 API: `crm.item.*`
Scope: `crm`

The path contains a dynamic parameter `:entityTypeId` — the smart process type ID. Find available types: `GET /v1/smart-processes`.

## Operations

- [Create item](./items/create.md) — `POST /v1/items/:entityTypeId`
- [List items](./items/list.md) — `GET /v1/items/:entityTypeId`
- [Get item](./items/get.md) — `GET /v1/items/:entityTypeId/:id`
- [Update item](./items/update.md) — `PATCH /v1/items/:entityTypeId/:id`
- [Delete item](./items/delete.md) — `DELETE /v1/items/:entityTypeId/:id`
- [Search items](./items/search.md) — `POST /v1/items/:entityTypeId/search`
- [Item fields](./items/fields.md) — `GET /v1/items/:entityTypeId/fields`
- [Aggregate items](./items/aggregate.md) — `POST /v1/items/:entityTypeId/aggregate`
- [Get products](./items/products-get.md) — `GET /v1/items/:entityTypeId/:id/products`
- [Set products](./items/products-set.md) — `PUT /v1/items/:entityTypeId/:id/products`
- [Add product](./items/products-add.md) — `POST /v1/items/:entityTypeId/:id/products`
- [Delete product](./items/products-delete.md) — `DELETE /v1/items/:entityTypeId/:id/products/:rowId`
- [Get product](./items/products-get-single.md) — `GET /v1/items/:entityTypeId/:id/products/:rowId`
- [Update product](./items/products-update.md) — `PATCH /v1/items/:entityTypeId/:id/products/:rowId`
- [Product fields](./items/products-fields.md) — `GET /v1/items/:entityTypeId/:id/products/fields`

## Key fields

| Field | Description |
|------|---------|
| `title` | Item name |
| `stageId` | Stage. Format `DT{typeId}_{catId}:{stage}`. List: `GET /v1/statuses?filter[entityId]=DYNAMIC_{entityTypeId}_STAGE_{categoryId}` |
| `categoryId` | Pipeline ID. List: `GET /v1/categories/:entityTypeId` |
| `opportunity` | Amount |
| `currencyId` | Currency. List: `GET /v1/currencies` |
| `assignedById` | Responsible person. List: `GET /v1/users` |
| `companyId` / `contactId` | Links to a company and a contact. Lists: `GET /v1/companies`, `GET /v1/contacts` |

Full field list — [`GET /v1/items/:entityTypeId/fields`](./items/fields.md).

## What to know before you start

1. `entityTypeId` in the path is the smart process type ID from [`GET /v1/smart-processes`](/docs/entities/smart-processes). The values `1`, `2`, `3`, `4`, `7`, `31` are reserved for specialized APIs (`/v1/leads`, `/v1/deals`, `/v1/contacts`, `/v1/companies`, `/v1/quotes`, `/v1/invoices`) — calling them through `/v1/items` returns `400 INVALID_DYNAMIC_PARAM`.
2. The minimum to create is `title`. The remaining required fields depend on the type settings.
3. User field names use the type's internal number — `ufCrm<typeId>_*`, which is not equal to `entityTypeId`. The exact names come from [`GET /v1/items/:entityTypeId/fields`](./items/fields.md).
4. The date fields `begindate` and `closedate` are stored without time — the passed time is discarded.
5. List responses put pagination in `meta` (`meta.total`, `meta.hasMore`), not at the top level.

## Typical scenario

1. Find the smart process type: [`GET /v1/smart-processes`](/docs/entities/smart-processes) — take the `entityTypeId`.
2. Inspect the type's fields: [`GET /v1/items/:entityTypeId/fields`](./items/fields.md).
3. Create an item: [`POST /v1/items/:entityTypeId`](./items/create.md).
4. Find and filter: [`GET /v1/items/:entityTypeId`](./items/list.md) or [`POST /v1/items/:entityTypeId/search`](./items/search.md).
5. If needed — add product line items: [`GET /v1/items/:entityTypeId/:id/products`](./items/products-get.md).

## Limits

| Limit | Value |
|-------|----------|
| Maximum records per request | 5000 (`limit ≤ 5000`) |
| Auto-pagination | enabled when `limit > 50` |
| Batch requests | up to 50 operations in [`POST /v1/batch`](/docs/batch) |
| Rate limiting | shared across the Vibecode API — see [Limits and optimization](/docs/optimization) |

## User fields

Managing user fields of smart process items is a separate section: [Smart process fields](/docs/userfields/smart-processes) (`/v1/items/:entityTypeId/userfields*`).

## See also

- [Smart process types](/docs/entities/smart-processes)
- [Smart process fields](/docs/userfields/smart-processes)
- [Entity API](/docs/entity-api)
- [Filtering syntax](/docs/filtering)
- [Entities reference](/docs/entities-index)