Leads pipelines and statuses

In this section we will describe all available methods for working with Lead Pipelines and Statuses via API

Table of Contents

Commom information

  • Each pipeline has 3 system statuses: Incoming Leads, Closed – Won (ID = 142), Closed – Lost (ID = 143)
  • The limit for the pipelines number on the account is 50.
  • Each pipeline can have no more than 100 statuses including system ones.

Leads pipelines list

Method

GET /api/v4/leads/pipelines

Description

This method allows to get a list of pipelines on the account.

Limitations

Method is available for all account users.

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 a collection of pipeline models. The properties of the pipeline model are listed below.

Parameter Data type Description
id int Pipeline ID
name string Pipeline name
sort int Pipeline sorting
is_main bool Defines whether the pipeline is main for the account
is_unsorted_on bool Defines whether Incoming Leads are enabled
is_archive bool Defines whether the pipeline is archived
account_id int Account ID the pipeline is located in
_embedded[statuses] array Pipeline statuses data. Statuses are explained in detail below

Response example

        
{
    "_total_items": 1,
    "_links": {
        "self": {
            "href": "https://example.amocrm.com/api/v4/leads/pipelines"
        }
    },
    "_embedded": {
        "pipelines": [
            {
                "id": 3177727,
                "name": "Pipeline",
                "sort": 1,
                "is_main": true,
                "is_unsorted_on": true,
                "is_archive": false,
                "account_id": 12345678,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.com/api/v4/leads/pipelines/3177727"
                    }
                },
                "_embedded": {
                    "statuses": [
                        {
                            "id": 32392156,
                            "name": "Incoming leads",
                            "sort": 10,
                            "is_editable": false,
                            "pipeline_id": 3177727,
                            "color": "#c1c1c1",
                            "type": 1,
                            "account_id": 12345678,
                            "_links": {
                                "self": {
                                    "href": "https://example.amocrm.com/api/v4/leads/pipelines/3177727/statuses/32392156"
                                }
                            }
                        },
                        {
                            "id": 32392159,
                            "name": "Initial contact",
                            "sort": 20,
                            "is_editable": true,
                            "pipeline_id": 3177727,
                            "color": "#99ccff",
                            "type": 0,
                            "account_id": 12345678,
                            "_links": {
                                "self": {
                                    "href": "https://example.amocrm.com/api/v4/leads/pipelines/3177727/statuses/32392159"
                                }
                            }
                        },
                        {
                            "id": 32392165,
                            "name": "Decision making",
                            "sort": 30,
                            "is_editable": true,
                            "pipeline_id": 3177727,
                            "color": "#ffcc66",
                            "type": 0,
                            "account_id": 12345678,
                            "_links": {
                                "self": {
                                    "href": "https://example.amocrm.com/api/v4/leads/pipelines/3177727/statuses/32392165"
                                }
                            }
                        },
                        {
                            "id": 142,
                            "name": "Closed - Won",
                            "sort": 10000,
                            "is_editable": false,
                            "pipeline_id": 3177727,
                            "color": "#CCFF66",
                            "type": 0,
                            "account_id": 12345678,
                            "_links": {
                                "self": {
                                    "href": "https://example.amocrm.com/api/v4/leads/pipelines/3177727/statuses/142"
                                }
                            }
                        },
                        {
                            "id": 143,
                            "name": "Closed - Lost",
                            "sort": 11000,
                            "is_editable": false,
                            "pipeline_id": 3177727,
                            "color": "#D5D8DB",
                            "type": 0,
                            "account_id": 12345678,
                            "_links": {
                                "self": {
                                    "href": "https://example.amocrm.com/api/v4/leads/pipelines/3177727/statuses/143"
                                }
                            }
                        }
                    ]
                }
            }
        ]
    }
}
        
    

Getting a leads pipeline by its ID

Method

GET /api/v4/leads/pipelines/{id}

Description

This method allows to get a pipeline model.

Limitations

Method is available for all account users.

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 return a pipeline model. The properties of the pipeline model are listed below.

Parameter Data type Description
id int Pipeline ID
name string Pipeline name
sort int Pipeline sorting
is_main bool Defines whether the pipeline is main for the account
is_unsorted_on bool Defines whether Incoming Leads are enabled
is_archive bool Defines whether the pipeline is archived
account_id int Account ID the pipeline is located in
_embedded[statuses] array Pipeline statuses data. Statuses are explained in detail below

Response example

        
{
    "id": 3177727,
    "name": "Pipeline",
    "sort": 1,
    "is_main": true,
    "is_unsorted_on": true,
    "is_archive": false,
    "account_id": 28847170,
    "_links": {
        "self": {
            "href": "https://shard152.amocrm.com/api/v4/leads/pipelines/3177727"
        }
    },
    "_embedded": {
        "statuses": [
            {
                "id": 32392156,
                "name": "Incoming leads",
                "sort": 10,
                "is_editable": false,
                "pipeline_id": 3177727,
                "color": "#c1c1c1",
                "type": 1,
                "account_id": 28847170,
                "_links": {
                    "self": {
                        "href": "https://shard152.amocrm.com/api/v4/leads/pipelines/3177727/statuses/32392156"
                    }
                }
            },
            {
                "id": 32392159,
                "name": "Initial contact",
                "sort": 20,
                "is_editable": true,
                "pipeline_id": 3177727,
                "color": "#99ccff",
                "type": 0,
                "account_id": 28847170,
                "_links": {
                    "self": {
                        "href": "https://shard152.amocrm.com/api/v4/leads/pipelines/3177727/statuses/32392159"
                    }
                }
            },
            {
                "id": 32392165,
                "name": "Decision making",
                "sort": 30,
                "is_editable": true,
                "pipeline_id": 3177727,
                "color": "#ffcc66",
                "type": 0,
                "account_id": 28847170,
                "_links": {
                    "self": {
                        "href": "https://shard152.amocrm.com/api/v4/leads/pipelines/3177727/statuses/32392165"
                    }
                }
            },
            {
                "id": 142,
                "name": "Closed - Won",
                "sort": 10000,
                "is_editable": false,
                "pipeline_id": 3177727,
                "color": "#CCFF66",
                "type": 0,
                "account_id": 28847170,
                "_links": {
                    "self": {
                        "href": "https://shard152.amocrm.com/api/v4/leads/pipelines/3177727/statuses/142"
                    }
                }
            },
            {
                "id": 143,
                "name": "Closed - Lost",
                "sort": 11000,
                "is_editable": false,
                "pipeline_id": 3177727,
                "color": "#D5D8DB",
                "type": 0,
                "account_id": 28847170,
                "_links": {
                    "self": {
                        "href": "https://shard152.amocrm.com/api/v4/leads/pipelines/3177727/statuses/143"
                    }
                }
            }
        ]
    }
}
        
    

Adding pipelines

Method

POST /api/v4/leads/pipelines

Description

This method allows adding multiple pipelines into the account.

Limitations

Method is available for administrator users only.

Request header

Content-Type: application/json

Request parameters

Parameter Data type Description
name string Pipeline name. Is a mandatory parameter
sort int Pipeline sorting. Is a mandatory parameter
is_main bool Defines whether the pipeline is main for the account. Is a mandatory parameter
is_unsorted_on bool Defines whether Incoming Leads are enabled. Is a mandatory parameter
_embedded[statuses] array Pipeline statuses data. You can pass names for the system statuses 142 and 143 when adding a pipeline. Statuses are explained in detail below
request_id string Field that will be returned unchanged in the response and will not be saved. Is not a mandatory parameter

An example of the request

        
[
    {
        "name": "Additional pipeline",
        "is_main": false,
        "is_unsorted_on": true,
        "sort": 20,
        "request_id": "123",
        "_embedded": {
            "statuses": [
                {
                    "id": 142,
                    "name": "Won leads status custom name"
                },
                {
                    "name": "Initial contact",
                    "sort": 10,
                    "color": "#fffeb2"
                }
            ]
        }
    }
]
        
    

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 Pipelines have been added successfully
422 The passed data can not be processed. Details are available in the request response
403 Insufficient rights to call this method
401 User is not authorized
400 Invalid data given. Details are available in the request response

Response parameters

Method returns a collection of added pipeline models. The parameters are similar to the pipelines list request parameters.

Response example

        
{
    "_total_items": 1,
    "_links": {
        "self": {
            "href": "https://example.amocrm.com/api/v4/leads/pipelines"
        }
    },
    "_embedded": {
        "pipelines": [
            {
                "id": 3270358,
                "name": "Additional pipeline",
                "sort": 1,
                "is_main": true,
                "is_unsorted_on": false,
                "account_id": 1415131,
                "request_id": "123",
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.com/api/v4/leads/pipelines/3270358"
                    }
                },
                "_embedded": {
                    "statuses": [
                        {
                            "id": 3304,
                            "name": "Incoming leads",
                            "sort": 10,
                            "is_editable": false,
                            "pipeline_id": 3270358,
                            "color": "#c1c1c1",
                            "type": 1,
                            "account_id": 1415131,
                            "_links": {
                                "self": {
                                    "href": "https://example.amocrm.com/api/v4/leads/pipelines/3270358/statuses/3304"
                                }
                            }
                        },
                        {
                            "id": 3303,
                            "name": "Initial contact",
                            "sort": 20,
                            "is_editable": true,
                            "pipeline_id": 3270358,
                            "color": "#fffeb2",
                            "type": 0,
                            "account_id": 1415131,
                            "_links": {
                                "self": {
                                    "href": "https://example.amocrm.com/api/v4/leads/pipelines/3270358/statuses/3303"
                                }
                            }
                        },
                        {
                            "id": 142,
                            "name": "Won leads status custom name",
                            "sort": 10000,
                            "is_editable": false,
                            "pipeline_id": 3270358,
                            "color": "#CCFF66",
                            "type": 0,
                            "account_id": 1415131,
                            "_links": {
                                "self": {
                                    "href": "https://example.amocrm.com/api/v4/leads/pipelines/3270358/statuses/142"
                                }
                            }
                        },
                        {
                            "id": 143,
                            "name": "Closed - Lost",
                            "sort": 11000,
                            "is_editable": false,
                            "pipeline_id": 3270358,
                            "color": "#D5D8DB",
                            "type": 0,
                            "account_id": 1415131,
                            "_links": {
                                "self": {
                                    "href": "https://example.amocrm.com/api/v4/leads/pipelines/3270358/statuses/143"
                                }
                            }
                        }
                    ]
                }
            }
        ]
    }
}
        
    

Pipeline edit

Method

PATCH /api/v4/leads/pipelines/{id}

Description

This method allows editing the pipeline on the account.

Limitations

Method is available for administrator users only.

Request header

Content-Type: application/json

Request parameters

To edit a pipeline, at least one parameter should be passed

Parameter Data type Description
name string Pipeline name
sort int Pipeline sorting
is_main bool Defines whether the pipeline is main for the account
is_unsorted_on bool Defines whether Incoming Leads are enabled

An example of the request

        
{
    "name": "New pipeline name",
    "is_main": false,
    "is_unsorted_on": false,
    "sort": 100
}
        
    

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 Pipeline has been edited successfuly
403 Insufficient rights to call this method
401 User is not authorized
400 Invalid data given. Details are available in the request response

Response parameters

Method returns a model of the edited pipeline. The parameters are similar to the pipelines list request parameters.

Response example

        
{
    "id": 3177727,
    "name": "New pipeline name",
    "sort": 1000,
    "is_main": false,
    "is_unsorted_on": false,
    "is_archive": false,
    "account_id": 12345678,
    "request_id": "0",
    "_links": {
        "self": {
            "href": "https://example.amocrm.com/api/v4/leads/pipelines/3177727"
        }
    },
    "_embedded": {
        "statuses": [
            {
                "id": 32392159,
                "name": "Initial contact",
                "sort": 20,
                "is_editable": true,
                "pipeline_id": 3177727,
                "color": "#99ccff",
                "type": 0,
                "account_id": 12345678,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.com/api/v4/leads/pipelines/3177727/statuses/32392159"
                    }
                }
            },
            {
                "id": 32392165,
                "name": "Decision making",
                "sort": 30,
                "is_editable": true,
                "pipeline_id": 3177727,
                "color": "#ffcc66",
                "type": 0,
                "account_id": 12345678,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.com/api/v4/leads/pipelines/3177727/statuses/32392165"
                    }
                }
            },
            {
                "id": 142,
                "name": "Closed - Won",
                "sort": 10000,
                "is_editable": false,
                "pipeline_id": 3177727,
                "color": "#CCFF66",
                "type": 0,
                "account_id": 12345678,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.com/api/v4/leads/pipelines/3177727/statuses/142"
                    }
                }
            },
            {
                "id": 143,
                "name": "Closed - Lost",
                "sort": 11000,
                "is_editable": false,
                "pipeline_id": 3177727,
                "color": "#D5D8DB",
                "type": 0,
                "account_id": 12345678,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.com/api/v4/leads/pipelines/3177727/statuses/143"
                    }
                }
            }
        ]
    }
}
        
    

Deleting a pipeline

Method

DELETE /api/v4/leads/pipelines/{id}

Description

This method allows to delete a pipeline from the account.

Limitations

  • Method is available for administrator users only
  • It is not possible to delete the last pipeline on the account
  • It is not possible to delete a pipeline that still has leads in it

Request header

Content-Type: application/json

HTTP response codes.

Response code Case
204 Pipeline has been successfully deleted
403 Insufficient rights to call this method
401 User is not authorized
400 Invalid data given. Details are available in the request response

Response parameters

Method does not return a body

Pipeline statuses list

Method

GET /api/v4/leads/pipelines/{pipeline_id}/statuses

Description

This method allows to get a list of pipeline statuses on the account.

Limitations

Method is available for all account users.

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 return a status models collection. The properties of the status model are listed below.

Parameter Data type Description
id int Status ID
name string Status name
sort int Status sorting
is_editable bool Defines whether the status can be edited
pipeline_id int ID of the pipeline the status is located in
color string Status color. The list of available colors
type int Status type (1 – incoming leads, 0 – regular status)
account_id int Account ID the status is located in

Response example

        
{
    "_total_items": 1,
    "_links": {
        "self": {
            "href": "https://example.amocrm.com/api/v4/leads/pipelines"
        }
    },
    "_embedded": {
        "pipelines": [
            {
                "id": 3177727,
                "name": "Pipeline",
                "sort": 1,
                "is_main": true,
                "is_unsorted_on": true,
                "is_archive": false,
                "account_id": 12345678,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.com/api/v4/leads/pipelines/3177727"
                    }
                },
                "_embedded": {
                    "statuses": [
                        {
                            "id": 32392156,
                            "name": "Incoming leads",
                            "sort": 10,
                            "is_editable": false,
                            "pipeline_id": 3177727,
                            "color": "#c1c1c1",
                            "type": 1,
                            "account_id": 12345678,
                            "_links": {
                                "self": {
                                    "href": "https://example.amocrm.com/api/v4/leads/pipelines/3177727/statuses/32392156"
                                }
                            }
                        },
                        {
                            "id": 32392159,
                            "name": "Initial contact",
                            "sort": 20,
                            "is_editable": true,
                            "pipeline_id": 3177727,
                            "color": "#99ccff",
                            "type": 0,
                            "account_id": 12345678,
                            "_links": {
                                "self": {
                                    "href": "https://example.amocrm.com/api/v4/leads/pipelines/3177727/statuses/32392159"
                                }
                            }
                        },
                        {
                            "id": 32392165,
                            "name": "Decision making",
                            "sort": 30,
                            "is_editable": true,
                            "pipeline_id": 3177727,
                            "color": "#ffcc66",
                            "type": 0,
                            "account_id": 12345678,
                            "_links": {
                                "self": {
                                    "href": "https://example.amocrm.com/api/v4/leads/pipelines/3177727/statuses/32392165"
                                }
                            }
                        },
                        {
                            "id": 142,
                            "name": "Closed - Won",
                            "sort": 10000,
                            "is_editable": false,
                            "pipeline_id": 3177727,
                            "color": "#CCFF66",
                            "type": 0,
                            "account_id": 12345678,
                            "_links": {
                                "self": {
                                    "href": "https://example.amocrm.com/api/v4/leads/pipelines/3177727/statuses/142"
                                }
                            }
                        },
                        {
                            "id": 143,
                            "name": "Closed - Lost",
                            "sort": 11000,
                            "is_editable": false,
                            "pipeline_id": 3177727,
                            "color": "#D5D8DB",
                            "type": 0,
                            "account_id": 12345678,
                            "_links": {
                                "self": {
                                    "href": "https://example.amocrm.com/api/v4/leads/pipelines/3177727/statuses/143"
                                }
                            }
                        }
                    ]
                }
            }
        ]
    }
}
        
    

Getting a leads pipeline status data by its ID

Method

GET /api/v4/leads/pipelines/{pipeline_id}/statuses/{id}

Description

This method allows to get a leads pipeline status model by its ID.

Limitations

Method is available for all account users.

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 a status model. The properties of the status model are listed below.

Parameter Data type Description
id int Status ID
name string Status name
sort int Status sorting
is_editable bool Defines whether the status can be edited
pipeline_id int ID of the pipeline the status is located in
color string Status color. The list of available colors
type int Status type (1 – incoming leads, 0 – regular status)
account_id int Account ID the status is located in

Response example

        
{
    "id": 32392156,
    "name": "Incoming Leads",
    "sort": 10,
    "is_editable": false,
    "pipeline_id": 3177727,
    "color": "#c1c1c1",
    "type": 1,
    "account_id": 12345678,
    "_links": {
        "self": {
            "href": "https://example.amocrm.com/api/v4/leads/pipelines/3177727/statuses/32392156"
        }
    }
}
        
    

Adding statuses to the pipeline

Method

POST /api/v4/leads/pipelines/{pipeline_id}/statuses

Description

This method allows adding multiple statuses into the account.

Limitations

Method is available for administrator users only.

Request header

Content-Type: application/json

Request parameters

Parameter Data type Description
name string Status name. Is a mandatory parameter
sort int Status sorting. Is a mandatory parameter
color string Status color. The list of available colors. Is not a mandatory parameter
request_id string Field that will be returned unchanged in the response and will not be saved. Is not a mandatory parameter

An example of the request

        
[
    {
        "name": "New status",
        "sort": 100,
        "color": "#fffeb2"
    },
    {
        "name": "New status 2",
        "sort": 200,
        "color": "#fffeb2"
    }
]
        
    

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 Statuses have been added successfully
422 The passed data can not be processed. Details are available in the request response
403 Insufficient rights to call this method
401 User is not authorized
400 Invalid data given. Details are available in the request response

Response parameters

Method returns a collection of added status models. The parameters are similar to the statuses list request parameters.

Response example

        
{
    "_total_items": 2,
    "_embedded": {
        "statuses": [
            {
                "id": 33035290,
                "name": "New status",
                "sort": 60,
                "is_editable": true,
                "pipeline_id": 3270355,
                "color": "#fffeb2",
                "type": 0,
                "account_id": 1415131,
                "request_id": "0",
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.com/api/v4/leads/pipelines/3270355/statuses/33035290"
                    }
                }
            },
            {
                "id": 33035293,
                "name": "New status 2",
                "sort": 70,
                "is_editable": true,
                "pipeline_id": 3270355,
                "color": "#fffeb2",
                "type": 0,
                "account_id": 1415131,
                "request_id": "1",
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.com/api/v4/leads/pipelines/3270355/statuses/33035293"
                    }
                }
            }
        ]
    }
}
        
    

Pipeline status edit

Method

PATCH /api/v4/leads/pipelines/{pipeline_id}/statuses/{id}

Description

This method allows to edit a pipeline status.

Limitations

Method is available for administrator users only.

Request header

Content-Type: application/json

Request parameters

To edit a status, at least one parameter should be passed

Parameter Data type Description
name string Status name
sort int Status sorting
color string Status color. The list of available colors

An example of the request

        
{
    "name": "New status name",
    "color": "#c1e0ff"
}
        
    

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 Status has been edited successfully
403 Insufficient rights to call this method
401 User is not authorized
400 Invalid data given. Details are available in the request response

Response parameters

Method returns a model of the edited status. The parameters are similar to the statuses list request parameters.

Response example

        
{
    "id": 32392165,
    "name": "New status name",
    "sort": 20,
    "is_editable": true,
    "pipeline_id": 3177727,
    "color": "#c1e0ff",
    "type": 0,
    "account_id": 12345678,
    "request_id": "0",
    "_links": {
        "self": {
            "href": "https://example.amocrm.com/api/v4/leads/pipelines/3177727/statuses/32392165"
        }
    }
}
        
    

Deleting a pipeline status

Method

DELETE /api/v4/leads/pipelines/{pipeline_id}/statuses/{id}

Description

This method allows to delete a status from the account.

Limitations

  • Method is available for administrator users only
  • Leads located in the deleted status will be moved to the first pipeline status

Request header

Content-Type: application/json

HTTP response codes.

Response code Case
204 The status has been successfully deleted
403 Insufficient rights to call this method
401 User is not authorized
400 Invalid data given. Details are available in the request response

Response parameters

Method does not return a body

Available status colors

Color Color ID
#fffeb2
#fffd7f
#fff000
#ffeab2
#ffdc7f
#ffce5a
#ffdbdb
#ffc8c8
#ff8f92
#d6eaff
#c1e0ff
#98cbff
#ebffb1
#deff81
#87f2c0
#f9deff
#f3beff
#ccc8f9
#eb93ff
#f2f3f4
#e6e8ea