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
  • The purpose of this stage is to accumulate leads from different sources to be analyzed by managers
  • There are 4 categories for Incoming leads: chats, forms, sip (call), and mail
  • Only 2 types of them are available for creation 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 data, company data and metadata can be passed (for example: call or form information)
  • Before accepting the Incoming lead, contacts and companies linked to it are unavailable in the Lists section
  • There can’t be 2 identical entities in the Incoming leads. If you attempt to add data that already exists, you will receive an error
  • An Incoming lead can be accepted or declined.
  • An Incoming lead of the chat type can also be linked to an existing Lead or Customer.

Incoming leads list

Method

GET /api/v4/leads/unsorted

Description

This method allows getting a list of the incoming leads in the account.

Limitations

The method is available in accordance with the user’s rights.

Authorization type

OAuth 2.0 with Access Token. Review our Step-by-step Example.

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 Sorting the results
Available fields for sorting: created_at.
Available values for sorting: 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]=5af9dedb6f2c6a29eaac6ee37fc75ffbb66e139e4603bdd0e14e39d4b319

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 example

The method returns a collection of incoming lead models.

{
    "_page": 1,
    "_links": {
        "self": {
            "href": "https://devteam.kommo.com/api/v4/leads/unsorted"
        }
    },
    "_embedded": {
        "unsorted": [
            {
                "uid": "5af9dedb6f2c6a29eaac6ee37fc75ffbb66e139e4603bdd0e14e39d4b319",
                "source_uid": null,
                "source_name": null,
                "category": "forms",
                "pipeline_id": 6950551,
                "created_at": 1686819152,
                "metadata": {
                    "form_id": "1115559",
                    "form_name": "Form #1686818993",
                    "form_page": "Site request #1115559 from form «Form #1686818993»",
                    "ip": "212.46.197.210",
                    "form_sent_at": "1686819152",
                    "referer": "https://devteam.kommo.com/",
                    "visitor_uid": null
                },
                "account_id": 31361463,
                "_links": {
                    "self": {
                        "href": "LINK"
                    }
                },
                "_embedded": {
                    "contacts": [
                        {
                            "id": 583338,
                            "_links": {
                                "self": {
                                    "href": "https://devteam.kommo.com/api/v4/contacts/583338"
                                }
                            }
                        }
                    ],
                    "leads": [
                        {
                            "id": 236768,
                            "_links": {
                                "self": {
                                    "href": "https://devteam.kommo.com/api/v4/leads/236768"
                                }
                            }
                        }
                    ],
                    "companies": []
                }
            },
            {
                "uid": "9ca097816a45770002e406db35e2a1945364d570b765332cef7a57289fc0",
                "source_uid": "amojo:onlinechat:b4b939f3-5a25-4cab-a4e8-57140f7c72fa",
                "source_name": "onlinechat:1494984c-db73-4ceb-b980-a20a5de569f2",
                "category": "chats",
                "pipeline_id": 6950551,
                "created_at": 1686818940,
                "metadata": {
                    "from": "",
                    "to": "1494984c-db73-4ceb-b980-a20a5de569f2",
                    "received_at": 1686818940,
                    "service": "onlinechat",
                    "client": {
                        "name": null,
                        "avatar": null
                    },
                    "origin": {
                        "chat_id": "b4b939f3-5a25-4cab-a4e8-57140f7c72fa",
                        "ref": null,
                        "visitor_uid": "b2aa4364-7790-4dca-8acc-ab90554f97f8"
                    },
                    "last_message_text": 1686818940,
                    "source_name": "Live chat"
                },
                "account_id": 31361463,
                "_links": {
                    "self": {
                        "href": "LINK"
                    }
                },
                "_embedded": {
                    "contacts": [
                        {
                            "id": 583308,
                            "_links": {
                                "self": {
                                    "href": "https://devteam.kommo.com/api/v4/contacts/583308"
                                }
                            }
                        }
                    ],
                    "leads": [
                        {
                            "id": 236738,
                            "_links": {
                                "self": {
                                    "href": "https://devteam.kommo.com/api/v4/leads/236738"
                                }
                            }
                        }
                    ],
                    "companies": []
                }
            },
            {
                "uid": "400c5eb65b9fa7bbfa813cf593b49d4942f325c7c3fbbcf3acf3bee79b63",
                "source_uid": "a1fee7c0fc436088e64ba2e8822ba2b3",
                "source_name": "Acme Co.",
                "category": "sip",
                "pipeline_id": 6950551,
                "created_at": 1510261200,
                "metadata": {
                    "from": "onlinePBX",
                    "phone": "14155551234",
                    "called_at": 1510261200,
                    "duration": "54",
                    "link": "https://example.com",
                    "service_code": "CkAvbEwPam6sad"
                },
                "account_id": 31361463,
                "_links": {
                    "self": {
                        "href": "LINK"
                    }
                },
                "_embedded": {
                    "contacts": [
                        {
                            "id": 583294,
                            "_links": {
                                "self": {
                                    "href": "https://devteam.kommo.com/api/v4/contacts/583294"
                                }
                            }
                        }
                    ],
                    "leads": [
                        {
                            "id": 236724,
                            "_links": {
                                "self": {
                                    "href": "https://devteam.kommo.com/api/v4/leads/236724"
                                }
                            }
                        }
                    ],
                    "companies": [
                        {
                            "id": 583292,
                            "_links": {
                                "self": {
                                    "href": "https://devteam.kommo.com/api/v4/companies/583292"
                                }
                            }
                        }
                    ]
                }
            }
        ]
    }
}

Response parameters

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 in which the incoming lead is located
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.
account_id int Account ID in which the incoming lead is located
_embedded object Embedded entities data
_embedded[contacts] array Data related to the contact of the incoming lead. Always consists of one object
_embedded[contacts][0] object Contact model
_embedded[contacts][0][id] int Contact ID
_embedded[companies] array Data related to the company of the incoming lead. Always consists of one object
_embedded[companies][0] object Company model
_embedded[companies][0][id] int Company ID
_embedded[leads] array Data related to the lead to which the incoming lead is connected . Always consists of one object
_embedded[leads][0] object Lead model
_embedded[leads][0][id] int Lead ID

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 accordance with the user’s rights.

Authorization type

OAuth 2.0 with Access Token. Review our Step-by-step Example.

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

An example of the request

In the following example, we will get a single incoming lead list.

https://devteam.kommo.com/api/v4/leads/unsorted/
5af9dedb6f2c6a29eaac6ee37fc75ffbb66e139e4603bdd0e14e39d4b319

Response example

The method returns a model of the incoming lead.

{
    "uid": "9ca097816a45770002e406db35e2a1945364d570b765332cef7a57289fc0",
    "source_uid": "amojo:onlinechat:b4b939f3-5a25-4cab-a4e8-57140f7c72fa",
    "source_name": "onlinechat:1494984c-db73-4ceb-b980-a20a5de569f2",
    "category": "chats",
    "pipeline_id": 6950551,
    "created_at": 1686818940,
    "metadata": {
        "from": "",
        "to": "1494984c-db73-4ceb-b980-a20a5de569f2",
        "received_at": 1686818940,
        "service": "onlinechat",
        "client": {
            "name": null,
            "avatar": null
        },
        "origin": {
            "chat_id": "b4b939f3-5a25-4cab-a4e8-57140f7c72fa",
            "ref": null,
            "visitor_uid": "b2aa4364-7790-4dca-8acc-ab90554f97f8"
        },
        "last_message_text": 1686818940,
        "source_name": "Live chat"
    },
    "account_id": 31361463,
    "_links": {
        "self": {
            "href": "LINK"
        }
    },
    "_embedded": {
        "contacts": [
            {
                "id": 583308,
                "_links": {
                    "self": {
                        "href": "https://devteam.kommo.com/api/v4/contacts/583308"
                    }
                }
            }
        ],
        "leads": [
            {
                "id": 236738,
                "_links": {
                    "self": {
                        "href": "https://devteam.kommo.com/api/v4/leads/236738"
                    }
                }
            }
        ],
        "companies": []
    }
}

Response parameters

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 in which the incoming lead is located
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.
account_id int Account ID in which the incoming lead is located
_embedded object Embedded entities data
_embedded[contacts] array Data related to the contact of the incoming lead. Always consists of one object
_embedded[contacts][0] object Contact model
_embedded[contacts][0][id] int Contact ID
_embedded[companies] array Data related to the company of the incoming lead. Always consists of one object
_embedded[companies][0] object Company model
_embedded[companies][0][id] int Company ID
_embedded[leads] array Data related to the lead to which the incoming lead is connected . Always consists of one object
_embedded[leads][0] object Lead model
_embedded[leads][0][id] int Lead ID

Adding incoming leads from the type sip (call)

Method

POST /api/v4/leads/unsorted/sip

Description

This method allows adding single or multiple incoming leads into the account.

Limitations

The method is available in accordance with the user’s rights.

Authorization type

OAuth 2.0 with Access Token. Review our Step-by-step Example.

Request header

Content-Type: application/json

An example of the request

[
    {
        "request_id": "123",
        "source_name": "Acme Co.",
        "source_uid": "a1fee7c0fc436088e64ba2e8822ba2b3",
        "pipeline_id": 6950551,
        "created_at": 1510261200,
        "_embedded": {
            "leads": [
                {
                    "name": "Tech maintenance",
                    "price": 5000,
                    "custom_fields_values": [
                        {
                            "field_id": 184994,
                            "values": [
                                {
                                    "value": true
                                }
                            ]
                        }
                    ],
                    "_embedded": {
                        "tags": [
                            {
                                "id": 2164
                            }
                        ]
                    }
                }
            ],
            "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"
        }
    }
]

Body parameters

It is important to note that added calls should be inbound (incoming calls).

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 to which the incoming lead will be added
created_at int Incoming lead creation date in the format of Unix Timestamp.
metadata object Incoming lead metadata. Check sip type metadata parameters.
_embedded object Embedded entities data
_embedded[contacts] array Data related to the contact of the incoming lead. Always consists of one object
_embedded[contacts][0] object Contact model. Corresponds to the model that’s passed when adding a contact
_embedded[companies] array Data related to the company of the incoming lead. Always consists of one object
_embedded[companies][0] object Company model. Corresponds to the model that’s passed when adding a company
_embedded[leads] array Data related to the lead to which the incoming lead is connected . Always consists of one 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. It’s not a mandatory field

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": "400c5eb65b9fa7bbfa813cf593b49d4942f325c7c3fbbcf3acf3bee79b63",
                "account_id": 31361463,
                "request_id": "123",
                "_links": {
                    "self": {
                        "href": "LINK"
                    }
                },
                "_embedded": {
                    "contacts": [
                        {
                            "id": 583294,
                            "_links": {
                                "self": {
                                    "href": "https://devteam.kommo.com/api/v4/contacts/583294"
                                }
                            }
                        }
                    ],
                    "leads": [
                        {
                            "id": 236724,
                            "_links": {
                                "self": {
                                    "href": "https://devteam.kommo.com/api/v4/leads/236724"
                                }
                            }
                        }
                    ],
                    "companies": []
                }
            }
        ]
    }
}

Adding incoming leads from the type form

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.

Authorization type

OAuth 2.0 with Access Token. Review our Step-by-step Example.

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 to which the incoming lead will be added
created_at int Incoming lead creation date in the format of Unix Timestamp.
metadata object Incoming lead metadata. Check form type metadata parameters.
_embedded object Embedded entities data
_embedded[contacts] array Data related to the contact of the incoming lead. Always consists of one object
_embedded[contacts][0] object Contact model. Corresponds to the model that’s passed when adding a contact
_embedded[companies] array Data related to the company of the incoming lead. Always consists of one object
_embedded[companies][0] object Company model. Corresponds to the model that’s passed when adding a company
_embedded[leads] array Data related to the lead to which the incoming lead is connected . Always consists of one 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. It’s not a mandatory field

An example of the request

[
    {
        "request_id": "456",
        "source_name": "Asme Co.",
        "source_uid": "a1fee7c0fc436088e64ba2e8822ba2b3",
        "pipeline_id": 6950551,
        "created_at": 1510261200,
        "_embedded": {
            "leads": [
                {
                    "name": "Tech maintenance",
                    "price": 5500,
                    "custom_fields_values": [
                        {
                            "field_id": 184994,
                            "values": [
                                {
                                    "value": true
                                }
                            ]
                        }
                    ],
                    "_embedded": {
                        "tags": [
                            {
                                "id": 2164
                            }
                        ]
                    }
                }
            ],
            "contacts": [
                {
                    "name": "Example 2 contact"
                }
            ],
            "companies": [
                {
                    "name": "Atme 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"
        }
    }
]

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": "5af9dedb6f2c6a29eaac4b60de71ddd5d2ec7d9f4867a83f73616a51bc76",
                "account_id": 31361463,
                "request_id": "456",
                "_links": {
                    "self": {
                        "href": "LINK"
                    }
                },
                "_embedded": {
                    "contacts": [
                        {
                            "id": 597518,
                            "_links": {
                                "self": {
                                    "href": "https://devteam.kommo.com/api/v4/contacts/597518"
                                }
                            }
                        }
                    ],
                    "leads": [
                        {
                            "id": 250286,
                            "_links": {
                                "self": {
                                    "href": "https://devteam.kommo.com/api/v4/leads/250286"
                                }
                            }
                        }
                    ],
                    "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.

Authorization type

OAuth 2.0 with Access Token. Review our Step-by-step Example.

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 on behalf of the user with ID 8375357.

{
    "user_id": 8375357,
    "status_id": 58141807
}

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 The incoming lead accepted successfully
401 The user is not authorized
400 Invalid data are given. Details are available in the request-response
404 The 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": "5af9dedb6f2c6a29eaac6ee37fc75ffbb66e139e4603bdd0e14e39d4b319",
    "pipeline_id": 6950551,
    "category": "forms",
    "created_at": 1686819152,
    "_embedded": {
        "leads": [
            {
                "id": 236768,
                "_links": {
                    "self": {
                        "href": "https://devteam.kommo.com/api/v4/leads/236768"
                    }
                }
            }
        ],
        "contacts": [
            {
                "id": 583338,
                "is_deleted": false,
                "is_unsorted": false,
                "_links": {
                    "self": {
                        "href": "https://devteam.kommo.com/api/v4/contacts/583338"
                    }
                }
            }
        ],
        "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.

Authorization type

OAuth 2.0 with Access Token. Review our Step-by-step Example.

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": 8375357
}

HTTP response codes.

Response code Case
200 Incoming lead was 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 example

The method returns a model of the declined incoming lead and entities that were moved to the trash.

{
    "uid": "400c5eb65b9fa7bbfa813cf593b49d4942f325c7c3fbbcf3acf3bee79b63",
    "pipeline_id": 6950551,
    "category": "sip",
    "created_at": 1510261200,
    "_embedded": {
        "leads": [
            {
                "id": 236724,
                "_links": {
                    "self": {
                        "href": "https://devteam.kommo.com/api/v4/leads/236724"
                    }
                }
            }
        ],
        "contacts": [
            {
                "id": 583294,
                "is_deleted": false,
                "is_unsorted": false,
                "_links": {
                    "self": {
                        "href": "https://devteam.kommo.com/api/v4/contacts/583294"
                    }
                }
            }
        ]
    }
}

Response parameters

Parameter Data type Description
uid string Incoming lead UID
category string Incoming lead category: sip, mail, chats, forms
pipeline_id int ID of the pipeline in which the incoming lead is located
created_at int The time and date the incoming lead was created in the format of Unix Timestamp
_embedded object Embedded entities data
_embedded[contacts] array Data related to the contact of the incoming lead.
_embedded[contacts][0] object Contact model
_embedded[contacts][0][id] int Contact ID
_embedded[companies] array Data related to the company of the incoming lead.
_embedded[companies][0] object Company model
_embedded[companies][0][id] int Company ID
_embedded[leads] array Data related to the lead to which the incoming lead is connected .
_embedded[leads][0] object Lead model
_embedded[leads][0][id] int Lead ID

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

Authorization type

OAuth 2.0 with Access Token. Review our Step-by-step Example.

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 user ID on behalf of which the binding will be performed
link object An object containing the data of the entity to which the incoming lead will be linked
link[entity_id] int The ID of the entity an incoming lead will be linked to
link[entity_type] string Entity type. Available options: leads, customers
link[metadata] object Action metadata
link[metadata][contact_id] int The ID of the contact to which the contact from the incoming lead will be assigned

An example of the request

{
    "link": {
        "entity_id": 152464,
        "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 example

{
    "uid": "9ca097816a45770002e406db35e2a1945364d570b765332cef7a57289fc0",
    "_embedded": {
        "leads": [
            {
                "id": 152464,
                "_links": {
                    "self": {
                        "href": "https://devteam.kommo.com/api/v4/leads/152464"
                    }
                }
            }
        ],
        "contacts": [],
        "customers": []
    }
}

Response parameters

The method returns the information about the performed action.

Parameter Data type Description
uid string Incoming lead UID
_embedded object Embedded entities data
_embedded[leads] array Data related to the lead to which the incoming lead is being connected.
_embedded[leads][0] object Lead model
_embedded[leads][0][id] int Lead ID
_embedded[contacts] array Data related to the contact to which the incoming lead is being connected.
_embedded[contacts][0] object Contact model
_embedded[contacts][0][id] int Contact ID
_embedded[companies] array Data related to the company to which the incoming lead is being connected.
_embedded[companies][0] object Company model
_embedded[companies][0][id] int Company ID

Incoming leads summary information

Method

GET /api/v4/leads/unsorted/summary

Description

This method allows to get summary information about the incoming leads in the account.

Limitations

The method is available in correspondence to the user rights.

Authorization type

OAuth 2.0 with Access Token. Review our Step-by-step Example.

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://devteam.kommo.com/api/v4/leads/unsorted/summary?filter[pipeline_id]=6950551

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": 6,
    "accepted": 1,
    "declined": 3,
    "average_sort_time": 44153027,
    "categories": {
        "sip": {
            "total": 2
        },
        "forms": {
            "total": 3
        },
        "chats": {
            "total": 1
        }
    }
}

Metadata objects description

There are 4 categories for Incoming leads: chats, forms, sip (call), and mail. The difference between the incoming leads from the four types is in the metadata.

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 and time in Unix Timestamp format
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 date and time in Unix Timestamp format
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 and time in Unix Timestamp format
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 and time when the email was received in Unix Timestamp format
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