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

Method is available in correspondense to the user rights.

GET parameters

Parameter Data type Description
with string This parameter takes a string which may consist of several values separated by commas. This method supports the following parameters.
page int Sample page
limit int The number of the entities returned in the response of one request (limit – 250)
query string|int Search query (will perform a search by custom fields values)
filter object Filter. Filters are described in detail in the separate article
order object List elements sorting
Fields available to sort by: created_at, updated_at, id.
Values available to sort by: asc, desc.
An example: /api/v4/leads?order[updated_at]=asc

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 User is not authorized

Response parameters

Method returns the lead models collection. 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 last
closed_at int Lead closure date in the format of Unix Timestamp
created_at int Lead creation date in the format of Unix Timestamp
updated_at int Lead update date in the format of Unix Timestamp
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 of the current lead custom fields’ values
score int|null Lead score
account_id int Account ID where the lead is located in
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

Response example

        
{
    "_page": 2,
    "_links": {
        "self": {
            "href": "https://example.amocrm.com/api/v4/leads?limit=2&page=2"
        },
        "next": {
            "href": "https://example.amocrm.com/api/v4/leads?limit=2&page=3"
        },
        "first": {
            "href": "https://example.amocrm.com/api/v4/leads?limit=2&page=1"
        },
        "prev": {
            "href": "https://example.amocrm.com/api/v4/leads?limit=2&page=1"
        }
    },
    "_embedded": {
        "leads": [
            {
                "id": 19619,
                "name": "Example lead",
                "price": 46333,
                "responsible_user_id": 123321,
                "group_id": 625,
                "status_id": 142,
                "pipeline_id": 1300,
                "loss_reason_id": null,
                "source_id": null,
                "created_by": 321123,
                "updated_by": 321123,
                "created_at": 1453279607,
                "updated_at": 1502193501,
                "closed_at": 1483005931,
                "closest_task_at": null,
                "is_deleted": false,
                "custom_fields_values": null,
                "score": null,
                "account_id": 5135160,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.com/api/v4/leads/19619"
                    }
                },
                "_embedded": {
                    "tags": [],
                    "companies": []
                }
            },
            {
                "id": 14460,
                "name": "Example lead 2",
                "price": 655,
                "responsible_user_id": 123321,
                "group_id": 625,
                "status_id": 142,
                "pipeline_id": 1300,
                "loss_reason_id": null,
                "source_id": null,
                "created_by": 321123,
                "updated_by": 321123,
                "created_at": 1453279607,
                "updated_at": 1502193501,
                "closed_at": 1483005931,
                "closest_task_at": null,
                "is_deleted": false,
                "custom_fields_values": null,
                "score": null,
                "account_id": 1351360,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.com/api/v4/leads/14460"
                    }
                },
                "_embedded": {
                    "tags": [],
                    "companies": []
                }
            }
        ]
    }
}

Parameters for GET-parameters “with”

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 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 deleted leads that are still restorable in the reseponse. You will receive lead models with the following properties: “id”, “updated_at”, “updated_by”, and “is_deleted” = true parameter.
source_id Adds the lead source ID into the response

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

Method is available in correspondense to the user rights.

GET parameters

Parameter Data type Description
with string This parameter takes a string which may consist of several values separated by commas. This method supports the following parameters.

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 parameters

Method returns a lead model. 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 last
closed_at int Lead closure date in the format of Unix Timestamp
created_at int Lead creation date in the format of Unix Timestamp
updated_at int Lead update date in the format of Unix Timestamp
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 of the current lead custom fields’ values
score int|null Lead score
account_id int Account ID where the lead is located in
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 elements quantity
_embedded[catalog_elements][0][catalog_id] int ID of the linked element’s list

Response example

        
{
    "id": 3912171,
    "name": "Example",
    "price": 12,
    "responsible_user_id": 504141,
    "group_id": 0,
    "status_id": 143,
    "pipeline_id": 3104455,
    "loss_reason_id": 4203748,
    "source_id": null,
    "created_by": 504141,
    "updated_by": 504141,
    "created_at": 1585299171,
    "updated_at": 1590683337,
    "closed_at": 1590683337,
    "closest_task_at": null,
    "is_deleted": false,
    "custom_fields_values": null,
    "score": null,
    "account_id": 28805383,
    "is_price_modified_by_robot": false,
    "_links": {
        "self": {
            "href": "https://example.amocrm.com/api/v4/leads/3912171"
        }
    },
    "_embedded": {
        "tags": [
            {
                "id": 100667,
                "name": "test"
            }
        ],
        "catalog_elements": [
            {
                "id": 525439,
                "metadata": {
                    "quantity": 1,
                    "catalog_id": 4521
                }
            }
        ],
        "loss_reason": [
            {
                "id": 4203748,
                "name": "Unsufficient budget",
                "sort": 100000,
                "created_at": 1582117280,
                "updated_at": 1582117280,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.com/api/v4/leads/loss_reasons/4203748"
                    }
                }
            }
        ],
        "companies": [
            {
                "id": 10971463,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.com/api/v4/companies/10971463"
                    }
                }
            }
        ],
        "contacts": [
            {
                "id": 10971465,
                "is_main": true,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.com/api/v4/contacts/10971465"
                    }
                }
            }
        ]
    }
}

Parameters for GET-parameters “with”

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 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 deleted leads that are still restorable in the reseponse. You will receive a lead model with the following properties: “id”, “updated_at”, “updated_by”, and “is_deleted” = true parameter.
source_id Adds the lead source ID into the response

Adding Leads

Method

POST /api/v4/leads

Description

This method allows adding multiple or singular leads into the account

Limitations

Method is available in correspondense to the user rights.

Request header

Content-Type: application/json

Request parameters

No fields are mandatory

Parameter Data type Description
name string Lead name. Is not a mandatory field
price int Lead sale. Is not a mandatory field
status_id int Stage ID the lead is added to. Is not a mandatory field, the first stage of the main pipeline by default
pipeline_id int Pipeline ID the lead is added to. Is not a mandatory field
created_by int ID of the user who created the lead. If value 0 is passed, it is concidered that a lead is created by Robot. Is not a mandatory field
updated_by int ID of the user who updated the lead last. If value 0 is passed, it is concidered that a lead is updated by Robot. Is not a mandatory field
closed_at int Lead closure date in the format of Unix Timestamp. Is not a mandatory field
created_at int Lead creation date in the format of Unix Timestamp. Is not a mandatory field
updated_at int Lead update date in the format of Unix Timestamp. Is not a mandatory field
loss_reason_id int Lead loss reason ID. Is not a mandatory field
responsible_user_id int Lead responsible user ID. Is not a mandatory field
custom_fields_values array An array of the current lead custom fields’ values. Is not a mandatory field. Examples of custom fields structure
_embedded object Embedded entities data, only tags can be passed when creating or updating a lead. Is not a mandatory field
_embedded[tags] array|null Data of the tags added to a lead
_embedded[tags][0] object Model of the tag added to a lead. ID or name parameter 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. Is not a mandatory field

An example of the request

In the following example we’ll create 2 leads.
For the first one, we’ll specify the Name, Sale, Creator – Robot, and the value of a text field.
For the second one, we’ll specify the Name, Sale, and will add a Tag. 

        
[
    {
        "name": "Example Lead 1",
        "created_by": 0,
        "price": 20000,
        "custom_fields_values": [
            {
                "field_id": 294471,
                "values": [
                    {
                        "value": "Our first client"
                    }
                ]
            }
        ]
    },
    {
        "name": "Example Lead 2",
        "price": 10000,
        "_embedded": {
            "tags": [
                {
                    "id": 2719
                }
            ]
        }
    }
]

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://example.amocrm.com/api/v4/leads"
        }
    },
    "_embedded": {
        "leads": [
            {
                "id": 10185151,
                "request_id": "0",
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.com/api/v4/leads/10185151"
                    }
                }
            },
            {
                "id": 10185153,
                "request_id": "1",
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.com/api/v4/leads/10185153"
                    }
                }
            }
        ]
    }
}

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

Method is available in correspondense to the user rights.

Request header

Content-Type: application/json

Request parameters

No fields are mandatory

Parameter Data type Description
name string Lead name. Is not a mandatory field
price int Lead sale. Is not a mandatory field
status_id int Stage ID the lead is updated in. Is not a mandatory field, the first stage of the main pipeline by default
pipeline_id int Pipeline ID the lead is updated in. Is not a mandatory field
created_by int ID of the user who created the lead. If value 0 is passed, it is concidered that a lead is created by Robot. Is not a mandatory field
updated_by int ID of the user who updated the lead last. If value 0 is passed, it is concidered that a lead is updated by Robot. Is not a mandatory field
closed_at int Lead closure date in the format of Unix Timestamp. Is not a mandatory field
created_at int Lead creation date in the format of Unix Timestamp. Is not a mandatory field
updated_at int Lead update date in the format of Unix Timestamp. Is not a mandatory field
loss_reason_id int Lead loss reason ID. Is not a mandatory field
responsible_user_id int Lead responsible user ID. Is not a mandatory field
custom_fields_values array An array of the current lead custom fields’ values. Is not a mandatory field. Examples of custom fields structure
_embedded object Embedded entities data, only tags can be passed when creating or updating a lead. Is not a mandatory field
_embedded[tags] array|null Data of the tags added to a lead
_embedded[tags][0] object Model of the tag added to a lead. ID or name parameter 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. Is not a mandatory field

An example of the request

In the following example we’ll update 2 leads.
For the first one, we’ll change the Stage and Pipeline, add the Loss reason and the Closure date.
For the second one, we’ll change the Lead Sale, Stage, Pipeline, and delete Tags.

        
[
    {
        "id": 54886,
        "pipeline_id": 47521,
        "status_id": 143,
        "date_close": 1589297221,
        "loss_reason_id": 7323,
        "updated_by": 0
    },
    {
        "id": 54884,
        "price": 50000,
        "pipeline_id": 47521,
        "status_id": 525743,
        "_embedded": {
            "tags": null
        }
    }
]

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 updated leads.

Response example

        
{
    "_links": {
        "self": {
            "href": "https://example.amocrm.com/api/v4/leads"
        }
    },
    "_embedded": {
        "leads": [
            {
                "id": 54886,
                "updated_at": 1589556420,
                "request_id": "0",
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.com/api/v4/leads/54886"
                    }
                }
            },
            {
                "id": 54884,
                "updated_at": 1589556420,
                "request_id": "1",
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.com/api/v4/leads/54884"
                    }
                }
            }
        ]
    }
}