## Участники списка

`GET /v1/call-lists/:id/items`

Возвращает участников списка обзвона страницами по 50 записей и текущий статус каждого участника в обзвоне.

## Параметры

| Параметр | Тип | Обяз. | По умолч. | Описание |
|----------|-----|:-----:|-----------|----------|
| `id` (path) | number | да | — | ID списка обзвона. Список: [`GET /v1/call-lists`](/docs/entities/call-lists/list) |
| `offset` (query) | number | нет | `0` | Смещение страницы: `0` или число, кратное 50. На странице до 50 участников, размер страницы фиксирован |

## Примеры

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

```bash
curl "https://vibecode.bitrix24.tech/v1/call-lists/17/items?offset=0" \
  -H "X-Api-Key: YOUR_API_KEY"
```

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

```bash
curl "https://vibecode.bitrix24.tech/v1/call-lists/17/items?offset=0" \
  -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/17/items?offset=0', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data, meta } = await res.json()
console.log(`На странице ${data.length} участников, следующее смещение ${meta.nextOffset}`)
```

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

```javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/call-lists/17/items?offset=0', {
  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 | ID участника в CRM — контакта, компании или сделки, в зависимости от `entityType`. Карточка: [`GET /v1/contacts/:id`](/docs/entities/contacts/get), [`GET /v1/companies/:id`](/docs/entities/companies/get), [`GET /v1/deals/:id`](/docs/entities/deals/get) |
| `data[].status` | string | Код статуса участника, например `IN_WORK`. Название статуса — в [справочнике статусов](/docs/entities/call-lists/statuses) по совпадению с `statusId` |
| `data[].entityType` | number | Тип участника числом — тот же код, что `entityTypeId` списка, см. [ключевые поля](/docs/entities/call-lists#ключевые-поля): `3` — контакт, `4` — компания, `2` — сделка. В [получении списка](/docs/entities/call-lists/get) одноимённое поле `entityType` приходит строкой — `CONTACT`, `COMPANY`, `DEAL` |
| `meta.offset` | number | Смещение текущей страницы, как в запросе |
| `meta.limit` | number | Размер страницы, всегда `50` |
| `meta.nextOffset` | number | Смещение следующей страницы, всегда `offset + 50`. Приходит на каждой странице и не показывает, есть ли за ней участники |

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

```json
{
  "success": true,
  "data": [
    {
      "id": 9,
      "status": "IN_WORK",
      "entityType": 3
    },
    {
      "id": 17,
      "status": "IN_WORK",
      "entityType": 3
    }
  ],
  "meta": {
    "offset": 0,
    "limit": 50,
    "nextOffset": 50
  }
}
```

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

404 — списка обзвона с таким ID нет:

```json
{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Call list not found or inaccessible"
  }
}
```

## Ошибки

| HTTP | Код | Описание |
|------|-----|----------|
| 404 | `ENTITY_NOT_FOUND` | Списка обзвона с таким `id` нет или он недоступен владельцу ключа |
| 400 | `INVALID_PARAMS` | `id` не положительное целое число, `offset` не кратен 50 или передан параметр запроса, кроме `offset` |
| 403 | `BITRIX_ACCESS_DENIED` | На запрошенной странице нет ни одного участника, доступного владельцу ключа. Так отвечает и страница за концом списка — см. «Известные особенности» |
| 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).

## Известные особенности

**Конец списка — отказ `403`.** Читайте страницы подряд со смещением `0`, `50`, `100` и так далее, пока не придёт `403 BITRIX_ACCESS_DENIED`. Этот отказ приходит на странице, где нет ни одного участника, доступного владельцу ключа. Если ключу доступны все участники списка, такая страница лежит за концом списка.

**Неполная страница встречается и в середине списка.** Страница собирается до того, как из неё убираются участники, недоступные владельцу ключа. Поэтому в `data` может прийти меньше 50 записей, а на следующей странице участники ещё будут.

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

- [Получить список](/docs/entities/call-lists/get)
- [Статусы участников](/docs/entities/call-lists/statuses)
- [Заменить состав](/docs/entities/call-lists/replace)
- [Создать список](/docs/entities/call-lists/create)
- [Обзвоны](/docs/entities/call-lists)
- [Лимиты и оптимизация](/docs/optimization)
- Связанные сущности: [Контакты](/docs/entities/contacts), [Компании](/docs/entities/companies), [Сделки](/docs/entities/deals)