## 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 |
|------|-----|:-----:|----------|
| `entityType` | string | yes | Participant type: `CONTACT` — contacts, `COMPANY` — companies |
| `entities` | number[] | yes | Participant IDs, a nonempty array of positive integers. All IDs must be of the type set in `entityType`. Contacts: [`GET /v1/contacts`](/docs/entities/contacts/list), companies: [`GET /v1/companies`](/docs/entities/companies/list) |
| `webformId` | number | no | CRM form to link to the list. Form list: [`GET /v1/crm-forms`](/docs/entities/crm-forms/list) |

Field values and relations to other entities — [call list key fields](/docs/entities/call-lists#key-fields).

## Examples

### curl — personal key

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

```bash
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 |
|------|-----|----------|
| `success` | boolean | `true` on successful creation |
| `data` | object | Creation result |
| `data.id` | number | ID of the created list. Needed for [list participants](/docs/entities/call-lists/items) and [participant replacement](/docs/entities/call-lists/replace) |
| `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 |

The list itself with its creation date and form link — [`GET /v1/call-lists/:id`](/docs/entities/call-lists/get).

## 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 |
|------|-----|----------|
| 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` |
| 400 | `UNKNOWN_FIELD` | The body has a field other than `entityType`, `entities` and `webformId`. The message contains `Supported write fields` |
| 400 | `INVALID_PARAMS` | `entityType` has any other value, for example `LEAD`. The message contains `entityType must be CONTACT or COMPANY` |
| 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` |
| 400 | `INVALID_PARAMS` | `webformId` is not a positive integer. The message contains `webformId must be a positive safe integer` |
| 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` |
| 422 | `BITRIX_ERROR` | No CRM form with this `webformId` exists. The response has `b24Code: "WEBFORM_ERROR"`. The message contains `Incorrect webform id` |
| 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` |
| 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](/docs/entities/call-lists/list) |
| 403 | `WRITE_BLOCKED_READONLY_KEY` | The key is read-only, creation is unavailable |
| 403 | `SCOPE_DENIED` | The key lacks the `crm` scope |
| 401 | `MISSING_API_KEY` | `X-Api-Key` is not passed |
| 401 | `TOKEN_MISSING` | The key has no configured Bitrix24 tokens |

Full list of common API errors — [Errors](/docs/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](/docs/entities/activities) with the filter `filter[providerId]=CALL_LIST`.

## See also

- [List call lists](/docs/entities/call-lists/list)
- [Get a call list](/docs/entities/call-lists/get)
- [Replace participants](/docs/entities/call-lists/replace)
- [List participants](/docs/entities/call-lists/items)
- [Participant statuses](/docs/entities/call-lists/statuses)
- Related entities: [Contacts](/docs/entities/contacts), [Companies](/docs/entities/companies), [CRM forms](/docs/entities/crm-forms), [Activities](/docs/entities/activities)