## 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 |
|----------|-----|-------|----------|
| `phone` (query) | string | yes | Phone number, a non-empty string. Encode the `+` sign in the request URL as `%2B` |

## Examples

### curl — personal key

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

### curl — OAuth application

```bash
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 |
|------|-----|----------|
| `success` | boolean | `true` on success |
| `data` | array | CRM cards with this number. An empty array if there are no matches |
| `data[].crmEntityType` | string | Card type: `CONTACT`, `COMPANY` or `LEAD` |
| `data[].crmEntityId` | integer | Card ID. To get the card: [`GET /v1/contacts/:id`](/docs/entities/contacts/get), [`GET /v1/companies/:id`](/docs/entities/companies/get), [`GET /v1/leads/:id`](/docs/entities/leads/get), depending on the `crmEntityType` value |
| `data[].name` | string | Company name, or the name of the contact or lead |
| `data[].assignedById` | integer | ID of the responsible employee. List: [`GET /v1/users`](/docs/entities/users/list) |
| `data[].assignedBy` | object | Responsible employee data for call routing |
| `data[].assignedBy.id` | string | ID of the responsible employee as a string |
| `data[].assignedBy.timemanStatus` | string | The employee's workday status, for example `EXPIRED` |
| `data[].assignedBy.userPhoneInner` | string | The employee's extension number |
| `data[].assignedBy.workPhone` | string \| null | Work phone |
| `data[].assignedBy.personalPhone` | string \| null | Personal phone |
| `data[].assignedBy.personalMobile` | string \| null | Mobile 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 |
|------|-----|----------|
| 400 | `MISSING_REQUIRED_FIELDS` | The `phone` parameter is missing or empty |
| 400 | `INVALID_PARAMS` | Bitrix24 rejected the parameter value |
| 401 | `MISSING_API_KEY` | The `X-Api-Key` header is missing |
| 401 | `INVALID_API_KEY` | The key is not found or has been revoked |
| 401 | `TOKEN_MISSING` | The key has no portal tokens. An OAuth application key requires the `Authorization: Bearer` header |
| 403 | `SCOPE_DENIED` | The key has no `telephony` scope |
| 403 | `BITRIX_ACCESS_DENIED` | Bitrix24 denied access. For the causes, see [Authorization, keys and permissions](/docs/errors/auth#bitrix_access_denied-403) |
| 422 | `BITRIX_ERROR` | Bitrix24 rejected the request |
| 429 | `RATE_LIMITED` | Request rate exceeded on the Bitrix24 side |
| 502 | `BITRIX_UNAVAILABLE` | Bitrix24 is unavailable |
| 503 | `BITRIX_TIMEOUT` | Bitrix24 did not respond in time |

The full list of common API errors — [Error codes](/docs/errors).

## Known specifics

**Duplicate search is a different task.** [Duplicate search](/docs/duplicates) returns the IDs of matching records, but not the cards or the responsible employee. Use this method for call routing.

## See also

- [Calls](/docs/calls)
- [Call recording](/docs/calls/record)
- [Duplicate search](/docs/duplicates)
- [Error codes](/docs/errors)