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

Create a call list

POST /v1/call-lists

Creates a new call list from CRM contacts or companies a manager needs to call.

Fields are passed flat at the JSON root, without a fields wrapper.

Request fields (body)

Field Type Required Description
FieldentityType Typestring Requiredyes DescriptionParticipant type: CONTACT — contacts, COMPANY — companies
Fieldentities Typenumber[] Requiredyes DescriptionParticipant IDs, a nonempty array of positive integers. All IDs must be of the type set in entityType. Contacts: GET /v1/contacts, companies: GET /v1/companies
FieldwebformId Typenumber Requiredno DescriptionCRM form to link to the list. Form list: GET /v1/crm-forms

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

Examples

curl — personal key

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

curl — OAuth application

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

JavaScript — personal key

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

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

JavaScript — OAuth application

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

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

Response fields

A successful creation returns HTTP status 201 Created.

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue on successful creation
Fielddata Typeobject DescriptionCreation result
Fielddata.id Typenumber DescriptionID of the created list. Needed for list participants and participant replacement
Fielddata.skipped Typenumber[] DescriptionIDs 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

The list itself with its creation date and form link — GET /v1/call-lists/:id.

Response example

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

Error response example

422 — no participant with this ID exists in CRM:

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "Incorrect entities id",
    "b24Code": "ENTITY_ERROR"
  }
}

Errors

HTTP Code Description
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
HTTP422 CodeBITRIX_ERROR DescriptionNo 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
HTTP422 CodeBITRIX_ERROR DescriptionNo CRM form with this webformId exists. The response has b24Code: "WEBFORM_ERROR". The message contains Incorrect webform id
HTTP422 CodeBITRIX_ERROR DescriptionThe 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
HTTP502 CodeBITRIX_RESPONSE_INVALID DescriptionBitrix24 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
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is read-only, creation 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

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 #<list ID>. Call list activities are available in Activities with the filter filter[providerId]=CALL_LIST.

See also