[{"data":1,"prerenderedAt":13},["ShallowReactive",2],{"docs-entities\u002Fcall-lists":3,"docs-tabs-entities\u002Fcall-lists":6},{"content":4,"lastmod":5},"# Call lists\n\nA call list collects CRM contacts or companies for a manager to call and stores the status of each participant: in progress, successful, wrong number, do not call again.\n\nBitrix24 API: `crm.calllist.list`, `crm.calllist.get`, `crm.calllist.add`, `crm.calllist.update`, `crm.calllist.items.get`, `crm.calllist.statuslist`\nScope: `crm`\n\n## Operations\n\n- [Create a call list](.\u002Fcall-lists\u002Fcreate.md) — `POST \u002Fv1\u002Fcall-lists`\n- [List call lists](.\u002Fcall-lists\u002Flist.md) — `GET \u002Fv1\u002Fcall-lists`\n- [Get a call list](.\u002Fcall-lists\u002Fget.md) — `GET \u002Fv1\u002Fcall-lists\u002F:id`\n- [Replace participants](.\u002Fcall-lists\u002Freplace.md) — `PUT \u002Fv1\u002Fcall-lists\u002F:id`\n- [List participants](.\u002Fcall-lists\u002Fitems.md) — `GET \u002Fv1\u002Fcall-lists\u002F:id\u002Fitems`\n- [Participant statuses](.\u002Fcall-lists\u002Fstatuses.md) — `GET \u002Fv1\u002Fcall-lists\u002Fstatuses`\n\n## Key fields\n\n| Field | Description |\n|------|----------|\n| `id` | Call list ID |\n| `entityType` | Participant type. On a list it is a string: `CONTACT`, `COMPANY`, and for lists built in the Bitrix24 interface also `LEAD` and `DEAL`. On a participant in [list participants](.\u002Fcall-lists\u002Fitems.md) it is a number, the same code as `entityTypeId` |\n| `entityTypeId` | The same type as a number: `1` — lead, `2` — deal, `3` — contact, `4` — company |\n| `createdById` | Who created the list. User list: [`GET \u002Fv1\u002Fusers`](\u002Fdocs\u002Fentities\u002Fusers) |\n| `webformId` | CRM form linked to the list, or `null`. Form list: [`GET \u002Fv1\u002Fcrm-forms`](\u002Fdocs\u002Fentities\u002Fcrm-forms) |\n| `dateCreate` | Creation date as a `YYYY-MM-DD HH:mm:ss` string |\n| `status` | Participant status in the list, a code from [`GET \u002Fv1\u002Fcall-lists\u002Fstatuses`](.\u002Fcall-lists\u002Fstatuses.md) |\n\nThe fields of the list itself are returned by [list call lists](.\u002Fcall-lists\u002Flist.md) and [get a call list](.\u002Fcall-lists\u002Fget.md), participant fields by [list participants](.\u002Fcall-lists\u002Fitems.md).\n\n## Before you start\n\n1. **The API creates lists of contacts and companies.** Creation and participant replacement accept `entityType` only as `CONTACT` or `COMPANY`. Reading also works with lists of leads and deals built in the Bitrix24 interface.\n2. **Every creation adds a \"Call list\" activity.** Together with the list, the Bitrix24 account gets an activity whose subject is the localized \"Call list\" label followed by `#\u003Clist ID>`, assigned to the list creator `createdById`. A repeated `POST` with the same participants creates a second list and a second activity. The activity is available in [Activities](\u002Fdocs\u002Fentities\u002Factivities) with the filter `filter[providerId]=CALL_LIST`.\n3. **Replacement overwrites all participants.** `PUT \u002Fv1\u002Fcall-lists\u002F:id` keeps only the participants you pass and removes the rest. The CRM form link is overwritten too: without `webformId` in the body it is reset to `null`.\n4. **A participant status is a dictionary code.** New participants get `IN_WORK`. To display a human-readable status name, look it up in the [status dictionary](.\u002Fcall-lists\u002Fstatuses.md) by matching the participant's `status` with the status's `statusId`.\n5. **The date has no time zone.** `dateCreate` comes as a `YYYY-MM-DD HH:mm:ss` string in the Bitrix24 account's local time, without a time zone. Convert it to the zone you need based on the account settings rather than reading it as UTC.\n6. **Pages of 50 records.** Call lists and participants are returned in fixed-size pages of 50 records. `offset` accepts only multiples of 50.\n\n## Typical scenario\n\n1. Find contacts to call: [`GET \u002Fv1\u002Fcontacts`](\u002Fdocs\u002Fentities\u002Fcontacts) with the filter you need.\n2. Create a list from their IDs: [`POST \u002Fv1\u002Fcall-lists`](.\u002Fcall-lists\u002Fcreate.md).\n3. Read participants and their statuses: [`GET \u002Fv1\u002Fcall-lists\u002F:id\u002Fitems`](.\u002Fcall-lists\u002Fitems.md).\n4. Match status codes to names: [`GET \u002Fv1\u002Fcall-lists\u002Fstatuses`](.\u002Fcall-lists\u002Fstatuses.md).\n5. If the participants changed, pass the new full participant list: [`PUT \u002Fv1\u002Fcall-lists\u002F:id`](.\u002Fcall-lists\u002Freplace.md).\n\n## Limits\n\n| Limit | Value |\n|-------|----------|\n| Call lists per page | 50, fixed |\n| Participants per page | 50, fixed |\n| `offset` | 0 or a multiple of 50 |\n| Request rate | The common Vibecode API limit — see [Limits and optimization](\u002Fdocs\u002Foptimization) |\n\n## See also\n\n- [Entity reference](\u002Fdocs\u002Fentity-api)\n- [Filtering syntax](\u002Fdocs\u002Ffiltering)\n- Related entities: [Contacts](\u002Fdocs\u002Fentities\u002Fcontacts), [Companies](\u002Fdocs\u002Fentities\u002Fcompanies), [Activities](\u002Fdocs\u002Fentities\u002Factivities), [CRM forms](\u002Fdocs\u002Fentities\u002Fcrm-forms)\n","2026-10-13",{"call-lists\u002Fcreate.md":7,"call-lists\u002Flist.md":8,"call-lists\u002Fget.md":9,"call-lists\u002Freplace.md":10,"call-lists\u002Fitems.md":11,"call-lists\u002Fstatuses.md":12},"## Create a call list\n\n`POST \u002Fv1\u002Fcall-lists`\n\nCreates a new call list from CRM contacts or companies a manager needs to call.\n\nFields are passed flat at the JSON root, without a `fields` wrapper.\n\n## Request fields (body)\n\n| Field | Type | Required | Description |\n|------|-----|:-----:|----------|\n| `entityType` | string | yes | Participant type: `CONTACT` — contacts, `COMPANY` — companies |\n| `entities` | number[] | yes | Participant IDs, a nonempty array of positive integers. All IDs must be of the type set in `entityType`. Contacts: [`GET \u002Fv1\u002Fcontacts`](\u002Fdocs\u002Fentities\u002Fcontacts\u002Flist), companies: [`GET \u002Fv1\u002Fcompanies`](\u002Fdocs\u002Fentities\u002Fcompanies\u002Flist) |\n| `webformId` | number | no | CRM form to link to the list. Form list: [`GET \u002Fv1\u002Fcrm-forms`](\u002Fdocs\u002Fentities\u002Fcrm-forms\u002Flist) |\n\nField values and relations to other entities — [call list key fields](\u002Fdocs\u002Fentities\u002Fcall-lists#key-fields).\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fcall-lists\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"entityType\": \"CONTACT\",\n    \"entities\": [9, 17]\n  }'\n```\n\n### curl — OAuth application\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fcall-lists\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"entityType\": \"CONTACT\",\n    \"entities\": [9, 17]\n  }'\n```\n\n### JavaScript — personal key\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fcall-lists', {\n  method: 'POST',\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({\n    entityType: 'CONTACT',\n    entities: [9, 17],\n  }),\n})\n\nconst { success, data } = await res.json()\nconsole.log('Call list ID:', data.id, 'skipped:', data.skipped)\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fcall-lists', {\n  method: 'POST',\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({\n    entityType: 'CONTACT',\n    entities: [9, 17],\n  }),\n})\n\nconst { success, data } = await res.json()\n```\n\n## Response fields\n\nA successful creation returns HTTP status `201 Created`.\n\n| Field | Type | Description |\n|------|-----|----------|\n| `success` | boolean | `true` on successful creation |\n| `data` | object | Creation result |\n| `data.id` | number | ID of the created list. Needed for [list participants](\u002Fdocs\u002Fentities\u002Fcall-lists\u002Fitems) and [participant replacement](\u002Fdocs\u002Fentities\u002Fcall-lists\u002Freplace) |\n| `data.skipped` | number[] | IDs from `entities` that are absent from the list when it is read back after creation on behalf of the key owner. An empty array means the list contains all passed participants |\n\nThe list itself with its creation date and form link — [`GET \u002Fv1\u002Fcall-lists\u002F:id`](\u002Fdocs\u002Fentities\u002Fcall-lists\u002Fget).\n\n## Response example\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"id\": 17,\n    \"skipped\": []\n  }\n}\n```\n\n## Error response example\n\n422 — no participant with this ID exists in CRM:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"BITRIX_ERROR\",\n    \"message\": \"Incorrect entities id\",\n    \"b24Code\": \"ENTITY_ERROR\"\n  }\n}\n```\n\n## Errors\n\n| HTTP | Code | Description |\n|------|-----|----------|\n| 400 | `MISSING_REQUIRED_FIELDS` | The body has no `entityType` or `entities`, or the body is not a JSON object. The message contains `entityType and entities are required` |\n| 400 | `UNKNOWN_FIELD` | The body has a field other than `entityType`, `entities` and `webformId`. The message contains `Supported write fields` |\n| 400 | `INVALID_PARAMS` | `entityType` has any other value, for example `LEAD`. The message contains `entityType must be CONTACT or COMPANY` |\n| 400 | `INVALID_PARAMS` | `entities` is empty, not an array, or contains a value that is not a positive integer. The message contains `entities must be a nonempty list` |\n| 400 | `INVALID_PARAMS` | `webformId` is not a positive integer. The message contains `webformId must be a positive safe integer` |\n| 422 | `BITRIX_ERROR` | No participant with this ID exists in CRM. The response has `b24Code: \"ENTITY_ERROR\"`. The list is not created, so a retry with corrected IDs does not produce a duplicate. The message contains `Incorrect entities id` |\n| 422 | `BITRIX_ERROR` | No CRM form with this `webformId` exists. The response has `b24Code: \"WEBFORM_ERROR\"`. The message contains `Incorrect webform id` |\n| 422 | `BITRIX_ERROR` | The verification read after creation found a participant not from `entities` or of another type. The list is already created. The message contains `participants outside the requested call-list composition` |\n| 502 | `BITRIX_RESPONSE_INVALID` | Bitrix24 did not return the ID of the new list, or returned participants in an unexpected structure during the verification read. The list may already exist: before retrying, check the existing lists with [list call lists](\u002Fdocs\u002Fentities\u002Fcall-lists\u002Flist) |\n| 403 | `WRITE_BLOCKED_READONLY_KEY` | The key is read-only, creation is unavailable |\n| 403 | `SCOPE_DENIED` | The key lacks the `crm` scope |\n| 401 | `MISSING_API_KEY` | `X-Api-Key` is not passed |\n| 401 | `TOKEN_MISSING` | The key has no configured Bitrix24 tokens |\n\nFull list of common API errors — [Errors](\u002Fdocs\u002Ferrors).\n\n## Known specifics\n\n**Every call creates a new list and a \"Call list\" activity.** A repeated request with the same participants does not find the previous list but creates a second one, together with a second \"Call list\" activity whose subject ends with `#\u003Clist ID>`. Call list activities are available in [Activities](\u002Fdocs\u002Fentities\u002Factivities) with the filter `filter[providerId]=CALL_LIST`.\n\n## See also\n\n- [List call lists](\u002Fdocs\u002Fentities\u002Fcall-lists\u002Flist)\n- [Get a call list](\u002Fdocs\u002Fentities\u002Fcall-lists\u002Fget)\n- [Replace participants](\u002Fdocs\u002Fentities\u002Fcall-lists\u002Freplace)\n- [List participants](\u002Fdocs\u002Fentities\u002Fcall-lists\u002Fitems)\n- [Participant statuses](\u002Fdocs\u002Fentities\u002Fcall-lists\u002Fstatuses)\n- Related entities: [Contacts](\u002Fdocs\u002Fentities\u002Fcontacts), [Companies](\u002Fdocs\u002Fentities\u002Fcompanies), [CRM forms](\u002Fdocs\u002Fentities\u002Fcrm-forms), [Activities](\u002Fdocs\u002Fentities\u002Factivities)\n","## List call lists\n\n`GET \u002Fv1\u002Fcall-lists`\n\nReturns the Bitrix24 account's call lists in pages of 50 records, with filtering, sorting and field selection.\n\n## Parameters\n\nAll parameters are optional.\n\n| Parameter | Type | Default | Description |\n|----------|-----|-----------|----------|\n| `filter` (query) | object | — | Filter by `id`, `dateCreate`, `createdById`, `webformId`, `entityTypeId`. Operators: `$eq`, `$gt`, `$lt`, `$gte`, `$lte`, `$in`, or a prefix before the field name: `=`, `>`, `\u003C`, `>=`, `\u003C=`, `@`. 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`.\u003Cbr>[Filtering syntax](\u002Fdocs\u002Ffiltering). Example: `?filter[entityTypeId]=3`, `?filter[id][$gte]=15`, `?filter[>=id]=15`, `?filter[id][]=15&filter[id][]=17` |\n| `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` |\n| `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` |\n| `offset` (query) | number | `0` | Page offset: `0` or a multiple of 50 — `50`, `100` and so on |\n\n**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`.\n\n**Common requests.**\n\n- Contact lists, newest first, ID and date only: `GET \u002Fv1\u002Fcall-lists?filter[entityTypeId]=3&sort=-id&select=id,dateCreate`\n- Several lists by ID in the JSON form of the filter: `GET \u002Fv1\u002Fcall-lists?filter={\"id\":{\"$in\":[15,17]}}&select=id`. URL-encode the `filter` value.\n\nOne filter form per request: either brackets or a JSON object.\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fcall-lists\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\"\n```\n\n### curl — OAuth application\n\n```bash\ncurl \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fcall-lists\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\"\n```\n\n### JavaScript — personal key\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fcall-lists', {\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n  },\n})\n\nconst { success, data, meta } = await res.json()\nconsole.log(`Lists on the page: ${data.length}, page full: ${meta.hasMore}`)\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fcall-lists', {\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n  },\n})\n\nconst { success, data, meta } = await res.json()\n```\n\n## Response fields\n\n| Field | Type | Description |\n|------|-----|----------|\n| `success` | boolean | Always `true` on success |\n| `data` | array | Call lists on the current page |\n| `data[].id` | number | Call list ID |\n| `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 |\n| `data[].createdById` | number | Who created the list. User list: [`GET \u002Fv1\u002Fusers`](\u002Fdocs\u002Fentities\u002Fusers) |\n| `data[].webformId` | number \\| null | CRM form linked to the list, or `null`. Form list: [`GET \u002Fv1\u002Fcrm-forms`](\u002Fdocs\u002Fentities\u002Fcrm-forms) |\n| `data[].entityTypeId` | number | Participant type as a number: `1` — lead, `2` — deal, `3` — contact, `4` — company |\n| `meta.offset` | number | Offset of the current page |\n| `meta.limit` | number | Page size, always `50` |\n| `meta.hasMore` | boolean | `true` if the page holds exactly 50 records |\n\n## Response example\n\nThe example shows three lists from the page.\n\n```json\n{\n  \"success\": true,\n  \"data\": [\n    {\n      \"id\": 5,\n      \"dateCreate\": \"2021-11-01 18:22:04\",\n      \"createdById\": 131,\n      \"webformId\": null,\n      \"entityTypeId\": 2\n    },\n    {\n      \"id\": 11,\n      \"dateCreate\": \"2025-07-14 08:41:08\",\n      \"createdById\": 29,\n      \"webformId\": 1,\n      \"entityTypeId\": 3\n    },\n    {\n      \"id\": 17,\n      \"dateCreate\": \"2026-10-13 09:42:01\",\n      \"createdById\": 1317,\n      \"webformId\": null,\n      \"entityTypeId\": 3\n    }\n  ],\n  \"meta\": {\n    \"offset\": 0,\n    \"limit\": 50,\n    \"hasMore\": false\n  }\n}\n```\n\n## Error response example\n\n400 — filter on a field that call lists do not have:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"UNKNOWN_FILTER_FIELD\",\n    \"message\": \"Unknown call-list filter field\"\n  }\n}\n```\n\n## Errors\n\n| HTTP | Code | Description |\n|------|-----|----------|\n| 400 | `UNKNOWN_FILTER_FIELD` | A field in `filter` is not one of `id`, `dateCreate`, `createdById`, `webformId`, `entityTypeId` |\n| 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 |\n| 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 |\n| 400 | `INVALID_FILTER` | Both `filter` forms in one request, or the same condition passed twice |\n| 400 | `INVALID_DUPLICATE_FILTER_FIELD` | Two conditions reduce to one, for example `filter[>=id]=15` and `filter[id][$gte]=20` |\n| 400 | `UNKNOWN_SORT_FIELD` | A field in `sort` is not one of the five available |\n| 400 | `INVALID_SORT_TYPE` | `sort` is not passed as a string, for example `sort[id]=desc` |\n| 400 | `UNKNOWN_FIELD` | A field in `select` is not one of the five available |\n| 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 |\n| 400 | `INVALID_PARAMS` | `offset` is negative, fractional or not a multiple of 50 |\n| 400 | `INVALID_PARAMS` | `sort` or `select` is passed more than once, or `select` is not passed as a string |\n| 422 | `BITRIX_ERROR` | Bitrix24 rejected the request. The reason is in `message` |\n| 502 | `BITRIX_RESPONSE_INVALID` | The Bitrix24 response did not match the expected list structure |\n| 403 | `SCOPE_DENIED` | The key lacks the `crm` scope |\n| 401 | `TOKEN_MISSING` | The key has no Bitrix24 tokens configured |\n| 401 | `MISSING_API_KEY` | `X-Api-Key` is not passed |\n\nFull list of common API errors: [Errors](\u002Fdocs\u002Ferrors).\n\n## See also\n\n- [Get a call list](\u002Fdocs\u002Fentities\u002Fcall-lists\u002Fget)\n- [Create a call list](\u002Fdocs\u002Fentities\u002Fcall-lists\u002Fcreate)\n- [Call list participants](\u002Fdocs\u002Fentities\u002Fcall-lists\u002Fitems)\n- [Filtering syntax](\u002Fdocs\u002Ffiltering)\n- [Entity reference](\u002Fdocs\u002Fentity-api)\n- [Limits and optimization](\u002Fdocs\u002Foptimization)\n","## Get a call list\n\n`GET \u002Fv1\u002Fcall-lists\u002F:id`\n\nReturns one call list by ID, including lead and deal lists created in the Bitrix24 interface.\n\n## Parameters\n\n| Parameter | Type | Required | Description |\n|----------|-----|:-----:|----------|\n| `id` (path) | number | yes | Call list ID, a positive integer. List: [`GET \u002Fv1\u002Fcall-lists`](\u002Fdocs\u002Fentities\u002Fcall-lists\u002Flist) |\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fcall-lists\u002F17\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\"\n```\n\n### curl — OAuth application\n\n```bash\ncurl \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fcall-lists\u002F17\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\"\n```\n\n### JavaScript — personal key\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fcall-lists\u002F17', {\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n  },\n})\n\nconst { success, data } = await res.json()\nconsole.log(`List ${data.id}: participants of type ${data.entityType}`)\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fcall-lists\u002F17', {\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n  },\n})\n\nconst { success, data } = await res.json()\n```\n\n## Response fields\n\n| Field | Type | Description |\n|------|-----|----------|\n| `success` | boolean | Always `true` on success |\n| `data` | object | Call list |\n| `data.id` | number | Call list ID |\n| `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 |\n| `data.createdById` | number | Who created the list. User list: [`GET \u002Fv1\u002Fusers`](\u002Fdocs\u002Fentities\u002Fusers) |\n| `data.webformId` | number \\| null | CRM form linked to the list, or `null`. Form list: [`GET \u002Fv1\u002Fcrm-forms`](\u002Fdocs\u002Fentities\u002Fcrm-forms) |\n| `data.entityTypeId` | number | Participant type as a number: `1` — lead, `2` — deal, `3` — contact, `4` — company |\n| `data.entityType` | string | The same type as a string: `LEAD`, `DEAL`, `CONTACT`, `COMPANY` |\n\n## Response example\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"id\": 17,\n    \"dateCreate\": \"2026-10-13 09:42:01\",\n    \"createdById\": 1317,\n    \"webformId\": null,\n    \"entityTypeId\": 3,\n    \"entityType\": \"CONTACT\"\n  }\n}\n```\n\n## Error response example\n\n404 — list not found:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"ENTITY_NOT_FOUND\",\n    \"message\": \"Call list not found or inaccessible\"\n  }\n}\n```\n\n## Errors\n\n| HTTP | Code | Description |\n|------|-----|----------|\n| 404 | `ENTITY_NOT_FOUND` | No list with this `id` exists, or it is not accessible to the key owner |\n| 400 | `INVALID_PARAMS` | `id` is not a positive integer, for example `abc` or `0` |\n| 400 | `INVALID_PARAMS` | A query string parameter is passed, for example `?select=id`. The method accepts no query string parameters |\n| 422 | `BITRIX_ERROR` | Bitrix24 rejected the request. The reason is in `message` |\n| 502 | `BITRIX_RESPONSE_INVALID` | The Bitrix24 response did not match the expected list structure |\n| 403 | `SCOPE_DENIED` | The key lacks the `crm` scope |\n| 401 | `TOKEN_MISSING` | The key has no Bitrix24 tokens configured |\n| 401 | `MISSING_API_KEY` | The `X-Api-Key` header is missing |\n\nFull list of common API errors: [Errors](\u002Fdocs\u002Ferrors).\n\n## See also\n\n- [List call lists](\u002Fdocs\u002Fentities\u002Fcall-lists\u002Flist)\n- [Call list participants](\u002Fdocs\u002Fentities\u002Fcall-lists\u002Fitems)\n- [Replace participants](\u002Fdocs\u002Fentities\u002Fcall-lists\u002Freplace)\n- [Participant statuses](\u002Fdocs\u002Fentities\u002Fcall-lists\u002Fstatuses)\n- [Entity reference](\u002Fdocs\u002Fentity-api)\n","## Replace participants\n\n`PUT \u002Fv1\u002Fcall-lists\u002F:id`\n\nReplaces all call list participants with the ones in the request and removes participants missing from it.\n\nThe body is passed in full, as when creating a list, flat at the JSON root, without a `fields` wrapper.\n\n## Parameters\n\n| Parameter | Type | Required | Description |\n|----------|-----|:-----:|----------|\n| `id` (path) | number | yes | Call list ID. List: [`GET \u002Fv1\u002Fcall-lists`](\u002Fdocs\u002Fentities\u002Fcall-lists\u002Flist) |\n\n## Request fields (body)\n\n| Field | Type | Required | Description |\n|------|-----|:-----:|----------|\n| `entityType` | string | yes | Participant type: `CONTACT` or `COMPANY`. Must match the list's `entityType` from [`GET \u002Fv1\u002Fcall-lists\u002F:id`](\u002Fdocs\u002Fentities\u002Fcall-lists\u002Fget) |\n| `entities` | number[] | yes | The new full list of participants, a nonempty array of positive integers. Contacts: [`GET \u002Fv1\u002Fcontacts`](\u002Fdocs\u002Fentities\u002Fcontacts\u002Flist), companies: [`GET \u002Fv1\u002Fcompanies`](\u002Fdocs\u002Fentities\u002Fcompanies\u002Flist) |\n| `webformId` | number | no | CRM form linked to the list. Form list: [`GET \u002Fv1\u002Fcrm-forms`](\u002Fdocs\u002Fentities\u002Fcrm-forms\u002Flist). If the field is omitted, the link is reset to `null`. To keep the form, pass the current `webformId` from [`GET \u002Fv1\u002Fcall-lists\u002F:id`](\u002Fdocs\u002Fentities\u002Fcall-lists\u002Fget) |\n\nField values and relations to other entities — [call list key fields](\u002Fdocs\u002Fentities\u002Fcall-lists#key-fields).\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl -X PUT \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fcall-lists\u002F17\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"entityType\": \"CONTACT\",\n    \"entities\": [9, 19]\n  }'\n```\n\n### curl — OAuth application\n\n```bash\ncurl -X PUT \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fcall-lists\u002F17\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"entityType\": \"CONTACT\",\n    \"entities\": [9, 19]\n  }'\n```\n\n### JavaScript — personal key\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fcall-lists\u002F17', {\n  method: 'PUT',\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({\n    entityType: 'CONTACT',\n    entities: [9, 19],\n  }),\n})\n\nconst { success, data } = await res.json()\nconsole.log('skipped:', data.skipped)\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fcall-lists\u002F17', {\n  method: 'PUT',\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({\n    entityType: 'CONTACT',\n    entities: [9, 19],\n  }),\n})\n\nconst { success, data } = await res.json()\n```\n\n## Response fields\n\n| Field | Type | Description |\n|------|-----|----------|\n| `success` | boolean | `true` on successful replacement |\n| `data` | object | Replacement result |\n| `data.id` | number | List ID, matches `id` from the path |\n| `data.skipped` | number[] | IDs from `entities` that are missing from the participant list read back after the replacement on behalf of the key owner. An empty array means the list contains all passed participants |\n\nThe new participants with their statuses — [`GET \u002Fv1\u002Fcall-lists\u002F:id\u002Fitems`](\u002Fdocs\u002Fentities\u002Fcall-lists\u002Fitems).\n\n## Response example\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"id\": 17,\n    \"skipped\": []\n  }\n}\n```\n\n## Error response example\n\n400 — the participant type does not match the list type:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"INVALID_PARAMS\",\n    \"message\": \"entityType must match the existing call list\"\n  }\n}\n```\n\n## Errors\n\n| HTTP | Code | Description |\n|------|-----|----------|\n| 400 | `INVALID_PARAMS` | `entityType` differs from the list type, for example `COMPANY` for a contact list. The message contains `entityType must match the existing call list` |\n| 400 | `MISSING_REQUIRED_FIELDS` | The body has no `entityType` or `entities`, or the body is not a JSON object. The message contains `entityType and entities are required` |\n| 400 | `UNKNOWN_FIELD` | The body has a field other than `entityType`, `entities` and `webformId`. The message contains `Supported write fields` |\n| 400 | `INVALID_PARAMS` | `entityType` has any other value, for example `LEAD`. The message contains `entityType must be CONTACT or COMPANY` |\n| 400 | `INVALID_PARAMS` | `entities` is empty, not an array, or contains a value that is not a positive integer. The message contains `entities must be a nonempty list` |\n| 400 | `INVALID_PARAMS` | `webformId` is not a positive integer. The message contains `webformId must be a positive safe integer` |\n| 400 | `INVALID_PARAMS` | `id` in the path is not a positive integer. The message contains `id must be a positive safe integer` |\n| 404 | `ENTITY_NOT_FOUND` | No list with this `id` exists, or it is not accessible to the key owner. The message contains `Call list not found or inaccessible` |\n| 422 | `BITRIX_ERROR` | No participant with this ID exists in CRM. The response has `b24Code: \"ENTITIES_ERROR\"`. The list participants do not change. The message contains `Incorrect entities id` |\n| 422 | `BITRIX_ERROR` | No CRM form with this `webformId` exists. The response has `b24Code: \"WEBFORM_ERROR\"`. The list participants do not change. The message contains `Incorrect webform id` |\n| 422 | `BITRIX_ERROR` | Bitrix24 did not confirm the replacement. Read [list participants](\u002Fdocs\u002Fentities\u002Fcall-lists\u002Fitems) to see the current participants. The message contains `Bitrix24 did not confirm the call-list replacement` |\n| 422 | `BITRIX_ERROR` | The verification read after replacement found a participant that is not in `entities` or has a different type. The replacement has already been applied. The message contains `participants outside the requested call-list composition` |\n| 502 | `BITRIX_RESPONSE_INVALID` | The Bitrix24 response did not match the expected list or participant structure. If the failure happened during the verification read, the replacement has already been applied |\n| 403 | `WRITE_BLOCKED_READONLY_KEY` | The key is read-only, so replacement is unavailable |\n| 403 | `SCOPE_DENIED` | The key lacks the `crm` scope |\n| 401 | `MISSING_API_KEY` | `X-Api-Key` is not passed |\n| 401 | `TOKEN_MISSING` | The key has no configured Bitrix24 tokens |\n\nFull list of common API errors — [Errors](\u002Fdocs\u002Ferrors).\n\n## Known specifics\n\n**A single participant is added or removed through the full participant list.** Read the current participants through [list participants](\u002Fdocs\u002Fentities\u002Fcall-lists\u002Fitems) across all pages, change the array, and pass it to `entities` in full.\n\n## See also\n\n- [Create a call list](\u002Fdocs\u002Fentities\u002Fcall-lists\u002Fcreate)\n- [Get a call list](\u002Fdocs\u002Fentities\u002Fcall-lists\u002Fget)\n- [List participants](\u002Fdocs\u002Fentities\u002Fcall-lists\u002Fitems)\n- [Participant statuses](\u002Fdocs\u002Fentities\u002Fcall-lists\u002Fstatuses)\n- [List call lists](\u002Fdocs\u002Fentities\u002Fcall-lists\u002Flist)\n- Related entities: [Contacts](\u002Fdocs\u002Fentities\u002Fcontacts), [Companies](\u002Fdocs\u002Fentities\u002Fcompanies), [CRM forms](\u002Fdocs\u002Fentities\u002Fcrm-forms)\n","## List participants\n\n`GET \u002Fv1\u002Fcall-lists\u002F:id\u002Fitems`\n\nReturns call list participants in pages of 50 records, along with the current status of each participant in the call list.\n\n## Parameters\n\n| Parameter | Type | Required | Default | Description |\n|----------|-----|:-----:|-----------|----------|\n| `id` (path) | number | yes | — | Call list ID. List: [`GET \u002Fv1\u002Fcall-lists`](\u002Fdocs\u002Fentities\u002Fcall-lists\u002Flist) |\n| `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 |\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fcall-lists\u002F17\u002Fitems?offset=0\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\"\n```\n\n### curl — OAuth application\n\n```bash\ncurl \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fcall-lists\u002F17\u002Fitems?offset=0\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\"\n```\n\n### JavaScript — personal key\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fcall-lists\u002F17\u002Fitems?offset=0', {\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n  },\n})\n\nconst { success, data, meta } = await res.json()\nconsole.log(`${data.length} participants on the page, next offset ${meta.nextOffset}`)\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fcall-lists\u002F17\u002Fitems?offset=0', {\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n  },\n})\n\nconst { success, data, meta } = await res.json()\n```\n\n## Response fields\n\n| Field | Type | Description |\n|------|-----|----------|\n| `success` | boolean | Always `true` on success |\n| `data` | array | Participants on the current page |\n| `data[].id` | number | Participant ID in CRM — a contact, company or deal, depending on `entityType`. Record: [`GET \u002Fv1\u002Fcontacts\u002F:id`](\u002Fdocs\u002Fentities\u002Fcontacts\u002Fget), [`GET \u002Fv1\u002Fcompanies\u002F:id`](\u002Fdocs\u002Fentities\u002Fcompanies\u002Fget), [`GET \u002Fv1\u002Fdeals\u002F:id`](\u002Fdocs\u002Fentities\u002Fdeals\u002Fget) |\n| `data[].status` | string | Participant status code, for example `IN_WORK`. The status name is in the [status dictionary](\u002Fdocs\u002Fentities\u002Fcall-lists\u002Fstatuses), matched by `statusId` |\n| `data[].entityType` | number | Participant type as a number — the same code as the list's `entityTypeId`, see [key fields](\u002Fdocs\u002Fentities\u002Fcall-lists#key-fields): `3` — contact, `4` — company, `2` — deal. In the [get a call list](\u002Fdocs\u002Fentities\u002Fcall-lists\u002Fget) response, the field of the same name, `entityType`, is a string — `CONTACT`, `COMPANY`, `DEAL` |\n| `meta.offset` | number | Offset of the current page, as in the request |\n| `meta.limit` | number | Page size, always `50` |\n| `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 |\n\n## Response example\n\n```json\n{\n  \"success\": true,\n  \"data\": [\n    {\n      \"id\": 9,\n      \"status\": \"IN_WORK\",\n      \"entityType\": 3\n    },\n    {\n      \"id\": 17,\n      \"status\": \"IN_WORK\",\n      \"entityType\": 3\n    }\n  ],\n  \"meta\": {\n    \"offset\": 0,\n    \"limit\": 50,\n    \"nextOffset\": 50\n  }\n}\n```\n\n## Error response example\n\n404 — no call list with this ID exists:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"ENTITY_NOT_FOUND\",\n    \"message\": \"Call list not found or inaccessible\"\n  }\n}\n```\n\n## Errors\n\n| HTTP | Code | Description |\n|------|-----|----------|\n| 404 | `ENTITY_NOT_FOUND` | No call list with this `id` exists, or it is not accessible to the key owner |\n| 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 |\n| 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\" |\n| 422 | `BITRIX_ERROR` | Bitrix24 rejected the request for another reason. The reason text is in `message` |\n| 502 | `BITRIX_RESPONSE_INVALID` | Bitrix24 returned a response that could not be parsed |\n| 403 | `SCOPE_DENIED` | The key lacks the `crm` scope |\n| 401 | `TOKEN_MISSING` | The key has no configured Bitrix24 tokens |\n| 401 | `MISSING_API_KEY` | The `X-Api-Key` header is not passed |\n\nFull list of common API errors — [Errors](\u002Fdocs\u002Ferrors).\n\n## Known specifics\n\n**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.\n\n**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.\n\n## See also\n\n- [Get a call list](\u002Fdocs\u002Fentities\u002Fcall-lists\u002Fget)\n- [Participant statuses](\u002Fdocs\u002Fentities\u002Fcall-lists\u002Fstatuses)\n- [Replace participants](\u002Fdocs\u002Fentities\u002Fcall-lists\u002Freplace)\n- [Create a call list](\u002Fdocs\u002Fentities\u002Fcall-lists\u002Fcreate)\n- [Call lists](\u002Fdocs\u002Fentities\u002Fcall-lists)\n- [Limits and optimization](\u002Fdocs\u002Foptimization)\n- Related entities: [Contacts](\u002Fdocs\u002Fentities\u002Fcontacts), [Companies](\u002Fdocs\u002Fentities\u002Fcompanies), [Deals](\u002Fdocs\u002Fentities\u002Fdeals)\n","## Participant statuses\n\n`GET \u002Fv1\u002Fcall-lists\u002Fstatuses`\n\nReturns the reference list of call-list participant statuses, used to turn a participant's status code into a human-readable name.\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fcall-lists\u002Fstatuses\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\"\n```\n\n### curl — OAuth application\n\n```bash\ncurl \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fcall-lists\u002Fstatuses\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\"\n```\n\n### JavaScript — personal key\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fcall-lists\u002Fstatuses', {\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n  },\n})\n\nconst { success, data } = await res.json()\nconst statusNames = Object.fromEntries(data.map((s) => [s.statusId, s.name]))\nconsole.log(statusNames.IN_WORK)\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fcall-lists\u002Fstatuses', {\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n  },\n})\n\nconst { success, data } = await res.json()\nconst statusNames = Object.fromEntries(data.map((s) => [s.statusId, s.name]))\n```\n\n## Response fields\n\n| Field | Type | Description |\n|------|-----|----------|\n| `success` | boolean | Always `true` on success |\n| `data` | array | Participant statuses |\n| `data[].id` | number | Internal number of the reference record. Not used to match a participant — use `statusId` for that |\n| `data[].statusId` | string | Status code: `IN_WORK`, `SUCCESS`, `WRONG_NUMBER`, `STOP_CALLING`. Matches the participant's `status` field from [`GET \u002Fv1\u002Fcall-lists\u002F:id\u002Fitems`](\u002Fdocs\u002Fentities\u002Fcall-lists\u002Fitems) |\n| `data[].name` | string | Human-readable status name, for example \"In progress\". Do not use it to match a participant |\n| `data[].sort` | number | Status order in the list, ascending |\n\n## Response example\n\n```json\n{\n  \"success\": true,\n  \"data\": [\n    {\n      \"id\": 61,\n      \"name\": \"In progress\",\n      \"sort\": 10,\n      \"statusId\": \"IN_WORK\"\n    },\n    {\n      \"id\": 63,\n      \"name\": \"Successful\",\n      \"sort\": 20,\n      \"statusId\": \"SUCCESS\"\n    },\n    {\n      \"id\": 65,\n      \"name\": \"Wrong number\",\n      \"sort\": 30,\n      \"statusId\": \"WRONG_NUMBER\"\n    },\n    {\n      \"id\": 67,\n      \"name\": \"Do not call again\",\n      \"sort\": 40,\n      \"statusId\": \"STOP_CALLING\"\n    }\n  ]\n}\n```\n\n## Error response example\n\n400 — a query parameter is passed, but the method accepts none:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"INVALID_PARAMS\",\n    \"message\": \"This operation has no query parameters\"\n  }\n}\n```\n\n## Errors\n\n| HTTP | Code | Description |\n|------|-----|----------|\n| 400 | `INVALID_PARAMS` | A query string parameter is passed. The method accepts none |\n| 422 | `BITRIX_ERROR` | Bitrix24 rejected the request. The reason is in `message` |\n| 502 | `BITRIX_RESPONSE_INVALID` | Bitrix24 returned a response that could not be parsed |\n| 403 | `SCOPE_DENIED` | The key lacks the `crm` scope |\n| 401 | `TOKEN_MISSING` | The key has no Bitrix24 tokens configured |\n| 401 | `MISSING_API_KEY` | The `X-Api-Key` header is not passed |\n\nFull list of common API errors: [Errors](\u002Fdocs\u002Ferrors).\n\n## Known specifics\n\n**The reference list is shared by all call lists of the Bitrix24 account.** One call returns status names for participants of any list.\n\n## See also\n\n- [Call list participants](\u002Fdocs\u002Fentities\u002Fcall-lists\u002Fitems)\n- [List call lists](\u002Fdocs\u002Fentities\u002Fcall-lists\u002Flist)\n- [Get a call list](\u002Fdocs\u002Fentities\u002Fcall-lists\u002Fget)\n- [Call lists](\u002Fdocs\u002Fentities\u002Fcall-lists)\n",1794739324119]