## List call lists

`GET /v1/call-lists`

Returns the Bitrix24 account's call lists in pages of 50 records, with filtering, sorting and field selection.

## Parameters

All parameters are optional.

| Parameter | Type | Default | Description |
|----------|-----|-----------|----------|
| `filter` (query) | object | — | Filter by `id`, `dateCreate`, `createdById`, `webformId`, `entityTypeId`. Operators: `$eq`, `$gt`, `$lt`, `$gte`, `$lte`, `$in`, or a prefix before the field name: `=`, `>`, `<`, `>=`, `<=`, `@`. The `@` prefix and an array of values work as `$in`. Use `$in` itself in the JSON form of the filter; in the bracket form pass an array instead: `filter[id][]=15`.<br>[Filtering syntax](/docs/filtering). Example: `?filter[entityTypeId]=3`, `?filter[id][$gte]=15`, `?filter[>=id]=15`, `?filter[id][]=15&filter[id][]=17` |
| `sort` (query) | string | — | Comma-separated sort fields; a `-` before the name sorts descending. The same five fields as in `filter` are available. Example: `?sort=-id` |
| `select` (query) | string | all five fields | Comma-separated fields or `*`. The same five fields are available. The response contains only the listed fields. Example: `?select=id,dateCreate` |
| `offset` (query) | number | `0` | Page offset: `0` or a multiple of 50 — `50`, `100` and so on |

**Pagination.** A page holds up to 50 records; the page size is fixed. Request the next page with `offset` increased by 50. `meta.hasMore` is `true` when the page is full and does not guarantee that the next page is non-empty. A page past the end comes back with an empty `data` array and `hasMore: false`.

**Common requests.**

- Contact lists, newest first, ID and date only: `GET /v1/call-lists?filter[entityTypeId]=3&sort=-id&select=id,dateCreate`
- Several lists by ID in the JSON form of the filter: `GET /v1/call-lists?filter={"id":{"$in":[15,17]}}&select=id`. URL-encode the `filter` value.

One filter form per request: either brackets or a JSON object.

## Examples

### curl — personal key

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

### curl — OAuth application

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

const { success, data, meta } = await res.json()
console.log(`Lists on the page: ${data.length}, page full: ${meta.hasMore}`)
```

### JavaScript — OAuth application

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/call-lists', {
  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 | Call lists on the current page |
| `data[].id` | number | Call list ID |
| `data[].dateCreate` | string | Creation date as a `YYYY-MM-DD HH:mm:ss` string in the Bitrix24 account's local time, without a time zone |
| `data[].createdById` | number | Who created the list. User list: [`GET /v1/users`](/docs/entities/users) |
| `data[].webformId` | number \| null | CRM form linked to the list, or `null`. Form list: [`GET /v1/crm-forms`](/docs/entities/crm-forms) |
| `data[].entityTypeId` | number | Participant type as a number: `1` — lead, `2` — deal, `3` — contact, `4` — company |
| `meta.offset` | number | Offset of the current page |
| `meta.limit` | number | Page size, always `50` |
| `meta.hasMore` | boolean | `true` if the page holds exactly 50 records |

## Response example

The example shows three lists from the page.

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

## Error response example

400 — filter on a field that call lists do not have:

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

## Errors

| HTTP | Code | Description |
|------|-----|----------|
| 400 | `UNKNOWN_FILTER_FIELD` | A field in `filter` is not one of `id`, `dateCreate`, `createdById`, `webformId`, `entityTypeId` |
| 400 | `INVALID_FILTER_OPERATOR` | An operator outside `$eq`, `$gt`, `$lt`, `$gte`, `$lte`, `$in`, an empty operator object, or a field prefix combined with an operator object |
| 400 | `INVALID_FILTER_SHAPE` | `filter` is given neither in brackets nor as a JSON object, a condition value is an object or an array of arrays, a value and operators or array elements and operators are mixed for one field, or an array element index exceeds 999 |
| 400 | `INVALID_FILTER` | Both `filter` forms in one request, or the same condition passed twice |
| 400 | `INVALID_DUPLICATE_FILTER_FIELD` | Two conditions reduce to one, for example `filter[>=id]=15` and `filter[id][$gte]=20` |
| 400 | `UNKNOWN_SORT_FIELD` | A field in `sort` is not one of the five available |
| 400 | `INVALID_SORT_TYPE` | `sort` is not passed as a string, for example `sort[id]=desc` |
| 400 | `UNKNOWN_FIELD` | A field in `select` is not one of the five available |
| 400 | `INVALID_PARAMS` | A parameter other than `filter`, `sort`, `select`, `offset` is passed, for example `limit`. The bracket notation `filter[id][$in][]=…` gets the same response: for a list of values pass `filter[id][]=…` or use the JSON form of the filter |
| 400 | `INVALID_PARAMS` | `offset` is negative, fractional or not a multiple of 50 |
| 400 | `INVALID_PARAMS` | `sort` or `select` is passed more than once, or `select` is not passed as a string |
| 422 | `BITRIX_ERROR` | Bitrix24 rejected the request. The reason is in `message` |
| 502 | `BITRIX_RESPONSE_INVALID` | The Bitrix24 response did not match the expected list structure |
| 403 | `SCOPE_DENIED` | The key lacks the `crm` scope |
| 401 | `TOKEN_MISSING` | The key has no Bitrix24 tokens configured |
| 401 | `MISSING_API_KEY` | `X-Api-Key` is not passed |

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

## See also

- [Get a call list](/docs/entities/call-lists/get)
- [Create a call list](/docs/entities/call-lists/create)
- [Call list participants](/docs/entities/call-lists/items)
- [Filtering syntax](/docs/filtering)
- [Entity reference](/docs/entity-api)
- [Limits and optimization](/docs/optimization)