لوكلاء AI: ملف markdown لهذه الصفحة — /docs-content-en/calls/crm-entities.md فهرس التوثيق — /llms.txt

مقالات التوثيق متاحة حاليًا باللغة الإنجليزية فقط.

CRM cards by phone

GET /v1/calls/crm-entities

Finds CRM cards by phone number and returns the responsible employee of each card. Use it to route an incoming call to the responsible employee.

Parameters

Parameter Type Required Description
Parameterphone (query) Typestring Requiredyes DescriptionPhone number, a non-empty string. Encode the + sign in the request URL as %2B

Examples

curl — personal key

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

curl — OAuth application

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

JavaScript — personal key

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

JavaScript — OAuth application

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

Response fields

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue on success
Fielddata Typearray DescriptionCRM cards with this number. An empty array if there are no matches
Fielddata[].crmEntityType Typestring DescriptionCard type: CONTACT, COMPANY or LEAD
Fielddata[].crmEntityId Typeinteger DescriptionCard ID. To get the card: GET /v1/contacts/:id, GET /v1/companies/:id, GET /v1/leads/:id, depending on the crmEntityType value
Fielddata[].name Typestring DescriptionCompany name, or the name of the contact or lead
Fielddata[].assignedById Typeinteger DescriptionID of the responsible employee. List: GET /v1/users
Fielddata[].assignedBy Typeobject DescriptionResponsible employee data for call routing
Fielddata[].assignedBy.id Typestring DescriptionID of the responsible employee as a string
Fielddata[].assignedBy.timemanStatus Typestring DescriptionThe employee's workday status, for example EXPIRED
Fielddata[].assignedBy.userPhoneInner Typestring DescriptionThe employee's extension number
Fielddata[].assignedBy.workPhone Typestring | null DescriptionWork phone
Fielddata[].assignedBy.personalPhone Typestring | null DescriptionPersonal phone
Fielddata[].assignedBy.personalMobile Typestring | null DescriptionMobile phone

Response example

The number belongs to a contact:

JSON 
{
  "success": true,
  "data": [
    {
      "crmEntityType": "CONTACT",
      "crmEntityId": 9,
      "assignedById": 1,
      "name": "Test contact",
      "assignedBy": {
        "id": "1",
        "timemanStatus": "EXPIRED",
        "userPhoneInner": "101",
        "workPhone": "+10000000001",
        "personalPhone": null,
        "personalMobile": "+10000000002"
      }
    }
  ]
}

No matches:

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

Error response example

400 — phone is missing:

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_REQUIRED_FIELDS",
    "message": "phone is required"
  }
}

Errors

HTTP Code Description
HTTP400 CodeMISSING_REQUIRED_FIELDS DescriptionThe phone parameter is missing or empty
HTTP400 CodeINVALID_PARAMS DescriptionBitrix24 rejected the parameter value
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header is missing
HTTP401 CodeINVALID_API_KEY DescriptionThe key is not found or has been revoked
HTTP401 CodeTOKEN_MISSING DescriptionThe key has no portal tokens. An OAuth application key requires the Authorization: Bearer header
HTTP403 CodeSCOPE_DENIED DescriptionThe key has no telephony scope
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionBitrix24 denied access. For the causes, see Authorization, keys and permissions
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 rejected the request
HTTP429 CodeRATE_LIMITED DescriptionRequest rate exceeded on the Bitrix24 side
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionBitrix24 is unavailable
HTTP503 CodeBITRIX_TIMEOUT DescriptionBitrix24 did not respond in time

The full list of common API errors — Error codes.

Known specifics

Duplicate search is a different task. Duplicate search returns the IDs of matching records, but not the cards or the responsible employee. Use this method for call routing.

See also