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 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