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

CRM cards by phone

GET /v1/calls/crm-entities

Scope: telephony | Authentication: X-Api-Key | URL: https://vibecode.bitrix24.com/v1

GET /v1/calls/crm-entities?phone=%2B10000000000 calls telephony.externalCall.searchCrmEntities with PHONE_NUMBER. Empty phone: 400 MISSING_REQUIRED_FIELDS. Response is an array of cards and assigned employees, normalized to camelCase: crmEntityType, crmEntityId, assignedById and other upstream fields. No match: empty array. Use for call routing. Duplicate search calls crm.duplicate.findbycomm and returns duplicate IDs rather than cards and assigned employees.

Errors: 400 invalid parameters; 401 key or token; 403 scope, Bitrix24 permissions or READONLY writes; 422 upstream refusal; 429 limits; 502 unavailable Bitrix24 account; 503 timeout or freeze.

Request parameters

Field Type Required Meaning
phone string yes Nonempty phone number. Encode + as %2B in a query string.

Response fields

Field Meaning
success Boolean result
data Result described above; credentials are omitted

Examples

cURL Personal key

Terminal 
curl -X GET 'https://vibecode.bitrix24.com/v1/calls/crm-entities?phone=%2B10000000000' \
  -H 'X-Api-Key: FAKE_VIBE_API_KEY'

cURL OAuth

Terminal 
curl -X GET 'https://vibecode.bitrix24.com/v1/calls/crm-entities?phone=%2B10000000000' \
  -H 'X-Api-Key: FAKE_VIBE_API_KEY' \
  -H 'Authorization: Bearer FAKE_APP_SESSION_TOKEN'

JavaScript Personal key

javascript 
const response = await fetch('https://vibecode.bitrix24.com/v1/calls/crm-entities?phone=%2B10000000000', {
  method: 'GET',
  headers: {"X-Api-Key": "FAKE_VIBE_API_KEY"},
});
console.log(await response.json());

JavaScript OAuth

javascript 
const response = await fetch('https://vibecode.bitrix24.com/v1/calls/crm-entities?phone=%2B10000000000', {
  method: 'GET',
  headers: {"X-Api-Key": "FAKE_VIBE_API_KEY", "Authorization": "Bearer FAKE_APP_SESSION_TOKEN"},
});
console.log(await response.json());

Observed on the test account 2026-10-02; the example shows nonsecret response fields.

JSON 
{
  "success": true,
  "data": []
}

Errors

HTTP Code
400 INVALID_PARAMS / MISSING_REQUIRED_FIELDS / READONLY_FIELD
401 MISSING_API_KEY / INVALID_API_KEY / TOKEN_MISSING
403 SCOPE_DENIED / WRITE_BLOCKED_READONLY_KEY / BITRIX_ACCESS_DENIED
422 BITRIX_ERROR
429 RATE_LIMITED
502 BITRIX_UNAVAILABLE
503 BITRIX_TIMEOUT

Error reference

403 when the key has no telephony scope:

JSON 
{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "This endpoint requires 'telephony' scope"
  }
}

See also

Calls

SIP