# Call lists

A call list collects CRM contacts or companies for a manager to call and stores the status of each participant: in progress, successful, wrong number, do not call again.

Bitrix24 API: `crm.calllist.list`, `crm.calllist.get`, `crm.calllist.add`, `crm.calllist.update`, `crm.calllist.items.get`, `crm.calllist.statuslist`
Scope: `crm`

## Operations

- [Create a call list](./call-lists/create.md) — `POST /v1/call-lists`
- [List call lists](./call-lists/list.md) — `GET /v1/call-lists`
- [Get a call list](./call-lists/get.md) — `GET /v1/call-lists/:id`
- [Replace participants](./call-lists/replace.md) — `PUT /v1/call-lists/:id`
- [List participants](./call-lists/items.md) — `GET /v1/call-lists/:id/items`
- [Participant statuses](./call-lists/statuses.md) — `GET /v1/call-lists/statuses`

## Key fields

| Field | Description |
|------|----------|
| `id` | Call list ID |
| `entityType` | Participant type. On a list it is a string: `CONTACT`, `COMPANY`, and for lists built in the Bitrix24 interface also `LEAD` and `DEAL`. On a participant in [list participants](./call-lists/items.md) it is a number, the same code as `entityTypeId` |
| `entityTypeId` | The same type as a number: `1` — lead, `2` — deal, `3` — contact, `4` — company |
| `createdById` | Who created the list. User list: [`GET /v1/users`](/docs/entities/users) |
| `webformId` | CRM form linked to the list, or `null`. Form list: [`GET /v1/crm-forms`](/docs/entities/crm-forms) |
| `dateCreate` | Creation date as a `YYYY-MM-DD HH:mm:ss` string |
| `status` | Participant status in the list, a code from [`GET /v1/call-lists/statuses`](./call-lists/statuses.md) |

The fields of the list itself are returned by [list call lists](./call-lists/list.md) and [get a call list](./call-lists/get.md), participant fields by [list participants](./call-lists/items.md).

## Before you start

1. **The API creates lists of contacts and companies.** Creation and participant replacement accept `entityType` only as `CONTACT` or `COMPANY`. Reading also works with lists of leads and deals built in the Bitrix24 interface.
2. **Every creation adds a "Call list" activity.** Together with the list, the Bitrix24 account gets an activity whose subject is the localized "Call list" label followed by `#<list ID>`, assigned to the list creator `createdById`. A repeated `POST` with the same participants creates a second list and a second activity. The activity is available in [Activities](/docs/entities/activities) with the filter `filter[providerId]=CALL_LIST`.
3. **Replacement overwrites all participants.** `PUT /v1/call-lists/:id` keeps only the participants you pass and removes the rest. The CRM form link is overwritten too: without `webformId` in the body it is reset to `null`.
4. **A participant status is a dictionary code.** New participants get `IN_WORK`. To display a human-readable status name, look it up in the [status dictionary](./call-lists/statuses.md) by matching the participant's `status` with the status's `statusId`.
5. **The date has no time zone.** `dateCreate` comes as a `YYYY-MM-DD HH:mm:ss` string in the Bitrix24 account's local time, without a time zone. Convert it to the zone you need based on the account settings rather than reading it as UTC.
6. **Pages of 50 records.** Call lists and participants are returned in fixed-size pages of 50 records. `offset` accepts only multiples of 50.

## Typical scenario

1. Find contacts to call: [`GET /v1/contacts`](/docs/entities/contacts) with the filter you need.
2. Create a list from their IDs: [`POST /v1/call-lists`](./call-lists/create.md).
3. Read participants and their statuses: [`GET /v1/call-lists/:id/items`](./call-lists/items.md).
4. Match status codes to names: [`GET /v1/call-lists/statuses`](./call-lists/statuses.md).
5. If the participants changed, pass the new full participant list: [`PUT /v1/call-lists/:id`](./call-lists/replace.md).

## Limits

| Limit | Value |
|-------|----------|
| Call lists per page | 50, fixed |
| Participants per page | 50, fixed |
| `offset` | 0 or a multiple of 50 |
| Request rate | The common Vibecode API limit — see [Limits and optimization](/docs/optimization) |

## See also

- [Entity reference](/docs/entity-api)
- [Filtering syntax](/docs/filtering)
- Related entities: [Contacts](/docs/entities/contacts), [Companies](/docs/entities/companies), [Activities](/docs/entities/activities), [CRM forms](/docs/entities/crm-forms)