For AI agents: markdown of this page — /docs-content-en/entities/call-lists/list.md documentation index — /llms.txt

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
Parameterfilter (query) Typeobject Default— DescriptionFilter 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.
Filtering syntax. Example: ?filter[entityTypeId]=3, ?filter[id][$gte]=15, ?filter[>=id]=15, ?filter[id][]=15&filter[id][]=17
Parametersort (query) Typestring Default— DescriptionComma-separated sort fields; a - before the name sorts descending. The same five fields as in filter are available. Example: ?sort=-id
Parameterselect (query) Typestring Defaultall five fields DescriptionComma-separated fields or *. The same five fields are available. The response contains only the listed fields. Example: ?select=id,dateCreate
Parameteroffset (query) Typenumber Default0 DescriptionPage 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

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

curl — OAuth application

Terminal 
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
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typearray DescriptionCall lists on the current page
Fielddata[].id Typenumber DescriptionCall list ID
Fielddata[].dateCreate Typestring DescriptionCreation date as a YYYY-MM-DD HH:mm:ss string in the Bitrix24 account's local time, without a time zone
Fielddata[].createdById Typenumber DescriptionWho created the list. User list: GET /v1/users
Fielddata[].webformId Typenumber | null DescriptionCRM form linked to the list, or null. Form list: GET /v1/crm-forms
Fielddata[].entityTypeId Typenumber DescriptionParticipant type as a number: 1 — lead, 2 — deal, 3 — contact, 4 — company
Fieldmeta.offset Typenumber DescriptionOffset of the current page
Fieldmeta.limit Typenumber DescriptionPage size, always 50
Fieldmeta.hasMore Typeboolean Descriptiontrue 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
HTTP400 CodeUNKNOWN_FILTER_FIELD DescriptionA field in filter is not one of id, dateCreate, createdById, webformId, entityTypeId
HTTP400 CodeINVALID_FILTER_OPERATOR DescriptionAn operator outside $eq, $gt, $lt, $gte, $lte, $in, an empty operator object, or a field prefix combined with an operator object
HTTP400 CodeINVALID_FILTER_SHAPE Descriptionfilter 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
HTTP400 CodeINVALID_FILTER DescriptionBoth filter forms in one request, or the same condition passed twice
HTTP400 CodeINVALID_DUPLICATE_FILTER_FIELD DescriptionTwo conditions reduce to one, for example filter[>=id]=15 and filter[id][$gte]=20
HTTP400 CodeUNKNOWN_SORT_FIELD DescriptionA field in sort is not one of the five available
HTTP400 CodeINVALID_SORT_TYPE Descriptionsort is not passed as a string, for example sort[id]=desc
HTTP400 CodeUNKNOWN_FIELD DescriptionA field in select is not one of the five available
HTTP400 CodeINVALID_PARAMS DescriptionA 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
HTTP400 CodeINVALID_PARAMS Descriptionoffset is negative, fractional or not a multiple of 50
HTTP400 CodeINVALID_PARAMS Descriptionsort or select is passed more than once, or select is not passed as a string
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 rejected the request. The reason is in message
HTTP502 CodeBITRIX_RESPONSE_INVALID DescriptionThe Bitrix24 response did not match the expected list structure
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks the crm scope
HTTP401 CodeTOKEN_MISSING DescriptionThe key has no Bitrix24 tokens configured
HTTP401 CodeMISSING_API_KEY DescriptionX-Api-Key is not passed

Full list of common API errors: Errors.

See also