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

Replace participants

PUT /v1/call-lists/:id

Replaces all call list participants with the ones in the request and removes participants missing from it.

The body is passed in full, as when creating a list, flat at the JSON root, without a fields wrapper.

Parameters

Parameter Type Required Description
Parameterid (path) Typenumber Requiredyes DescriptionCall list ID. List: GET /v1/call-lists

Request fields (body)

Field Type Required Description
FieldentityType Typestring Requiredyes DescriptionParticipant type: CONTACT or COMPANY. Must match the list's entityType from GET /v1/call-lists/:id
Fieldentities Typenumber[] Requiredyes DescriptionThe new full list of participants, a nonempty array of positive integers. Contacts: GET /v1/contacts, companies: GET /v1/companies
FieldwebformId Typenumber Requiredno DescriptionCRM form linked to the list. Form list: GET /v1/crm-forms. If the field is omitted, the link is reset to null. To keep the form, pass the current webformId from GET /v1/call-lists/:id

Field values and relations to other entities — call list key fields.

Examples

curl — personal key

Terminal 
curl -X PUT "https://vibecode.bitrix24.com/v1/call-lists/17" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entityType": "CONTACT",
    "entities": [9, 19]
  }'

curl — OAuth application

Terminal 
curl -X PUT "https://vibecode.bitrix24.com/v1/call-lists/17" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "entityType": "CONTACT",
    "entities": [9, 19]
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/call-lists/17', {
  method: 'PUT',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    entityType: 'CONTACT',
    entities: [9, 19],
  }),
})

const { success, data } = await res.json()
console.log('skipped:', data.skipped)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/call-lists/17', {
  method: 'PUT',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    entityType: 'CONTACT',
    entities: [9, 19],
  }),
})

const { success, data } = await res.json()

Response fields

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue on successful replacement
Fielddata Typeobject DescriptionReplacement result
Fielddata.id Typenumber DescriptionList ID, matches id from the path
Fielddata.skipped Typenumber[] DescriptionIDs 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

The new participants with their statuses — GET /v1/call-lists/:id/items.

Response example

JSON 
{
  "success": true,
  "data": {
    "id": 17,
    "skipped": []
  }
}

Error response example

400 — the participant type does not match the list type:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "entityType must match the existing call list"
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS DescriptionentityType differs from the list type, for example COMPANY for a contact list. The message contains entityType must match the existing call list
HTTP400 CodeMISSING_REQUIRED_FIELDS DescriptionThe body has no entityType or entities, or the body is not a JSON object. The message contains entityType and entities are required
HTTP400 CodeUNKNOWN_FIELD DescriptionThe body has a field other than entityType, entities and webformId. The message contains Supported write fields
HTTP400 CodeINVALID_PARAMS DescriptionentityType has any other value, for example LEAD. The message contains entityType must be CONTACT or COMPANY
HTTP400 CodeINVALID_PARAMS Descriptionentities is empty, not an array, or contains a value that is not a positive integer. The message contains entities must be a nonempty list
HTTP400 CodeINVALID_PARAMS DescriptionwebformId is not a positive integer. The message contains webformId must be a positive safe integer
HTTP400 CodeINVALID_PARAMS Descriptionid in the path is not a positive integer. The message contains id must be a positive safe integer
HTTP404 CodeENTITY_NOT_FOUND DescriptionNo list with this id exists, or it is not accessible to the key owner. The message contains Call list not found or inaccessible
HTTP422 CodeBITRIX_ERROR DescriptionNo 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
HTTP422 CodeBITRIX_ERROR DescriptionNo CRM form with this webformId exists. The response has b24Code: "WEBFORM_ERROR". The list participants do not change. The message contains Incorrect webform id
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 did not confirm the replacement. Read list participants to see the current participants. The message contains Bitrix24 did not confirm the call-list replacement
HTTP422 CodeBITRIX_ERROR DescriptionThe 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
HTTP502 CodeBITRIX_RESPONSE_INVALID DescriptionThe 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
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is read-only, so replacement is unavailable
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks the crm scope
HTTP401 CodeMISSING_API_KEY DescriptionX-Api-Key is not passed
HTTP401 CodeTOKEN_MISSING DescriptionThe key has no configured Bitrix24 tokens

Full list of common API errors — Errors.

Known specifics

A single participant is added or removed through the full participant list. Read the current participants through list participants across all pages, change the array, and pass it to entities in full.

See also