Get leads

get

https://{subdomain}.kommo.com/api/v4/leads

This method allows getting a list of leads in the account

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

“with”parameters

Parameter	Description
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.
loss_reason	Adds detailed information about the lead loss reason 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
catalog_elements	Adds lists items linked to the lead to the response
source_id	Adds the lead source ID to the response
source	Adds information about the source, its ID and name to the response

filter[statuses]

❗️
Due to the service limitations, you can filter only one stage in one pipeline. But it is possible to filter several stages within several pipelines outside of the service.

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

Response parameters

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
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][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[tags][0][color]	string/null	Tag color
_embedded[contacts]	array	GET parameter “with” is required. Linked contacts data array.
_embedded[contacts][0]	object	Linked contact data
_embedded[contacts][0][id]	ints	Linked contact ID
_embedded[contacts][0][is_main][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][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[source]	object	GET parameter "with" is required. Lead source
_embedded[source][id]	int	Lead source ID
_embedded[source][id]	string	Lead source name

Query Params

with

string

This parameter accepts a string which may consist of several values (look at the table above) separated by commas.

page

int32

Page of leads list

limit

string

The number of entities returned per request (limit – 250)

query

string

Search query (Searches through the filled fields of the entity)

order[created_at]

string

enum

Sorting the results

Allowed:

order[updated_at]

string

enum

Sorting the results

Allowed:

order[id]

string

enum

Sorting the results

Allowed:

filter[id][]

array of int32s

Filter by lead ID

filter[id][]

filter[name][]

array of strings

Filter by lead name

filter[name][]

filter[price]

int32

filter[created_by][]

array of int32s

Filter by ID of the user who created the entity.

filter[created_by][]

filter[updated_by][]

array of int32s

Filter by ID of the user who changed the entity last

filter[updated_by][]

filter[responsible_user_id][]

array of int32s

Filter by ID of the entity responsible user

filter[responsible_user_id][]

filter[created_at][from]

int32

Filter by the creation date of the lead. Date in Unix Timestamp format

filter[created_at][to]

int32

Filter by the creation date of the lead. Date in Unix Timestamp format

filter[updated_at][from]

int32

Filter by the last update date of the lead. Date in Unix Timestamp format.

filter[updated_at][to]

int32

Filter by the last update date of the lead. Date in Unix Timestamp format.

filter[closed_at][from]

int32

Filter by the lead closing date. Date in Unix Timestamp format.

filter[closed_at][to]

int32

Filter by the lead closing date. Date in Unix Timestamp format.

filter[closest_task_at][from]

int32

Filter leads by the date of the task closest to completion. Date in Unix Timestamp format.

filter[closest_task_at][to]

int32

Date in Unix Timestamp format. Date in Unix Timestamp format.

filter[pipeline_id][]

array of int32s

Filter by pipeline ID

filter[pipeline_id][]

filter[statuses][0][pipeline_id]

int32

Should be used with filter[statuses][0][status_id]. The filter allows you to filter leads based on their specific stages.

filter[statuses][0][status_id]

int32

Should be used with filter[statuses][0][pipeline_id]. The filter allows you to filter leads based on their specific stages.

Headers

string

enum

Defaults to application/json

Generated from available response content types

Allowed:

Responses

filter[statuses]

200200

204204

400400

401401

403403

429429

500500