## List participants

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

Returns call list participants in pages of 50 records, along with the current status of each participant in the call list.

## Parameters

| Parameter | Type | Required | Default | Description |
|----------|-----|:-----:|-----------|----------|
| `id` (path) | number | yes | — | Call list ID. List: [`GET /v1/call-lists`](/docs/entities/call-lists/list) |
| `offset` (query) | number | no | `0` | Page offset: `0` or a multiple of 50. A page holds up to 50 participants, and the page size is fixed |

## Examples

### curl — personal key

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

### curl — OAuth application

```bash
curl "https://vibecode.bitrix24.com/v1/call-lists/17/items?offset=0" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"
```

### JavaScript — personal key

```javascript
const res = await fetch('https://vibecode.bitrix24.com/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} participants on the page, next offset ${meta.nextOffset}`)
```

### JavaScript — OAuth application

```javascript
const res = await fetch('https://vibecode.bitrix24.com/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()
```

## Response fields

| Field | Type | Description |
|------|-----|----------|
| `success` | boolean | Always `true` on success |
| `data` | array | Participants on the current page |
| `data[].id` | number | Participant ID in CRM — a contact, company or deal, depending on `entityType`. Record: [`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 | Participant status code, for example `IN_WORK`. The status name is in the [status dictionary](/docs/entities/call-lists/statuses), matched by `statusId` |
| `data[].entityType` | number | Participant type as a number — the same code as the list's `entityTypeId`, see [key fields](/docs/entities/call-lists#key-fields): `3` — contact, `4` — company, `2` — deal. In the [get a call list](/docs/entities/call-lists/get) response, the field of the same name, `entityType`, is a string — `CONTACT`, `COMPANY`, `DEAL` |
| `meta.offset` | number | Offset of the current page, as in the request |
| `meta.limit` | number | Page size, always `50` |
| `meta.nextOffset` | number | Offset of the next page, always `offset + 50`. It is returned on every page and does not indicate whether more participants follow |

## Response example

```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
  }
}
```

## Error response example

404 — no call list with this ID exists:

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

## Errors

| HTTP | Code | Description |
|------|-----|----------|
| 404 | `ENTITY_NOT_FOUND` | No call list with this `id` exists, or it is not accessible to the key owner |
| 400 | `INVALID_PARAMS` | `id` is not a positive integer, `offset` is not a multiple of 50, or a query parameter other than `offset` is passed |
| 403 | `BITRIX_ACCESS_DENIED` | The requested page has no participant accessible to the key owner. A page past the end of the list returns the same error — see "Known specifics" |
| 422 | `BITRIX_ERROR` | Bitrix24 rejected the request for another reason. The reason text is in `message` |
| 502 | `BITRIX_RESPONSE_INVALID` | Bitrix24 returned a response that could not be parsed |
| 403 | `SCOPE_DENIED` | The key lacks the `crm` scope |
| 401 | `TOKEN_MISSING` | The key has no configured Bitrix24 tokens |
| 401 | `MISSING_API_KEY` | The `X-Api-Key` header is not passed |

Full list of common API errors — [Errors](/docs/errors).

## Known specifics

**The end of the list is a `403` rejection.** Read pages in sequence with offsets `0`, `50`, `100` and so on until `403 BITRIX_ACCESS_DENIED` is returned. This rejection is returned for a page that has no participant accessible to the key owner. If the key can access all list participants, such a page lies past the end of the list.

**A partial page also occurs in the middle of the list.** A page is assembled before participants inaccessible to the key owner are removed from it. So `data` may contain fewer than 50 records while the next page still has participants.

## See also

- [Get a call list](/docs/entities/call-lists/get)
- [Participant statuses](/docs/entities/call-lists/statuses)
- [Replace participants](/docs/entities/call-lists/replace)
- [Create a call list](/docs/entities/call-lists/create)
- [Call lists](/docs/entities/call-lists)
- [Limits and optimization](/docs/optimization)
- Related entities: [Contacts](/docs/entities/contacts), [Companies](/docs/entities/companies), [Deals](/docs/entities/deals)