For AI agents: markdown of this page — /docs-content-en/telephony/crm/register.md documentation index — /llms.txt

Register a call

POST /v1/calls/register

Registers an inbound or outbound call in Bitrix24 CRM. With crmCreate: true, it creates a lead if the phone number is not found among existing entities. Returns callId for all subsequent call operations.

Request fields (body)

Parameter Type Required Default Description
userId number yes — ID of the Bitrix24 user receiving the call. A positive integer. A numeric string such as "42" is also accepted. Employees
phoneNumber string yes — Caller's phone number in international format. A non-empty string or a number. Surrounding whitespace is trimmed. A string of spaces counts as empty
type number yes — Direction: 1 — outbound, 2 — inbound, 3 — inbound with redirection, 4 — callback, 5 — informational
lineNumber string no — External line number of the application. List of lines
crmCreate boolean no false true — create a lead if the number is not found in CRM

Examples

curl — personal key

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/calls/register \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": 1,
    "phoneNumber": "+12025550123",
    "type": 2,
    "crmCreate": true
  }'

curl — OAuth application

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/calls/register \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": 1,
    "phoneNumber": "+12025550124",
    "type": 2,
    "crmCreate": true
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/calls/register', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    userId: 1,
    phoneNumber: '+12025550125',
    type: 2,
    crmCreate: true,
  }),
})

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

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/calls/register', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    userId: 1,
    phoneNumber: '+12025550126',
    type: 2,
    crmCreate: true,
  }),
})

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

Response fields

Field Type Description
callId string Call identifier for all subsequent operations
crmCreatedLead number | null ID of the created lead. null if no lead was created
crmCreatedEntities array Array of created CRM entities [{entityType, entityId}]
crmEntityType string Type of the linked CRM entity: LEAD, CONTACT, COMPANY or an empty string
crmEntityId number | null ID of the linked CRM entity. null if no entity is linked

Response example

HTTP 201 — the call is registered and a new lead is created:

JSON 
{
  "success": true,
  "data": {
    "callId": "externalCall.00b1e735843c558431be668e3687a58b.1777974304",
    "crmCreatedLead": 1001069,
    "crmCreatedEntities": [{"entityType": "LEAD", "entityId": 1001069}],
    "crmEntityType": "LEAD",
    "crmEntityId": 1001069
  }
}

Error response example

400 — required parameters are missing:

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_PARAMS",
    "message": "Required: userId (positive integer), phoneNumber (non-empty string)"
  }
}

Errors

HTTP Code Description
400 MISSING_PARAMS userId is missing or is not recognized as a positive integer, or phoneNumber is missing or is not recognized as a non-empty string or number
401 MISSING_API_KEY The X-Api-Key header is missing
401 INVALID_API_KEY Invalid API key
401 TOKEN_MISSING The API key has no Bitrix24 tokens configured
401 KEY_INACTIVE The API key is inactive or revoked
403 SCOPE_DENIED The key is missing the telephony scope
422 BITRIX_ERROR type is missing or its value is outside the 1–5 range — error.message contains Unknown TYPE
422 BITRIX_ERROR Bitrix24 returned an error (text in error.message)
429 RATE_LIMITED Request limit exceeded
502 BITRIX_UNAVAILABLE Bitrix24 is unavailable

Full list of common API errors — Errors.

Known specifics

Search for an existing CRM entity when crmCreate: true. Bitrix24 first looks for a lead, contact, or company with a matching phone number. On a match, crmEntityId points to the existing entity and crmCreatedLead stays null. A new lead is created only if there are no matches.

CRM_* fields are empty when crmCreate: false. A CRM link can be created automatically when the call is finished via POST /v1/calls/:callId/finish if Bitrix24 finds a matching number at that point.

callId is a required parameter for all subsequent steps. Save it right away: all show, hide, finish, transcription operations take callId in the request path.

See also