[{"data":1,"prerenderedAt":7},["ShallowReactive",2],{"docs-calls\u002Fcrm-entities":3,"docs-tabs-calls\u002Fcrm-entities":6},{"content":4,"lastmod":5},"## CRM cards by phone\n\n`GET \u002Fv1\u002Fcalls\u002Fcrm-entities`\n\nFinds CRM cards by phone number and returns the responsible employee of each card. Use it to route an incoming call to the responsible employee.\n\n## Parameters\n\n| Parameter | Type | Required | Description |\n|----------|-----|-------|----------|\n| `phone` (query) | string | yes | Phone number, a non-empty string. Encode the `+` sign in the request URL as `%2B` |\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl 'https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fcalls\u002Fcrm-entities?phone=%2B10000000000' \\\n  -H 'X-Api-Key: YOUR_API_KEY'\n```\n\n### curl — OAuth application\n\n```bash\ncurl 'https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fcalls\u002Fcrm-entities?phone=%2B10000000000' \\\n  -H 'X-Api-Key: YOUR_APP_KEY' \\\n  -H 'Authorization: Bearer USER_SESSION_TOKEN'\n```\n\n### JavaScript — personal key\n\n```javascript\nconst response = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fcalls\u002Fcrm-entities?phone=%2B10000000000', {\n  headers: { 'X-Api-Key': 'YOUR_API_KEY' },\n});\nconst { data } = await response.json();\nconsole.log(data);\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst response = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fcalls\u002Fcrm-entities?phone=%2B10000000000', {\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n  },\n});\nconst { data } = await response.json();\nconsole.log(data);\n```\n\n## Response fields\n\n| Field | Type | Description |\n|------|-----|----------|\n| `success` | boolean | `true` on success |\n| `data` | array | CRM cards with this number. An empty array if there are no matches |\n| `data[].crmEntityType` | string | Card type: `CONTACT`, `COMPANY` or `LEAD` |\n| `data[].crmEntityId` | integer | Card ID. To get the card: [`GET \u002Fv1\u002Fcontacts\u002F:id`](\u002Fdocs\u002Fentities\u002Fcontacts\u002Fget), [`GET \u002Fv1\u002Fcompanies\u002F:id`](\u002Fdocs\u002Fentities\u002Fcompanies\u002Fget), [`GET \u002Fv1\u002Fleads\u002F:id`](\u002Fdocs\u002Fentities\u002Fleads\u002Fget), depending on the `crmEntityType` value |\n| `data[].name` | string | Company name, or the name of the contact or lead |\n| `data[].assignedById` | integer | ID of the responsible employee. List: [`GET \u002Fv1\u002Fusers`](\u002Fdocs\u002Fentities\u002Fusers\u002Flist) |\n| `data[].assignedBy` | object | Responsible employee data for call routing |\n| `data[].assignedBy.id` | string | ID of the responsible employee as a string |\n| `data[].assignedBy.timemanStatus` | string | The employee's workday status, for example `EXPIRED` |\n| `data[].assignedBy.userPhoneInner` | string | The employee's extension number |\n| `data[].assignedBy.workPhone` | string \\| null | Work phone |\n| `data[].assignedBy.personalPhone` | string \\| null | Personal phone |\n| `data[].assignedBy.personalMobile` | string \\| null | Mobile phone |\n\n## Response example\n\nThe number belongs to a contact:\n\n```json\n{\n  \"success\": true,\n  \"data\": [\n    {\n      \"crmEntityType\": \"CONTACT\",\n      \"crmEntityId\": 9,\n      \"assignedById\": 1,\n      \"name\": \"Test contact\",\n      \"assignedBy\": {\n        \"id\": \"1\",\n        \"timemanStatus\": \"EXPIRED\",\n        \"userPhoneInner\": \"101\",\n        \"workPhone\": \"+10000000001\",\n        \"personalPhone\": null,\n        \"personalMobile\": \"+10000000002\"\n      }\n    }\n  ]\n}\n```\n\nNo matches:\n\n```json\n{\n  \"success\": true,\n  \"data\": []\n}\n```\n\n## Error response example\n\n400 — `phone` is missing:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"MISSING_REQUIRED_FIELDS\",\n    \"message\": \"phone is required\"\n  }\n}\n```\n\n## Errors\n\n| HTTP | Code | Description |\n|------|-----|----------|\n| 400 | `MISSING_REQUIRED_FIELDS` | The `phone` parameter is missing or empty |\n| 400 | `INVALID_PARAMS` | Bitrix24 rejected the parameter value |\n| 401 | `MISSING_API_KEY` | The `X-Api-Key` header is missing |\n| 401 | `INVALID_API_KEY` | The key is not found or has been revoked |\n| 401 | `TOKEN_MISSING` | The key has no portal tokens. An OAuth application key requires the `Authorization: Bearer` header |\n| 403 | `SCOPE_DENIED` | The key has no `telephony` scope |\n| 403 | `BITRIX_ACCESS_DENIED` | Bitrix24 denied access. For the causes, see [Authorization, keys and permissions](\u002Fdocs\u002Ferrors\u002Fauth#bitrix_access_denied-403) |\n| 422 | `BITRIX_ERROR` | Bitrix24 rejected the request |\n| 429 | `RATE_LIMITED` | Request rate exceeded on the Bitrix24 side |\n| 502 | `BITRIX_UNAVAILABLE` | Bitrix24 is unavailable |\n| 503 | `BITRIX_TIMEOUT` | Bitrix24 did not respond in time |\n\nThe full list of common API errors — [Error codes](\u002Fdocs\u002Ferrors).\n\n## Known specifics\n\n**Duplicate search is a different task.** [Duplicate search](\u002Fdocs\u002Fduplicates) returns the IDs of matching records, but not the cards or the responsible employee. Use this method for call routing.\n\n## See also\n\n- [Calls](\u002Fdocs\u002Fcalls)\n- [Call recording](\u002Fdocs\u002Fcalls\u002Frecord)\n- [Duplicate search](\u002Fdocs\u002Fduplicates)\n- [Error codes](\u002Fdocs\u002Ferrors)\n","2026-10-20",{},1795343930443]