# Leads

CRM lead management: create, retrieve, update, delete, filter.

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

A lead can originate from a [CRM form](./crm-forms.md). Its ID and fields are available via `GET /v1/crm-forms/:id`.

## Operations

- [Create lead](./leads/create.md) — `POST /v1/leads`
- [List leads](./leads/list.md) — `GET /v1/leads`
- [Get lead](./leads/get.md) — `GET /v1/leads/:id`
- [Update lead](./leads/update.md) — `PATCH /v1/leads/:id`
- [Delete lead](./leads/delete.md) — `DELETE /v1/leads/:id`
- [Move to another status](./leads/move.md) — `POST /v1/leads/:id/move`
- [Convert lead](./leads/convert.md) — `POST /v1/leads/:id/convert`
- [Search leads](./leads/search.md) — `POST /v1/leads/search`
- [Lead fields](./leads/fields.md) — `GET /v1/leads/fields`
- [Aggregate leads](./leads/aggregate.md) — `POST /v1/leads/aggregate`
- [Get products](./leads/products-get.md) — `GET /v1/leads/:id/products`
- [Set products](./leads/products-set.md) — `PUT /v1/leads/:id/products`
- [Add product](./leads/products-add.md) — `POST /v1/leads/:id/products`
- [Delete product](./leads/products-delete.md) — `DELETE /v1/leads/:id/products/:rowId`
- [Get product](./leads/products-get-single.md) — `GET /v1/leads/:id/products/:rowId`
- [Update product](./leads/products-update.md) — `PATCH /v1/leads/:id/products/:rowId`
- [Product fields](./leads/products-fields.md) — `GET /v1/leads/:id/products/fields`
- [List lead contacts](./leads/contacts-list.md) — `GET /v1/leads/:id/contacts`
- [Replace lead contacts](./leads/contacts-set.md) — `PUT /v1/leads/:id/contacts`
- [Link a contact to a lead](./leads/contacts-create.md) — `POST /v1/leads/:id/contacts`
- [Unlink a contact from a lead](./leads/contacts-delete-delete.md) — `DELETE /v1/leads/:id/contacts/:relatedId`
- [Unlink all contacts from a lead](./leads/contacts-delete.md) — `DELETE /v1/leads/:id/contacts`
- [Import records](../import.md) — `POST /v1/leads/import`

## Key fields

| Field | Description |
|------|----------|
| `id` | Lead ID. Source: [List leads](./leads/list.md) |
| `title` | Lead title |
| `name` | Customer name |
| `stageId` | Lead status. Source: [List of dictionaries](./statuses/list.md) with `entityId=STATUS` |
| `opportunity` | Lead amount |
| `currencyId` | Amount currency. Source: [List currencies](./currencies/list.md) |
| `sourceId` | Inquiry source from the [List of dictionaries](./statuses/list.md) with `entityId=SOURCE` |
| `assignedById` | Assignee. Source: [List employees](./users/list.md) |

Full list of fields — [Lead fields](./leads/fields.md).

## What to know before you start

1. Leads are disabled in Simple CRM. [CRM mode](./crm-settings/mode.md): `GET /v1/crm-settings/mode`, `1` is Classic CRM, `2` is Simple CRM.
2. On create and update, pass fields at the JSON root, without a `fields` wrapper. The format is described on the [Create lead](./leads/create.md) and [Update lead](./leads/update.md) pages.
3. In responses the status comes in `stageId`, the amount in `opportunity`, and the currency in `currencyId`. The names `statusId`, `amount` and `currency` are accepted on write as aliases for these fields. Use one name per field in a request. To set the amount using `opportunity` or `amount`, pass `isManualOpportunity: true` in the same request. Otherwise, Bitrix24 recalculates the amount from the product rows.
4. Lead products and contacts are managed by separate operations: [Get products](./leads/products-get.md) and [List lead contacts](./leads/contacts-list.md). To move from a lead to other entities, use [Convert lead](./leads/convert.md).

## Typical scenario

1. Check the [CRM mode](./crm-settings/mode.md).
2. Pick a status through the [List of dictionaries](./statuses/list.md) with `entityId=STATUS`.
3. [Create lead](./leads/create.md) with a `title`, customer data and the selected `stageId`.
4. As work progresses, [move the lead to another status](./leads/move.md).
5. Check the result through [Get lead](./leads/get.md).

## Limits

| Limit | Value |
|-------|----------|
| Maximum records per request | 5000 (`limit ≤ 5000`) |
| Automatic pagination | enabled when `limit > 50` |
| `offset` on large result sets | `limit ≤ 500` recommended when `offset ≥ 2500` |
| Batch requests | up to 50 operations in [Batch calls](/docs/batch) |
| Request rate | shared across the Vibecode API — see [Limits and optimization](/docs/optimization) |

## See also

- [Deals](./deals.md)
- [Contacts](./contacts.md)
- [CRM forms](./crm-forms.md)
- [CRM mode](./crm-settings/mode.md)
- [Import records](../import.md)