Incoming Leads
In this section, we will describe all available methods for working with Incoming leads via API.
Table of Contents
- Common information
- Incoming leads list
- Getting an incoming lead by its UID
- Adding the sip (call) type incoming leads
- Adding the form type incoming leads
- Accepting incoming leads
- Declining incoming leads
- Linking incoming leads
- Incoming leads summary information
- Metadata objects description
Common information
- Incoming leads is a system stage of the Leads pipeline with additional functionality
- This stage accumulates leads from different sources to be sorted out by managers
- There are 4 categories for the Incoming leads: chats, forms, sip (call), and mail
- Only 2 types are available to add via API: forms and sip.
- Incoming leads of the chats and mail types are added via built-in tools (chats and mail integrations)
- When adding an Incoming lead, contact, company data, and metadata (call or form info) can be passed
- Until the Incoming lead is accepted, contacts and companies linked to it are unavailable in the Lists section
- There can’t be 2 of the same entity in the Incoming leads. If you attempt to add data that already exists, you will receive an error
- An Incoming lead can be accepted, declined, or linked to an existing Lead or Customer. Only Incoming leads of the chat type can be linked
Incoming leads list
Method
GET /api/v4/leads/unsorted
Description
This method allows getting a list of incoming leads in the account.
Limitations
The method is available in correspondence to the user rights.
GET parameters
Parameter | Data type | Description |
---|---|---|
page | int | Sample page |
limit | int | The number of the entities returned in the response to one request (limit – 250) |
filter | object | Filter |
filter[uid] | string|array | Filter by the incoming lead UID. Either a single UID or an array of UIDs can be passed |
filter[category] | array | Filter by the incoming leads categories (sip, mail, forms, chats) |
filter[pipeline_id] | int | Filter by the pipeline ID |
order | object | List elements sorting. Fields available to sort by: created_at. Values available to sort by: asc, desc. An example: /api/v4/leads/unsorted?order[created_at]=asc |
An example of the request
In the following example, we will get a single incoming lead list.
https://example.kommo.com/api/v4/leads/unsorted?filter[uid]=98fb033cefde74f5de1a5d3980a2a2d108037
Data type header when the request is successful
Content-Type: application/hal+json
Data type header in case of an error
Content-Type: application/problem+json
HTTP response codes.
Response code | Case |
---|---|
200 | Request successful |
401 | The user is not authorized |
Response parameters
The method returns a collection of incoming lead models. The properties of the model are listed below.
Parameter | Data type | Description |
---|---|---|
uid | string | Incoming lead UID |
source_uid | string | Incoming lead source UID. Generated by the integration |
source_name | string | Incoming lead source name |
category | string | Incoming lead category: sip, mail, chats, forms |
pipeline_id | int | ID of the pipeline the incoming lead is located in |
created_at | int | The time and date the incoming lead was created in the format of Unix Timestamp |
metadata | object | Incoming lead metadata. Each type has its own parameters. They are described in detail here |
account_id | int | Account ID |
_embedded | object | Embedded entities data |
_embedded[contacts] | array | Linked contact data array. Always consists of 1 object |
_embedded[contacts][0] | object | Contact model |
_embedded[contacts][0][id] | int | Contact ID |
_embedded[companies] | array | Linked company data array. Always consists of 1 object |
_embedded[companies][0] | object | Company model |
_embedded[companies][0][id] | int | Company ID |
_embedded[leads] | array | Lead data array. Always consists of 1 object |
_embedded[leads][0] | object | Lead model |
_embedded[leads][0][id] | int | Lead ID |
Response example
{
"_page": 1,
"_links": {
"self": {
"href": "https://example.kommo.com/api/v4/leads/unsorted?filter[uid]=98fb033cefde74f5de1a5d3980a2a2d108037"
}
},
"_embedded": {
"unsorted": [
{
"uid": "98fb033cefde74f5de1a5d3980a2a2d108037",
"source_uid": null,
"source_name": "UIS",
"category": "sip",
"pipeline_id": 2194576,
"created_at": 1583156937,
"metadata": {
"from": "14155551234",
"phone": 14155551234,
"called_at": 1583156916,
"duration": "0",
"link": null,
"service_code": "uis_widget"
},
"account_id": 123312,
"_links": {
"self": {
"href": "https://example.kommo.com/api/v4/leads/unsorted/98fb033cefde74f5de1a52d108037"
}
},
"_embedded": {
"contacts": [
{
"id": 13176707,
"_links": {
"self": {
"href": "https://example.kommo.com/api/v4/contacts/13176707"
}
}
}
],
"leads": [
{
"id": 7002787,
"_links": {
"self": {
"href": "https://example.kommo.com/api/v4/leads/7002787"
}
}
}
],
"companies": []
}
}
]
}
}
Getting an incoming lead by its UID
Method
GET /api/v4/leads/unsorted/{uid}
Description
This method allows getting a particular incoming lead data by its UID.
Limitations
The method is available in correspondence to the user rights.
Data type header when the request is successful
Content-Type: application/hal+json
Data type header in case of an error
Content-Type: application/problem+json
HTTP response codes.
Response code | Case |
---|---|
200 | Request successful |
401 | The user is not authorized |
Response parameters
The method returns a model of the incoming lead. The properties of the model are listed below.
Parameter | Data type | Description |
---|---|---|
uid | string | Incoming lead UID |
source_uid | string | Incoming lead source UID. Generated by the integration |
source_name | string | Incoming lead source name |
category | string | Incoming lead category: sip, mail, chats, forms |
pipeline_id | int | The ID of the pipeline the incoming lead is located in |
created_at | int | The time and date the incoming lead was created in the format of Unix Timestamp |
metadata | object | Incoming lead metadata. Each type has its own parameters. They are described in detail here |
account_id | int | Account ID |
_embedded | object | Embedded entities data |
_embedded[contacts] | array | Linked contact data array. Always consists of 1 object |
_embedded[contacts][0] | object | Contact model |
_embedded[contacts][0][id] | int | Contact ID |
_embedded[companies] | array | Linked company data array. Always consists of 1 object |
_embedded[companies][0] | object | Company model |
_embedded[companies][0][id] | int | Company ID |
_embedded[leads] | array | Lead data array. Always consists of 1 object |
_embedded[leads][0] | object | Lead model |
_embedded[leads][0][id] | int | Lead ID |
Response example
{
"uid": "aa401affb0094076b7449008363c1dc77d6790ad13fb5b08176dc46daa18",
"source_uid": "my_unique_uid",
"source_name": "Source name",
"category": "forms",
"pipeline_id": 3166396,
"created_at": 1588840852,
"metadata": {
"form_id": "my_best_form",
"form_name": "Feedback form",
"form_page": "https://example.com/form",
"ip": "192.168.0.1",
"form_sent_at": "1570178452",
"referer": "https://google.com/search",
"visitor_uid": null
},
"account_id": 28805383,
"_links": {
"self": {
"href": "https://example.kommo.com/api/v4/leads/unsorted/aa401affb0094076b08176dc46daa18"
}
},
"_embedded": {
"contacts": [
{
"id": 9567221,
"_links": {
"self": {
"href": "https://example.kommo.com/api/v4/contacts/9567221"
}
}
}
],
"leads": [
{
"id": 6414851,
"_links": {
"self": {
"href": "https://example.kommo.com/api/v4/leads/6414851"
}
}
}
],
"companies": []
}
}
Adding the sip (call) type incoming leads
Method
POST /api/v4/leads/unsorted/sip
Description
This method allows adding multiple or singular incoming leads into the account.
Limitations
The method is available in correspondence to the user rights.
Request header
Content-Type: application/json
Request parameters
It is important to note that added calls should be inbound.
All fields except created_at, pipeline_id are mandatory.
Parameter | Data type | Description |
---|---|---|
source_uid | string | Incoming lead source UID. Generated by the integration |
source_name | string | Incoming lead source name |
pipeline_id | int | The ID of the pipeline the incoming lead will be added to |
created_at | int | Incoming lead creation date in the format of Unix Timestamp. |
metadata | object | Incoming lead metadata. Each type has its own parameters. They are described in detail here |
_embedded | object | Embedded entities data |
_embedded[contacts] | array | Linked contact data array. Always consists of 1 object |
_embedded[contacts][0] | object | Contact model. Corresponds to the model that’s passed when adding a contact |
_embedded[companies] | array | Linked company data array. Always consists of 1 object |
_embedded[companies][0] | object | Company model. Corresponds to the model that’s passed when adding a company |
_embedded[leads] | array | Lead data array. Always consists of 1 object |
_embedded[leads][0] | object | Lead model. Corresponds to the model that’s passed when adding a lead |
request_id | string | The field that will be returned unchanged in the response and will not be saved. Is not a mandatory field |
An example of the request
[
{
"request_id": "123",
"source_name": "Acme Co.",
"source_uid": "a1fee7c0fc436088e64ba2e8822ba2b3",
"pipeline_id": 2194576,
"created_at": 1510261200,
"_embedded": {
"leads": [
{
"name": "Tech maintenance",
"price": 5000,
"custom_fields_values": [
{
"field_id": 284785,
"values": [
{
"value": "Custom field"
}
]
}
],
"_embedded": {
"tags": [
{
"id": 263809
}
]
}
}
],
"contacts": [
{
"name": "Example contact"
}
],
"companies": [
{
"name": "Acme Co."
}
]
},
"metadata": {
"is_call_event_needed": true,
"uniq": "a1fe231cc88e64ba2e8822ba2b3ewrw",
"duration": 54,
"service_code": "CkAvbEwPam6sad",
"link": "https://example.com",
"phone": 14155551234,
"called_at": 1510261200,
"from": "onlinePBX"
}
}
]
Data type header when the request is successful
Content-Type: application/hal+json
Data type header in case of an error
Content-Type: application/problem+json
HTTP response codes.
Response code | Case |
---|---|
200 | Incoming leads added successfully |
401 | The user is not authorized |
400 | Invalid data are given. Details are available in the request-response |
Response parameters
The method returns a collection of created incoming leads.
Response example
{
"_total_items": 1,
"_embedded": {
"unsorted": [
{
"uid": "aa401affb0094076b74442bc3f401d53e103f264d6668fd3ecfd5acef42f",
"account_id": 28805383,
"request_id": "123",
"_links": {
"self": {
"href": "https://example.kommo.com/api/v4/leads/unsorted/aa401d6668fd3ecfd5acef42f"
}
},
"_embedded": {
"contacts": [
{
"id": 11075541,
"_links": {
"self": {
"href": "https://example.kommo.com/api/v4/contacts/11075541"
}
}
}
],
"leads": [
{
"id": 7706509,
"_links": {
"self": {
"href": "https://example.kommo.com/api/v4/leads/7706509"
}
}
}
],
"companies": []
}
}
]
}
}
Adding the form type incoming leads
Method
POST /api/v4/leads/unsorted/forms
Description
This method allows adding multiple or singular incoming leads into the account.
Limitations
The method is available in correspondence to the user rights.
Request header
Content-Type: application/json
Request parameters
All fields except created_at, pipeline_id are mandatory.
Parameter | Data type | Description |
---|---|---|
source_uid | string | Incoming lead source UID. Generated by the integration |
source_name | string | Incoming lead source name |
pipeline_id | int | The ID of the pipeline the incoming lead will be added to |
created_at | int | Incoming lead creation date in the format of Unix Timestamp. |
metadata | object | Incoming lead metadata. Each type has its own parameters. They are described in detail here |
_embedded | object | Embedded entities data |
_embedded[contacts] | array | Linked contact data array. Always consists of 1 object |
_embedded[contacts][0] | object | Contact model. Corresponds to the model that’s passed when adding a contact |
_embedded[companies] | array | Linked company data array. Always consists of 1 object |
_embedded[companies][0] | object | Company model. Corresponds to the model that’s passed when adding a company |
_embedded[leads] | array | Lead data array. Always consists of 1 object |
_embedded[leads][0] | object | Lead model. Corresponds to the model that’s passed when adding a lead |
request_id | string | The field that will be returned unchanged in the response and will not be saved. Is not a mandatory field |
An example of the request
[
{
"request_id": "123",
"source_name": "Acme Co.",
"source_uid": "a1fee7c0fc436088e64ba2e8822ba2b3",
"pipeline_id": 2194576,
"created_at": 1590830520,
"_embedded": {
"leads": [
{
"name": "Tech maintenance",
"visitor_uid": "5692210d-58d0-468c-acb2-dce7f93eef87",
"price": 5000,
"custom_fields_values": [
{
"field_id": 284785,
"values": [
{
"value": "Custom field"
}
]
}
],
"_embedded": {
"tags": [
{
"name": "Example tag"
}
]
}
}
],
"contacts": [
{
"name": 234,
"first_name": "123213",
"last_name": 234,
"custom_fields_values": [
{
"field_code": "PHONE",
"values": [
{
"value": "+14155551234"
}
]
}
]
}
],
"companies": [
{
"name": "Acme Co."
}
]
},
"metadata": {
"ip": "123.222.2.22",
"form_id": "a1fee7c0fc436088e64ba2e8822ba2b3ewrw",
"form_sent_at": 1590830520,
"form_name": "Application form",
"form_page": "https://example.com",
"referer": "https://www.google.com/search?&q=elon+musk"
}
}
]
Data type header when the request is successful
Content-Type: application/hal+json
Data type header in case of an error
Content-Type: application/problem+json
HTTP response codes.
Response code | Case |
---|---|
200 | Incoming leads added successfully |
401 | The user is not authorized |
400 | Invalid data are given. Details are available in the request-response |
Response parameters
The method returns a collection of created incoming leads.
Response example
{
"_total_items": 1,
"_embedded": {
"unsorted": [
{
"uid": "69035fda95c38bf3a281e846652217aade38692a5cf9d2b312e3724f78bc",
"account_id": 28805383,
"request_id": "123",
"_links": {
"self": {
"href": "https://example.kommo.com/api/v4/leads/unsorted/69035fd2b312e3724f78bc"
}
},
"_embedded": {
"contacts": [
{
"id": 11075543,
"_links": {
"self": {
"href": "https://example.kommo.com/api/v4/contacts/11075543"
}
}
}
],
"leads": [
{
"id": 7706511,
"_links": {
"self": {
"href": "https://example.kommo.com/api/v4/leads/7706511"
}
}
}
],
"companies": []
}
}
]
}
}
Accepting incoming leads
Method
POST /api/v4/leads/unsorted/{uid}/accept
Description
This method allows to accept an incoming lead.
Limitations
The method is available in correspondence to the user rights.
Request header
Content-Type: application/json
Request parameters
There are no mandatory parameters to accept an incoming lead, however, optional data can be passed.
Parameter | Data type | Description |
---|---|---|
user_id | int | The ID of the user who will be set as the entity creator |
status_id | int | The ID of the stage where the lead will be located after an incoming lead is accepted |
An example of the request
In the following example, we will accept an Incoming lead using the /api/v4/leads/unsorted/{uid}/accept method.
The Incoming lead will be accepted on behalf of the user with ID 123123.
{
"user_id": 123123,
"status_id": 30846280
}
Data type header when the request is successful
Content-Type: application/hal+json
Data type header in case of an error
Content-Type: application/problem+json
HTTP response codes.
Response code | Case |
---|---|
200 | Incoming lead accepted successfully |
401 | The user is not authorized |
400 | Invalid data are given. Details are available in the request-response |
404 | Incoming lead with this UID was not found |
Response parameters
The method returns a model of the accepted incoming lead and created entities.
Response example
{
"uid": "3cvd1de2ebfsd152fd6a465cd3e586cbdba6827",
"pipeline_id": 31634,
"category": "mail",
"_embedded": {
"leads": [
{
"id": 9944789,
"_links": {
"self": {
"href": "https://example.kommo.com/api/v4/leads/9944789"
}
}
}
],
"contacts": [
{
"id": 16522451,
"_links": {
"self": {
"href": "https://example.kommo.com/api/v4/contacts/16522451"
}
}
}
],
"companies": []
}
}
Declining incoming leads
Method
DELETE /api/v4/leads/unsorted/{uid}/decline
Description
This method allows to decline an incoming lead.
Limitations
The method is available in correspondence to the user rights.
Request header
Content-Type: application/json
Request parameters
There are no mandatory parameters to decline an incoming lead, however, optional data can be passed.
Parameter | Data type | Description |
---|---|---|
user_id | int | The ID of the user performing the decline |
An example of the request
{
"user_id": 123123
}
HTTP response codes.
Response code | Case |
---|---|
200 | Incoming lead deleted successfully |
403 | Insufficient rights to call this method |
404 | Incoming lead with this UID was not found |
401 | The user is not authorized |
400 | Invalid data are given. Details are available in the request-response |
Response parameters
The method returns a model of the declined incoming lead and entities that were moved to the bin.
Response example
{
"uid": "98bc1d1de2f960a2ad0e34b52823",
"pipeline_id": 1394576,
"created_at": 1589115506,
"category": "mail",
"_embedded": {
"leads": [
{
"id": 9937533,
"_links": {
"self": {
"href": "https://example.kommo.com/api/v4/leads/9937533"
}
}
}
],
"contacts": [
{
"id": 163141,
"_links": {
"self": {
"href": "https://example.kommo.com/api/v4/contacts/163141"
}
}
}
]
}
}
Linking incoming leads
Method
POST /api/v4/leads/unsorted/{uid}/link
Description
This method allows link an incoming lead to an existing lead or customer.
Limitations
- The method is available for administrator users only
- The method is available for incoming leads of the “chats” type only
Request header
Content-Type: application/json
Request parameters
To link an incoming lead, it is required to pass the “link” object.
Parameter | Data type | Description |
---|---|---|
user_id | int | The ID of the user who performs the link |
link | object | An object containing the data of the entity an incoming lead will be linked to |
link[entity_id] | int | The ID of the entity an incoming lead will be linked to |
link[entity_type] | string | Entity type: leads, customers |
link[metadata] | object | Action metadata |
link[metadata][contact_id] | int | The ID of the contact the incoming lead’s contact will be linked to |
An example of the request
{
"link": {
"entity_id": 93144801,
"entity_type": "leads"
}
}
Data type header when the request is successful
Content-Type: application/hal+json
Data type header in case of an error
Content-Type: application/problem+json
HTTP response codes.
Response code | Case |
---|---|
200 | Incoming lead linked successfully |
401 | The user is not authorized |
400 | Invalid data are given. Details are available in the request-response |
Response parameters
The method returns the information about the performed action.
Response example
{
"uid": "d7faa21ce091fe0da05d8d4c2075090c1e9bfd4",
"_embedded": {
"leads": [
{
"id": 93144801,
"_links": {
"self": {
"href": "https://example.kommo.com/api/v4/leads/93144801"
}
}
}
]
}
}
Incoming leads summary information
Method
GET /api/v4/leads/unsorted/summary
Description
This method allows to get the incoming leads summary information.
Limitations
The method is available in correspondence to the user rights.
GET parameters
Parameter | Data type | Description |
---|---|---|
filter | object | Filter |
filter[uid] | string|array | Filter by the incoming lead UID. Either a single UID or an array of UIDs can be passed |
filter[created_at] | int|object | Filter by creation date and incoming lead acceptance date. You can pass a timestamp, in which case data will be returned for the incoming lead created and received from the passed timestamp. You can also pass an object like filter[created_at][from]=… and filter[created_at][to]=… to filter by FROM and TO values. |
filter[pipeline_id] | int | Filter by the pipeline ID |
An example of the request
https://example.kommo.com/api/v4/leads/unsorted/summary?filter[created_at][from]=1589176500&filter[created_at][to]=1589176560&filter[pipeline_id]=2194576
Data type header when the request is successful
Content-Type: application/hal+json
Data type header in case of an error
Content-Type: application/problem+json
HTTP response codes.
Response code | Case |
---|---|
200 | Request successful |
401 | The user is not authorized |
Response parameters
The method returns the summary information as an object.
Parameter | Data type | Description |
---|---|---|
total | int | Total number of incoming leads |
accepted | int | Total number of accepted incoming leads |
declined | int | Total number of declined incoming leads |
average_sort_time | int | Average sorting time in seconds |
categories | object | The number of incoming leads of a particular category |
Response example
{
"total": 168,
"accepted": 6,
"declined": 2,
"average_sort_time": 34521,
"categories": {
"sip": {
"total": 31
},
"mail": {
"total": 41
},
"forms": {
"total": 27
},
"chats": {
"total": 69
}
}
}
Metadata objects description
Incoming leads metadata of the sip (call) category
Parameter | Data type | Description |
---|---|---|
from | string | Call initiator |
phone | string | Call recipient |
called_at | int | Call date in the format of Unix Timestamp |
duration | int | Call duration |
link | string | A link to the call recording |
service_code | string | Service provider code |
is_call_event_needed | bool | This flag is not returned in the response but can be passed. If the “true” value is passed, the call event will be added to the entity card. |
Incoming leads metadata of the forms category
Parameter | Data type | Description |
---|---|---|
form_id | string | Integration’s form ID. |
form_name | string | Form name |
form_page | string | Web-page where the form is installed |
ip | string | The IP address of the request |
form_sent_at | int | Form submission timestamp is the format of Unix Timestamp |
referer | string | Web-page the applicant was redirected from to the form page |
Incoming leads metadata of the chats category
Parameter | Data type | Description |
---|---|---|
from | string | The name of the user who sent the message |
to | string | The ID of the page that received the message |
received_at | int | Message date in the format of Unix Timestamp |
service | string | Name of the service that delivered the message |
client | object | Message author data |
client[name] | string | Message sender name |
client[avatar] | string|null | Link to the sender’s avatar |
origin | object | Message source data |
origin[chat_id] | string | Chat ID in the chats service |
origin[ref] | string|null | Additional data from the chats service |
origin[visitor_uid] | string|null | UID of the user who sent the message |
last_message_text | string|null | The last message from the user |
source_name | string | Message source name |
Incoming leads metadata of the mail category
Parameter | Data type | Description |
---|---|---|
from | object | Email author data |
from[email] | string | Author email address |
from[name] | string | Author name |
received_at | int | Date when the email was received in the format of Unix Timestamp |
subject | string | Email subject |
thread_id | int | Thread ID in the mail service |
message_id | int | Email ID in the mail service |
content_summary | string | Email content summary |