Caller ID
Kommo provides many ways to retrieve the caller identity.
Call event
When creating a notification using the public API method POST /api/v2/events, a search for the caller ID is performed and a notification is created. This notification will be connected to the card with this phone number if it exists, and if not linked to create a new contact.
If more than one entity were assigned this phone number, then the method will return only one entity (lead, company, contact or customer), according to the algorithm mentioned in the call notification page.
Search by phone number
You can find the caller ID by performing a search, using the GET /api/v2/search/by_phone method, passing a telephone number to the query parameter. The response is an entity card stored in Kommo. The user, from whom the method is performed, has rights to view this card.
Algorithm
If more than one entity were assigned this phone number, then the method will return only one entity (company or contact) with the connected active lead or customer if it exists.
The method first searches for a company associated with this phone number. If there is more than one then the following points are considered:
- If any of the companies has an active lead or connected customer, and if there is one and only one active lead/connected customer with no customers/active leads respectively, the lead/customer will be returned along with the entity that has the phone number.
- If no company has an active lead/connected customer or more than one company has one active lead/connected customer, then the algorithm returns the oldest company in the account.
If no company is found, the algorithm repeats the search for a contact with the same considerations.
Otherwise it will return an empty array.
Note: This method uses only the last seven digits of the phone number for search.
Method URL
GET /api/v2/search/by_phone
Authorization type
OAuth 2.0 with Access Token. Review our Step-by-step Example.
Example of the request
GET https://subdomain.kommo.com/api/v2/search/by_phone?phone=+18305803077
GET parameter
| Parameter | Description |
| phone | The phone number we want to find the entity connected to it |
Example of the response
If no lead/customer is returned
{
"_links": {
"self": {
"href": "/api/v2/search/by_phone?phone=18305803077",
"method": "get"
}
},
"_embedded": {
"items": [
{
"id": 6811296,
"type": 3,
"responsible_user_id": 8375357,
"name": "Kommo",
"_links": {
"self": "/api/v2/companies/?id=6811296",
"method": "GET"
}
}
]
}
}Response parameters
| Parameter | Description |
| _embedded | An array containing information about the successfully returned entity |
| _embedded[items][0][id] | Unique identifier of the entity |
| _embedded[items][0][type] | Entity type (1 for contacts, 3 for companies) |
| _embedded[items][0][responsible_user_id] | Id of the user responsible of the entity |
| _embedded[items][0][name] | Entity name |
| _embedded[items][0][links] | URL and method type of the returned entity |
If there is a lead returned
{
"_links": {
"self": {
"href": "/api/v2/search/by_phone?phone=+14155237743",
"method": "get"
}
},
"_embedded": {
"items": [
{
"id": 5102790,
"type": 2,
"responsible_user_id": 8375357,
"name": "First patch",
"phone_entity": {
"id": 6811296,
"type": 3,
"name": "Lama Company",
"responsible_user_id": 8375357
},
"_links": {
"self": "/api/v2/leads/?id=5102790",
"method": "GET"
}
}
]
}
}If there is a customer returned
{
"_links": {
"self": {
"href": "/api/v2/search/by_phone?phone=+18305803077",
"method": "get"
}
},
"_embedded": {
"items": [
{
"id": 3970,
"type": 12,
"responsible_user_id": 8375357,
"name": "Customer 2",
"phone_entity": {
"id": 5760184,
"type": 1,
"name": "Adam Noah",
"responsible_user_id": 8320148
},
"_links": {
"self": "/api/v2/customers/?id=3970",
"method": "GET"
}
}
]
}
}Response parameters
| Parameter | Description |
| _embedded | An array containing information about the successfully returned entity with the requested phone number. |
| _embedded[items][0][id] | Unique identifier of the active lead |
| _embedded[items][0][type] | 2 for leads, 12 for customers |
| _embedded[items][0][responsible_user_id] | Id of the user responsible of the lead |
| _embedded[items][0][name] | Entity name |
| _embedded[items][0][phone_entity] | Details about the entity with the phone number when there are leads/customers connected to it. |
| _embedded[items][0][phone_entity][id] | Unique identifier of the entity |
| _embedded[items][0][phone_entity][type] | Entity type (1 for contacts, 3 for companies) |
| _embedded[items][0][phone_entity][responsible_user_id] | Id of the user responsible of the entity |
| _embedded[items][0][phone_entity][name] | Entity name |
| _embedded[items][0][phone_entity][links] | URL and method type of the returned entity |
Example of JS code
self.findByNumber = function(number, callback) {
// Phone number in form +1 830-570-3077
number = number.replace(/\s/g, ''); // delete problems
number = number.replace(/-/g, ''); // delete
$.get('/api/v2/search/by_phone?phone='+ parseInt(number))
.done(function (res, status, xhr) {
var entity = {};
if(xhr.status === 200 && res['_embedded'] && res['_embedded'].items){
entity.phone = number;
entity.id = res['_embedded'].items[0].id;
entity.type = res['_embedded'].items[0].type;
if(entity.type === 2 && _.isEmpty(res['_embedded'].items[0].name)){
entity.name = 'Lead #' + entity.id;
} else {
entity.name = res['_embedded'].items[0].name;
}
entity.type_string = res['_embedded'].items[0].type;
entity.phone_entity = res['_embedded'].items[0].phone_entity
}
callback(entity);
}).fail(function () {
callback({});
})
};