## Список обзвонов

`GET /v1/call-lists`

Возвращает списки обзвона портала страницами по 50 записей с фильтрацией, сортировкой и выбором полей.

## Параметры

Все параметры необязательные.

| Параметр | Тип | По умолч. | Описание |
|----------|-----|-----------|----------|
| `filter` (query) | object | — | Фильтрация по полям `id`, `dateCreate`, `createdById`, `webformId`, `entityTypeId`. Операторы — `$eq`, `$gt`, `$lt`, `$gte`, `$lte`, `$in` либо префикс перед именем поля: `=`, `>`, `<`, `>=`, `<=`, `@`. Префикс `@` и массив значений работают как `$in`. Сам `$in` указывайте в JSON-форме фильтра, в квадратных скобках вместо него передайте массив: `filter[id][]=15`.<br>[Синтаксис фильтрации](/docs/filtering). Пример: `?filter[entityTypeId]=3`, `?filter[id][$gte]=15`, `?filter[>=id]=15`, `?filter[id][]=15&filter[id][]=17` |
| `sort` (query) | string | — | Поля сортировки через запятую, `-` перед именем — по убыванию. Доступны те же пять полей, что у `filter`. Пример: `?sort=-id` |
| `select` (query) | string | все пять полей | Поля через запятую или `*`. Доступны те же пять полей. В ответе приходят только перечисленные поля. Пример: `?select=id,dateCreate` |
| `offset` (query) | number | `0` | Смещение страницы: `0` или число, кратное 50 — `50`, `100` и далее |

**Пагинация.** Страница содержит до 50 записей, размер страницы фиксирован. Следующую страницу запрашивайте с `offset`, увеличенным на 50. `meta.hasMore` равен `true`, когда страница заполнена целиком, и не гарантирует, что следующая страница непустая. Страница за концом приходит с пустым массивом `data` и `hasMore: false`.

**Типовые запросы.**

- Списки контактов, новые сверху, только идентификатор и дата: `GET /v1/call-lists?filter[entityTypeId]=3&sort=-id&select=id,dateCreate`
- Несколько списков по идентификаторам в JSON-форме фильтра: `GET /v1/call-lists?filter={"id":{"$in":[15,17]}}&select=id`. Значение `filter` передаётся в URL-кодировке.

Одна форма фильтра на запрос: либо квадратные скобки, либо JSON-объект.

## Примеры

### curl — личный ключ

```bash
curl "https://vibecode.bitrix24.tech/v1/call-lists" \
  -H "X-Api-Key: YOUR_API_KEY"
```

### curl — OAuth-приложение

```bash
curl "https://vibecode.bitrix24.tech/v1/call-lists" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"
```

### JavaScript — личный ключ

```javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/call-lists', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data, meta } = await res.json()
console.log(`Списков на странице: ${data.length}, страница полная: ${meta.hasMore}`)
```

### JavaScript — OAuth-приложение

```javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/call-lists', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { success, data, meta } = await res.json()
```

## Поля ответа

| Поле | Тип | Описание |
|------|-----|----------|
| `success` | boolean | Всегда `true` при успехе |
| `data` | array | Списки обзвона на текущей странице |
| `data[].id` | number | Идентификатор списка обзвона |
| `data[].dateCreate` | string | Дата создания строкой `YYYY-MM-DD HH:mm:ss` во времени портала, без часового пояса |
| `data[].createdById` | number | Кто создал список. Список пользователей: [`GET /v1/users`](/docs/entities/users) |
| `data[].webformId` | number \| null | CRM-форма, привязанная к списку, или `null`. Список форм: [`GET /v1/crm-forms`](/docs/entities/crm-forms) |
| `data[].entityTypeId` | number | Тип участников числом: `1` — лид, `2` — сделка, `3` — контакт, `4` — компания |
| `meta.offset` | number | Смещение текущей страницы |
| `meta.limit` | number | Размер страницы, всегда `50` |
| `meta.hasMore` | boolean | `true`, если на странице ровно 50 записей |

## Пример ответа

Показаны три списка из страницы ответа.

```json
{
  "success": true,
  "data": [
    {
      "id": 5,
      "dateCreate": "2021-11-01 18:22:04",
      "createdById": 131,
      "webformId": null,
      "entityTypeId": 2
    },
    {
      "id": 11,
      "dateCreate": "2025-07-14 08:41:08",
      "createdById": 29,
      "webformId": 1,
      "entityTypeId": 3
    },
    {
      "id": 17,
      "dateCreate": "2026-10-13 09:42:01",
      "createdById": 1317,
      "webformId": null,
      "entityTypeId": 3
    }
  ],
  "meta": {
    "offset": 0,
    "limit": 50,
    "hasMore": false
  }
}
```

## Пример ответа при ошибке

400 — фильтр по полю, которого нет у списка обзвона:

```json
{
  "success": false,
  "error": {
    "code": "UNKNOWN_FILTER_FIELD",
    "message": "Unknown call-list filter field"
  }
}
```

## Ошибки

| HTTP | Код | Описание |
|------|-----|----------|
| 400 | `UNKNOWN_FILTER_FIELD` | Поле в `filter` не входит в `id`, `dateCreate`, `createdById`, `webformId`, `entityTypeId` |
| 400 | `INVALID_FILTER_OPERATOR` | Оператор вне списка `$eq`, `$gt`, `$lt`, `$gte`, `$lte`, `$in`, пустой объект операторов или префикс поля вместе с объектом операторов |
| 400 | `INVALID_FILTER_SHAPE` | `filter` не задан ни квадратными скобками, ни JSON-объектом, значение условия — объект или массив массивов, для одного поля смешаны значение и операторы либо элементы массива и операторы, индекс элемента массива больше 999 |
| 400 | `INVALID_FILTER` | В одном запросе обе формы `filter` или одно и то же условие передано дважды |
| 400 | `INVALID_DUPLICATE_FILTER_FIELD` | Два условия сводятся к одному, например `filter[>=id]=15` и `filter[id][$gte]=20` |
| 400 | `UNKNOWN_SORT_FIELD` | Поле в `sort` не входит в пять доступных |
| 400 | `INVALID_SORT_TYPE` | `sort` передан не строкой, например `sort[id]=desc` |
| 400 | `UNKNOWN_FIELD` | Поле в `select` не входит в пять доступных |
| 400 | `INVALID_PARAMS` | Передан параметр вне `filter`, `sort`, `select`, `offset`, например `limit`. Так же отвечает скобочная запись `filter[id][$in][]=…`: для списка значений передайте `filter[id][]=…` или JSON-форму фильтра |
| 400 | `INVALID_PARAMS` | `offset` отрицательный, дробный или не кратен 50 |
| 400 | `INVALID_PARAMS` | `sort` или `select` передан больше одного раза, `select` передан не строкой |
| 422 | `BITRIX_ERROR` | Битрикс24 отклонил запрос. Текст причины — в `message` |
| 502 | `BITRIX_RESPONSE_INVALID` | Ответ Битрикс24 не совпал с ожидаемой структурой списка |
| 403 | `SCOPE_DENIED` | Ключу не хватает скоупа `crm` |
| 401 | `TOKEN_MISSING` | У ключа нет настроенных токенов Битрикс24 |
| 401 | `MISSING_API_KEY` | Не передан `X-Api-Key` |

Полный список общих ошибок API — [Ошибки](/docs/errors).

## Смотрите также

- [Получить список](/docs/entities/call-lists/get)
- [Создать список](/docs/entities/call-lists/create)
- [Участники списка](/docs/entities/call-lists/items)
- [Синтаксис фильтрации](/docs/filtering)
- [Справочник сущностей](/docs/entity-api)
- [Лимиты и оптимизация](/docs/optimization)