Leads

In this section, we will describe all available methods for the Lead entity.

Table of Contents

Leads list

Method

GET /api/v4/leads

Description

This method allows to get a list of 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
with string This parameter accepts a string which may consist of several values separated by commas.
page int Sample page
limit int The number of entities returned per request (limit – 250)
query string|int Search query (Searches through the filled fields of the entity)
filter object Working with filters is described in detail in Filters API
order object Sorting the results
Available fields for sorting: created_at, updated_at, id.
Available values for sorting: asc, desc.
An example: /api/v4/leads?order[updated_at]=asc

“with” Parameters

Parameter Description
catalog_elements Adds lists items linked to the lead to the response
is_price_modified_by_robot Adds a property represents whether the lead sale value was changed last time by Robot to the response
loss_reason Adds detailed information about the lead loss reason to the response
contacts Adds information about the contacts associated with the lead to the response
only_deleted If this parameter is passed, the method request will return only the deleted leads that are still restorable in the response. You will receive lead models with the following properties: “id”, modification date and “is_deleted” = true parameters.
source_id Adds the lead source ID to the response

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

When the request is successful, the method returns the leads model collection.

{
    "_page": 1,
    "_links": {
        "self": {
            "href": "LINK"
        }
    },
    "_embedded": {
        "leads": [
            {
                "id": 152462,
                "name": "Example Lead 1",
                "price": 15000,
                "responsible_user_id": 8375357,
                "group_id": 0,
                "status_id": 58141807,
                "pipeline_id": 6950551,
                "loss_reason_id": null,
                "created_by": 8375357,
                "updated_by": 0,
                "created_at": 1686673336,
                "updated_at": 1686747000,
                "closed_at": null,
                "closest_task_at": 1686850200,
                "is_deleted": false,
                "custom_fields_values": [
                    {
                        "field_id": 184994,
                        "field_name": "Sale",
                        "field_code": null,
                        "field_type": "checkbox",
                        "values": [
                            {
                                "value": true
                            }
                        ],
                        "is_computed": false
                    }
                ],
                "score": null,
                "account_id": 31361463,
                "labor_cost": null,
                "is_price_computed": false,
                "source_id": 20692839,
                "is_price_modified_by_robot": true,
                "_links": {
                    "self": {
                        "href": "LINK"
                    }
                },
                "_embedded": {
                    "tags": [],
                    "catalog_elements": [],
                    "loss_reason": [],
                    "companies": [],
                    "contacts": []
                }
            },
            {
                "id": 152464,
                "name": "Example lead 2",
                "price": 20000,
                "responsible_user_id": 8375357,
                "group_id": 0,
                "status_id": 58141807,
                "pipeline_id": 6950551,
                "loss_reason_id": null,
                "created_by": 0,
                "updated_by": 8375357,
                "created_at": 1686673337,
                "updated_at": 1686747678,
                "closed_at": null,
                "closest_task_at": null,
                "is_deleted": false,
                "custom_fields_values": [
                    {
                        "field_id": 184994,
                        "field_name": "Sale",
                        "field_code": null,
                        "field_type": "checkbox",
                        "values": [
                            {
                                "value": true
                            }
                        ],
                        "is_computed": false
                    }
                ],
                "score": null,
                "account_id": 31361463,
                "labor_cost": null,
                "is_price_computed": false,
                "source_id": 20692839,
                "is_price_modified_by_robot": false,
                "_links": {
                    "self": {
                        "href": "LINK"
                    }
                },
                "_embedded": {
                    "tags": [
                        {
                            "id": 2164,
                            "name": "Ex",
                            "color": null
                        }
                    ],
                    "catalog_elements": [],
                    "loss_reason": [],
                    "companies": [],
                    "contacts": []
                }
            },
            {
                "id": 186404,
                "name": "Example lead 0",
                "price": 100,
                "responsible_user_id": 8375357,
                "group_id": 0,
                "status_id": 143,
                "pipeline_id": 6950551,
                "loss_reason_id": 15906383,
                "created_by": 8375357,
                "updated_by": 8375357,
                "created_at": 1686747706,
                "updated_at": 1686747731,
                "closed_at": 1686747731,
                "closest_task_at": null,
                "is_deleted": false,
                "custom_fields_values": null,
                "score": null,
                "account_id": 31361463,
                "labor_cost": null,
                "is_price_computed": false,
                "source_id": null,
                "is_price_modified_by_robot": false,
                "_links": {
                    "self": {
                        "href": "LINK"
                    }
                },
                "_embedded": {
                    "tags": [],
                    "catalog_elements": [],
                    "loss_reason": [
                        {
                            "id": 15906383,
                            "name": "Insufficient budget",
                            "sort": 100000,
                            "created_at": 1686662760,
                            "updated_at": 1686662760,
                            "_links": {
                                "self": {
                                    "href": "LINK"
                                }
                            }
                        }
                    ],
                    "companies": [
                        {
                            "id": 406320,
                            "_links": {
                                "self": {
                                    "href": "LINK"
                                }
                            }
                        }
                    ],
                    "contacts": [
                        {
                            "id": 406322,
                            "is_main": true,
                            "_links": {
                                "self": {
                                    "href": "LINK"
                                }
                            }
                        }
                    ]
                }
            }
        ]
    }
}

Response parameters

The properties of a lead model are listed below.

Parameter Data type Description
id int Lead ID
name string Lead name
price int Lead sale
responsible_user_id int Lead responsible user ID
group_id int Group ID of the lead responsible user
status_id int ID of the stage the lead is added to, the first stage of the main pipeline by default
pipeline_id int ID of the pipeline the lead is added to
loss_reason_id int Lead loss reason ID
source_id int GET parameter “with” is required. Lead source ID
created_by int Id of the user who created the lead
updated_by int Id of the user who updated the lead
created_at int The time and date the lead was created in the format of Unix Timestamp
updated_at int The time and date the lead was updated in the format of Unix Timestamp
closed_at int The time and date the lead was closed in the format of Unix Timestamp
closest_task_at int The time and date of the closest open task in the format of Unix Timestamp
is_deleted bool Defines whether the lead was deleted
custom_fields_values array|null An array containing information on the values ​​of custom fields specified for this lead
score int|null Lead score
account_id int Account ID where the lead is located in
labor_cost int Shows how much time was spent working with the deal. Calculation time in seconds
is_price_modified_by_robot bool GET parameter “with” is required. Defines whether the lead sale value was changed by the Robot last time
_embedded object Embedded entities data
_embedded[loss_reason] object GET parameter “with” is required. Lead loss reason
_embedded[loss_reason][id] int Loss reason ID
_embedded[loss_reason][name] string Loss reason name
_embedded[tags] array Lead tags data array
_embedded[tags][0] object Lead tag model
_embedded[tags][0][id] int Tag ID
_embedded[tags][0][name] string Tag name
_embedded[contacts] array GET parameter “with” is required. Linked contacts data array
_embedded[contacts][0] object Linked contact data
_embedded[contacts][0][id] int Linked contact ID
_embedded[contacts][0][is_main] bool Defines whether the contact is main for the lead
_embedded[companies] array Linked company data array. This array always consists of 1 element as a lead can have only 1 company linked to it
_embedded[companies][0] object Linked company data
_embedded[companies][0][id] int Linked company ID
_embedded[catalog_elements] array GET parameter “with” is required. Linked lists’ elements data array
_embedded[catalog_elements][0] object Linked list element data
_embedded[catalog_elements][0][id] int Linked element ID
_embedded[catalog_elements][0][metadata] object Meta-data of the element
_embedded[catalog_elements][0][quantity] int Linked element quantity
_embedded[catalog_elements][0][catalog_id] int ID of the linked element’s list

Getting a lead by its ID

Method

GET /api/v4/leads/{id}

Description

This method allows to get a particular lead data by its ID.

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
with string This parameter takes a string which may consist of several values separated by commas.

“with” parameters

Parameter Description
catalog_elements Adds lists elements linked to the lead into the response
is_price_modified_by_robot Adds a property that represents whether the lead sale value was changed by Robot the last time into the response
loss_reason Adds detailed info on the lead loss reason into the response
contacts Adds info on the contacts linked to the lead into the response
only_deleted If this parameter is passed, the method request will return only the deleted leads that are still restorable in the response. You will receive lead models with the following properties: “id”, modification date and “is_deleted” = true parameters.
source_id Adds the lead source ID to the response

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
204 The lead with the specified ID does not exist.
401 User is not authorized

Response example

The method returns a lead model.

{
    "id": 152464,
    "name": "Example lead 2",
    "price": 20000,
    "responsible_user_id": 8375357,
    "group_id": 0,
    "status_id": 58141807,
    "pipeline_id": 6950551,
    "loss_reason_id": null,
    "created_by": 0,
    "updated_by": 8375357,
    "created_at": 1686673337,
    "updated_at": 1686748504,
    "closed_at": null,
    "closest_task_at": null,
    "is_deleted": false,
    "custom_fields_values": [
        {
            "field_id": 184994,
            "field_name": "Sale",
            "field_code": null,
            "field_type": "checkbox",
            "values": [
                {
                    "value": true
                }
            ],
            "is_computed": false
        }
    ],
    "score": null,
    "account_id": 31361463,
    "labor_cost": null,
    "is_price_computed": false,
    "_links": {
        "self": {
            "href": "https://devteam.kommo.com/api/v4/leads/152464?page=1&limit=50"
        }
    },
    "_embedded": {
        "tags": [
            {
                "id": 2164,
                "name": "Ex",
                "color": null
            }
        ],
        "companies": []
    }
}

Response parameters

The properties of the lead model are listed below.

Parameter Data type Description
id int Lead ID
name string Lead name
price int Lead sale
responsible_user_id int Lead responsible user ID
group_id int Group ID of the lead responsible user
status_id int ID of the stage the lead is added to, the first stage of the main pipeline by default
pipeline_id int ID of the pipeline the lead is added to
loss_reason_id int Lead loss reason ID
source_id int GET parameter “with” is required. Lead source ID
created_by int Id of the user who created the lead
updated_by int Id of the user who updated the lead
created_at int The time and date the lead was created in the format of Unix Timestamp
updated_at int The time and date the lead was updated in the format of Unix Timestamp
closed_at int The time and date the lead was closed in the format of Unix Timestamp
closest_task_at int The time and date of the closest open task in the format of Unix Timestamp
is_deleted bool Defines whether the lead was deleted
custom_fields_values array|null An array containing information on the values ​​of custom fields specified for this lead
score int|null Lead score
account_id int Account ID where the lead is located in
labor_cost int Shows how much time was spent working with the deal. Calculation time in seconds
is_price_modified_by_robot bool GET parameter “with” is required. Defines whether the lead sale value was changed by the Robot last time
_embedded object Embedded entities data
_embedded[loss_reason] object GET parameter “with” is required. Lead loss reason
_embedded[loss_reason][id] int Loss reason ID
_embedded[loss_reason][name] string Loss reason name
_embedded[tags] array Lead tags data array
_embedded[tags][0] object Lead tag model
_embedded[tags][0][id] int Tag ID
_embedded[tags][0][name] string Tag name
_embedded[contacts] array GET parameter “with” is required. Linked contacts data array
_embedded[contacts][0] object Linked contact data
_embedded[contacts][0][id] int Linked contact ID
_embedded[contacts][0][is_main] bool Defines whether the contact is main for the lead
_embedded[companies] array Linked company data array. This array always consists of 1 element as a lead can have only 1 company linked to it
_embedded[companies][0] object Linked company data
_embedded[companies][0][id] int Linked company ID
_embedded[catalog_elements] array GET parameter “with” is required. Linked lists’ elements data array
_embedded[catalog_elements][0] object Linked list element data
_embedded[catalog_elements][0][id] int Linked element ID
_embedded[catalog_elements][0][metadata] object Meta-data of the element
_embedded[catalog_elements][0][quantity] int Linked element quantity
_embedded[catalog_elements][0][catalog_id] int ID of the linked element’s list

Adding Leads

Method

POST /api/v4/leads

Description

This method allows adding multiple or singular 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

Request body example

In the following example we’ll create 2 leads.

For the first one, we’ll specify the Name, Sale, Pipeline, Creator, Status, and the value of a custom switch field.

For the second one, we’ll specify only the Name and price.

[
    {
        "name": "Example Lead 1",
        "created_by": 8375357,
        "price": 20000,
        "status_id": 58141807,
        "pipeline_id": 6950551,
        "custom_fields_values": [
            {
                "field_id": 184994,
                "values": [
                    {
                        "value": true
                    }
                ]
            }
        ]
    },
    {
        "name": "Example Lead 2",
        "price": 10000
    }
]

Body parameters

No fields are mandatory

Parameter Data type Description
name string Lead name.
price int Lead sale.
status_id int Stage ID the lead is added to. The first stage of the main pipeline by default
pipeline_id int Pipeline ID the lead is added to.
created_by int The ID of the user creating the lead. When passing the value 0, the lead will be considered as created by the robot.
updated_by int The ID of the user updating the lead. When passing the value 0, the lead will be considered as created by the robot.
created_at int Lead creation date in the format of Unix Timestamp.
updated_at int Lead update date in the format of Unix Timestamp.
closed_at int Lead closure date in the format of Unix Timestamp.
loss_reason_id int Lead loss reason ID.
responsible_user_id int Lead responsible user ID.
custom_fields_values array An array of the current lead custom fields’ values. Examples of custom fields structure
_embedded object Embedded entities data, only tags can be passed when creating or updating a lead.
_embedded[tags] array|null Data of the tags added to a lead
_embedded[tags][0] object Model of the tag added to a lead. If filled then either the tag’s ID or name is required
_embedded[tags][0][id] int Tag ID
_embedded[tags][0][name] string Tag name
request_id string Field that will be returned unchanged in the response and will not be saved.

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 Leads have been created successfully
401 User is not authorized
400 Invalid data given. Details are available in the request response

Response parameters

Method returns a collection of created leads.

Response example

{
    "_links": {
        "self": {
            "href": "https://devteam.kommo.com/api/v4/leads"
        }
    },
    "_embedded": {
        "leads": [
            {
                "id": 152462,
                "request_id": "0",
                "_links": {
                    "self": {
                        "href": "https://devteam.kommo.com/api/v4/leads/152462"
                    }
                }
            },
            {
                "id": 152464,
                "request_id": "1",
                "_links": {
                    "self": {
                        "href": "https://devteam.kommo.com/api/v4/leads/152464"
                    }
                }
            }
        ]
    }
}

Updating Leads

Method

PATCH /api/v4/leads

Description

This method allows updating multiple leads.

To update a singular lead, you can add the lead ID into the method URL (/api/v4/leads/{id}).

When updating multiple leads, an array of lead objects is passed. In case with a singular lead, the lead model is passed.

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

Request body example

In the following example we’ll update 2 leads.

For the first one, we’ll change the Name, price, and status, and we’ll add the value of a custom field.

For the second one, we’ll change the only the price and the pipeline.

[
    {
        "id": 152464,
        "name": "Lead with Sam",
        "price": 12000,
        "status_id": 58141811,
        "custom_fields_values": [
            {
                "field_id": 184994,
                "values": [
                    {
                        "value": true
                    }
                ]
            }
        ]
    },
    {
        "id": 152462,
        "price": 15000,
        "pipeline_id": 6954751
    }
]

Body parameters

No fields are mandatory

Parameter Data type Description
name string Lead name.
price int Lead sale.
status_id int Stage ID the lead is added to. The first stage of the main pipeline by default
pipeline_id int Pipeline ID the lead is added to.
created_by int The ID of the user creating the lead. When passing the value 0, the lead will be considered as created by the robot.
updated_by int The ID of the user updating the lead. When passing the value 0, the lead will be considered as created by the robot.
created_at int Lead creation date in the format of Unix Timestamp.
updated_at int Lead update date in the format of Unix Timestamp.
closed_at int Lead closure date in the format of Unix Timestamp.
loss_reason_id int Lead loss reason ID.
responsible_user_id int Lead responsible user ID.
custom_fields_values array An array of the current lead custom fields’ values. Examples of custom fields structure
_embedded object Embedded entities data, only tags can be passed when creating or updating a lead.
_embedded[tags] array|null Data of the tags added to a lead
_embedded[tags][0] object Model of the tag added to a lead. If filled then either the tag’s ID or name is required
_embedded[tags][0][id] int Tag ID
_embedded[tags][0][name] string Tag name
request_id string Field that will be returned unchanged in the response and will not be saved.

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 Leads have been updated successfully
401 User is not authorized
400 Invalid data given. Details are available in the request response

Response parameters

Method returns a collection of the updated leads.

Response example

{
    "_links": {
        "self": {
            "href": "https://devteam.kommo.com/api/v4/leads"
        }
    },
    "_embedded": {
        "leads": [
            {
                "id": 152464,
                "updated_at": 1686732474,
                "_links": {
                    "self": {
                        "href": "https://devteam.kommo.com/api/v4/leads/152464"
                    }
                }
            },
            {
                "id": 152462,
                "updated_at": 1686732474,
                "_links": {
                    "self": {
                        "href": "https://devteam.kommo.com/api/v4/leads/152462"
                    }
                }
            }
        ]
    }
}

Complex addition of leads with contact and company

Method

POST /api/v4/leads/complex

Description

The method allows you to add leads with contacts and a company to your account in batches. The added data can be checked in the duplicate control.

Restrictions

  • The method is available according to the user’s rights.
  • For one lead, you can specify no more than one related contact and one related company.
  • For added entities (lead, contact, company), you can transfer no more than 40 values of additional fields.
  • The data you add participates in duplicate control if the option is enabled for the integration that adds the data.
  • The method does not perform duplicate control for already added leads against each other.
  • The method does not perform duplicate control for leads in the same request.
  • The method searches for duplicates among the current added leads against the already added ones.
  • You can transfer no more than 50 transactions per request.
  • When you create a new contact and company, they will be linked together.

Request header

Content-Type: application/json

Request body example

In this example, we will create a lead with a contact and a company, as well as an incoming lead of the form category in the incoming lead status with contact.

[
 {
    "name": "New lead 1",
    "price": 2222,
    "_embedded":{
       "contacts":[
          {
             "first_name":"Adam",
             "created_at":1668784888,
             "responsible_user_id":8375357,
             "custom_fields_values": [
                  {
                      "field_id": 562166,
                      "field_name": "Phone",
                      "values": [
                          {
                              "value": "0965423364",
                              "enum_code": "WORK"
                          }
                      ]
                  }
              ],
             "updated_by":0
          }
       ],
       "companies":[
          {
             "name":"Kommo"
          }
       ]
    },
    "created_at":1668784001,
    "responsible_user_id":8375357,
    "status_id":49366079,
    "pipeline_id":5597036,
    "request_id": "1"
 }
]

Body parameters

Parameter Data type Description
name string Lead name
price int Lead price
status_id int ID of the stage the lead is added to, the first stage of the main pipeline by default
pipeline_id int ID of the pipeline the lead is added to
created_by int Id of the user who created the lead
updated_by int Id of the user who updated the lead
created_at int The time and date the lead was created in the format of Unix Timestamp
updated_at int The time and date the lead was updated in the format of Unix Timestamp
closed_at int Lead closure date in the format of Unix Timestamp
loss_reason_id int Lead loss reason ID
responsible_user_id int Lead responsible user ID
group_id int Group ID of the lead responsible user
source_id int GET parameter “with” is required. Lead source ID
closest_task_at int Date of the closest open task in the format of Unix Timestamp
is_deleted bool Defines whether the lead was deleted
custom_fields_values array| null An array containing information about additional fields specified for the added lead. The field is optional. Examples of custom field values. You can transfer no more than 40 fields for one lead. If you need to pass more, you can perform an update operation after creation or create through a common method that does not check for duplicates.
_embedded object Embedded entities data
_embedded[tags] array Lead tags data array
_embedded[tags][0] object Lead tag model
_embedded[tags][0][id] int Tag ID
_embedded[contacts] array Linked contacts data array. This array always consists of 1 element as the method accepts only one contact.
_embedded[contacts][0] object Linked contact data, entered in the same way you add a contact.
_embedded[companies] array Linked company data array. This array always consists of 1 element, as a lead can have only one company linked to it.
_embedded[companies][0] object Linked company data, entered the same way you add a company.
_embedded[metadata] object An array containing the metadata for the entity being created in the incoming lead. If metadata is passed, we consider it to be an incoming lead, and any status passed other than the incoming lead will be ignored. The parameters are the same as those passed when creating an incoming lead, except for the need to pass an additional category key. Read more about metadata parameters.
_embedded[metadata][category] string Incoming lead category. Valid options are sip and forms.
_embedded[source][external_id] int The external ID of the source. A source can be added using the Sources API. If the external_id of the source is passed and the pipeline_id is not passed, the lead will be added to the pipeline where the source is located.
_embedded[source][type] string Source type. For leads added by integrations, only the widget is supported

Data type header on success

Content-Type: application/hal+json

Data type header on error

Content-Type: application/problem+json

HTTP response codes

Response code Condition
200 Leads have been successfully created
401 User not authorized
400 Incorrect data transmitted. Details are available in the response body

Response example

The first time you enter the lead, it will be added normally.

[
   {
       "id": 9774766,
       "contact_id": 12117258,
       "company_id": 12117260,
       "request_id": [
           "1"
       ],
       "merged": false
   }
]

Now, let’s change in the request body a little bit. For example, let’s change the request name and id and send it again. According to the duplicate control rules in our account and pipeline where we perform the request, the lead is considered a duplicate. The response with the true value of the merged flag is received.

[
   {
       "id": 9774766,
       "contact_id": 12117258,
       "company_id": 12117260,
       "request_id": [
           "2"
       ],
       "merged": true
   }
]

Response parameters

Parameter Description
id Lead id
contact_id Contact id
company_id Company id
request_id An array of request IDs that have been added. If no duplicates were found, the array would always have one element. If multiple duplicates of the same lead are passed, the request_id array will contain the identifiers of the passed leads, which are duplicates.
merged A flag indicates whether a duplicate was found according to the conditions for searching for duplicates and whether the merging was performed.