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

Common information

  • Each pipeline has 3 system statuses: Incoming Leads, Closed – Won (ID = 142), Closed – Lost (ID = 143)
  • The limit for the number of the pipeline 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

The method is available for all account users.

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

Response example

The method returns a collection of pipeline models.

{
    "_total_items": 2,
    "_links": {
        "self": {
            "href": "https://devteam.kommo.com/api/v4/leads/pipelines"
        }
    },
    "_embedded": {
        "pipelines": [
            {
                "id": 6950551,
                "name": "Pipeline",
                "sort": 1,
                "is_main": true,
                "is_unsorted_on": true,
                "is_archive": false,
                "account_id": 31361463,
                "_links": {
                    "self": {
                        "href": "https://devteam.kommo.com/api/v4/leads/pipelines/6950551"
                    }
                },
                "_embedded": {
                    "statuses": [
                        {
                            "id": 58141803,
                            "name": "Incoming leads",
                            "sort": 10,
                            "is_editable": false,
                            "pipeline_id": 6950551,
                            "color": "#c1c1c1",
                            "type": 1,
                            "account_id": 31361463,
                            "_links": {
                                "self": {
                                    "href": "https://devteam.kommo.com/api/v4/leads/pipelines/6950551/statuses/58141803"
                                }
                            }
                        },
                        {
                            "id": 58141807,
                            "name": "Initial contact",
                            "sort": 20,
                            "is_editable": true,
                            "pipeline_id": 6950551,
                            "color": "#99ccff",
                            "type": 0,
                            "account_id": 31361463,
                            "_links": {
                                "self": {
                                    "href": "https://devteam.kommo.com/api/v4/leads/pipelines/6950551/statuses/58141807"
                                }
                            }
                        },
                        {
                            "id": 58141811,
                            "name": "Discussions",
                            "sort": 30,
                            "is_editable": true,
                            "pipeline_id": 6950551,
                            "color": "#ffff99",
                            "type": 0,
                            "account_id": 31361463,
                            "_links": {
                                "self": {
                                    "href": "https://devteam.kommo.com/api/v4/leads/pipelines/6950551/statuses/58141811"
                                }
                            }
                        },
                        {
                            "id": 58141815,
                            "name": "Decision making",
                            "sort": 40,
                            "is_editable": true,
                            "pipeline_id": 6950551,
                            "color": "#ffcc66",
                            "type": 0,
                            "account_id": 31361463,
                            "_links": {
                                "self": {
                                    "href": "https://devteam.kommo.com/api/v4/leads/pipelines/6950551/statuses/58141815"
                                }
                            }
                        },
                        {
                            "id": 58141819,
                            "name": "Contract discussion",
                            "sort": 50,
                            "is_editable": true,
                            "pipeline_id": 6950551,
                            "color": "#ffcccc",
                            "type": 0,
                            "account_id": 31361463,
                            "_links": {
                                "self": {
                                    "href": "https://devteam.kommo.com/api/v4/leads/pipelines/6950551/statuses/58141819"
                                }
                            }
                        },
                        {
                            "id": 142,
                            "name": "Closed - won",
                            "sort": 10000,
                            "is_editable": false,
                            "pipeline_id": 6950551,
                            "color": "#CCFF66",
                            "type": 0,
                            "account_id": 31361463,
                            "_links": {
                                "self": {
                                    "href": "https://devteam.kommo.com/api/v4/leads/pipelines/6950551/statuses/142"
                                }
                            }
                        },
                        {
                            "id": 143,
                            "name": "Closed - lost",
                            "sort": 11000,
                            "is_editable": false,
                            "pipeline_id": 6950551,
                            "color": "#D5D8DB",
                            "type": 0,
                            "account_id": 31361463,
                            "_links": {
                                "self": {
                                    "href": "https://devteam.kommo.com/api/v4/leads/pipelines/6950551/statuses/143"
                                }
                            }
                        }
                    ]
                }
            },
            {
                "id": 6954751,
                "name": "Pipeline 2",
                "sort": 2,
                "is_main": false,
                "is_unsorted_on": true,
                "is_archive": false,
                "account_id": 31361463,
                "_links": {
                    "self": {
                        "href": "https://devteam.kommo.com/api/v4/leads/pipelines/6954751"
                    }
                },
                "_embedded": {
                    "statuses": [
                        {
                            "id": 58166539,
                            "name": "Incoming leads",
                            "sort": 10,
                            "is_editable": false,
                            "pipeline_id": 6954751,
                            "color": "#c1c1c1",
                            "type": 1,
                            "account_id": 31361463,
                            "_links": {
                                "self": {
                                    "href": "https://devteam.kommo.com/api/v4/leads/pipelines/6954751/statuses/58166539"
                                }
                            }
                        },
                        {
                            "id": 58166543,
                            "name": "Accepting",
                            "sort": 20,
                            "is_editable": true,
                            "pipeline_id": 6954751,
                            "color": "#99ccff",
                            "type": 0,
                            "account_id": 31361463,
                            "_links": {
                                "self": {
                                    "href": "https://devteam.kommo.com/api/v4/leads/pipelines/6954751/statuses/58166543"
                                }
                            }
                        },
                        {
                            "id": 58166551,
                            "name": "Negotiation",
                            "sort": 30,
                            "is_editable": true,
                            "pipeline_id": 6954751,
                            "color": "#ffcc66",
                            "type": 0,
                            "account_id": 31361463,
                            "_links": {
                                "self": {
                                    "href": "https://devteam.kommo.com/api/v4/leads/pipelines/6954751/statuses/58166551"
                                }
                            }
                        },
                        {
                            "id": 142,
                            "name": "Closed - won",
                            "sort": 10000,
                            "is_editable": false,
                            "pipeline_id": 6954751,
                            "color": "#CCFF66",
                            "type": 0,
                            "account_id": 31361463,
                            "_links": {
                                "self": {
                                    "href": "https://devteam.kommo.com/api/v4/leads/pipelines/6954751/statuses/142"
                                }
                            }
                        },
                        {
                            "id": 143,
                            "name": "Closed - lost",
                            "sort": 11000,
                            "is_editable": false,
                            "pipeline_id": 6954751,
                            "color": "#D5D8DB",
                            "type": 0,
                            "account_id": 31361463,
                            "_links": {
                                "self": {
                                    "href": "https://devteam.kommo.com/api/v4/leads/pipelines/6954751/statuses/143"
                                }
                            }
                        }
                    ]
                }
            }
        ]
    }
}

Response parameters

The properties of the pipeline model are listed in the following table.

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

Getting a leads pipeline by its ID

Method

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

Description

This method allows to get a pipeline model.

Limitations

The method is available for all account users.

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

Response example

The method returns a pipeline model.

{
    "id": 6950551,
    "name": "Pipeline",
    "sort": 1,
    "is_main": true,
    "is_unsorted_on": true,
    "is_archive": false,
    "account_id": 31361463,
    "_links": {
        "self": {
            "href": "https://devteam.kommo.com/api/v4/leads/pipelines/6950551"
        }
    },
    "_embedded": {
        "statuses": [
            {
                "id": 58141803,
                "name": "Incoming leads",
                "sort": 10,
                "is_editable": false,
                "pipeline_id": 6950551,
                "color": "#c1c1c1",
                "type": 1,
                "account_id": 31361463,
                "_links": {
                    "self": {
                        "href": "https://devteam.kommo.com/api/v4/leads/pipelines/6950551/statuses/58141803"
                    }
                }
            },
            {
                "id": 58141807,
                "name": "Initial contact",
                "sort": 20,
                "is_editable": true,
                "pipeline_id": 6950551,
                "color": "#99ccff",
                "type": 0,
                "account_id": 31361463,
                "_links": {
                    "self": {
                        "href": "https://devteam.kommo.com/api/v4/leads/pipelines/6950551/statuses/58141807"
                    }
                }
            },
            {
                "id": 58141811,
                "name": "Discussions",
                "sort": 30,
                "is_editable": true,
                "pipeline_id": 6950551,
                "color": "#ffff99",
                "type": 0,
                "account_id": 31361463,
                "_links": {
                    "self": {
                        "href": "https://devteam.kommo.com/api/v4/leads/pipelines/6950551/statuses/58141811"
                    }
                }
            },
            {
                "id": 58141815,
                "name": "Decision making",
                "sort": 40,
                "is_editable": true,
                "pipeline_id": 6950551,
                "color": "#ffcc66",
                "type": 0,
                "account_id": 31361463,
                "_links": {
                    "self": {
                        "href": "https://devteam.kommo.com/api/v4/leads/pipelines/6950551/statuses/58141815"
                    }
                }
            },
            {
                "id": 58141819,
                "name": "Contract discussion",
                "sort": 50,
                "is_editable": true,
                "pipeline_id": 6950551,
                "color": "#ffcccc",
                "type": 0,
                "account_id": 31361463,
                "_links": {
                    "self": {
                        "href": "https://devteam.kommo.com/api/v4/leads/pipelines/6950551/statuses/58141819"
                    }
                }
            },
            {
                "id": 142,
                "name": "Closed - won",
                "sort": 10000,
                "is_editable": false,
                "pipeline_id": 6950551,
                "color": "#CCFF66",
                "type": 0,
                "account_id": 31361463,
                "_links": {
                    "self": {
                        "href": "https://devteam.kommo.com/api/v4/leads/pipelines/6950551/statuses/142"
                    }
                }
            },
            {
                "id": 143,
                "name": "Closed - lost",
                "sort": 11000,
                "is_editable": false,
                "pipeline_id": 6950551,
                "color": "#D5D8DB",
                "type": 0,
                "account_id": 31361463,
                "_links": {
                    "self": {
                        "href": "https://devteam.kommo.com/api/v4/leads/pipelines/6950551/statuses/143"
                    }
                }
            }
        ]
    }
}

Response parameters

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

Adding pipelines

Method

POST /api/v4/leads/pipelines

Description

This method allows adding multiple pipelines into the account.

Limitations

The method is available for administrator users only.

Authorization type

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

Request header

Content-Type: application/json

Request body example

[
    {
        "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"
                }
            ]
        }
    }
]

Body parameters

Parameter Data type Description
name string Pipeline name. It is a mandatory parameter
sort int Pipeline sorting. It is a mandatory parameter
is_main bool Defines whether the pipeline is main for the account. It is a mandatory parameter
is_unsorted_on bool Defines whether Incoming Leads are enabled. It 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 The field that will be returned unchanged in the response and will not be saved. It is not a mandatory parameter

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 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 added pipeline models. The parameters are similar to the pipelines list request parameters.

Response example

{
    "_total_items": 1,
    "_links": {
        "self": {
            "href": "https://devteam.kommo.com/api/v4/leads/pipelines"
        }
    },
    "_embedded": {
        "pipelines": [
            {
                "id": 6964299,
                "name": "Additional pipeline",
                "sort": 20,
                "is_main": false,
                "is_unsorted_on": true,
                "is_archive": false,
                "account_id": 31361463,
                "request_id": "123",
                "_links": {
                    "self": {
                        "href": "https://devteam.kommo.com/api/v4/leads/pipelines/6964299"
                    }
                },
                "_embedded": {
                    "statuses": [
                        {
                            "id": 58220123,
                            "name": "Incoming leads",
                            "sort": 10,
                            "is_editable": false,
                            "pipeline_id": 6964299,
                            "color": "#c1c1c1",
                            "type": 1,
                            "account_id": 31361463,
                            "_links": {
                                "self": {
                                    "href": "https://devteam.kommo.com/api/v4/leads/pipelines/6964299/statuses/58220123"
                                }
                            }
                        },
                        {
                            "id": 58220127,
                            "name": "Initial contact",
                            "sort": 20,
                            "is_editable": true,
                            "pipeline_id": 6964299,
                            "color": "#fffeb2",
                            "type": 0,
                            "account_id": 31361463,
                            "_links": {
                                "self": {
                                    "href": "https://devteam.kommo.com/api/v4/leads/pipelines/6964299/statuses/58220127"
                                }
                            }
                        },
                        {
                            "id": 142,
                            "name": "Won leads status custom name",
                            "sort": 10000,
                            "is_editable": false,
                            "pipeline_id": 6964299,
                            "color": "#CCFF66",
                            "type": 0,
                            "account_id": 31361463,
                            "_links": {
                                "self": {
                                    "href": "https://devteam.kommo.com/api/v4/leads/pipelines/6964299/statuses/142"
                                }
                            }
                        },
                        {
                            "id": 143,
                            "name": "Closed - lost",
                            "sort": 11000,
                            "is_editable": false,
                            "pipeline_id": 6964299,
                            "color": "#D5D8DB",
                            "type": 0,
                            "account_id": 31361463,
                            "_links": {
                                "self": {
                                    "href": "https://devteam.kommo.com/api/v4/leads/pipelines/6964299/statuses/143"
                                }
                            }
                        }
                    ]
                }
            }
        ]
    }
}

Editing a pipeline

Method

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

Description

This method allows editing the pipeline on the account.

Limitations

The method is available for administrator users only.

Authorization type

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

Request header

Content-Type: application/json

Request body example

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

Body 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

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

Response parameters

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

Response example

{
    "id": 6964299,
    "name": "New pipeline name",
    "sort": 100,
    "is_main": false,
    "is_unsorted_on": false,
    "is_archive": false,
    "account_id": 31361463,
    "request_id": "0",
    "_links": {
        "self": {
            "href": "https://devteam.kommo.com/api/v4/leads/pipelines/6964299"
        }
    },
    "_embedded": {
        "statuses": [
            {
                "id": 58220127,
                "name": "Initial contact",
                "sort": 20,
                "is_editable": true,
                "pipeline_id": 6964299,
                "color": "#fffeb2",
                "type": 0,
                "account_id": 31361463,
                "_links": {
                    "self": {
                        "href": "https://devteam.kommo.com/api/v4/leads/pipelines/6964299/statuses/58220127"
                    }
                }
            },
            {
                "id": 142,
                "name": "Won leads status custom name",
                "sort": 10000,
                "is_editable": false,
                "pipeline_id": 6964299,
                "color": "#CCFF66",
                "type": 0,
                "account_id": 31361463,
                "_links": {
                    "self": {
                        "href": "https://devteam.kommo.com/api/v4/leads/pipelines/6964299/statuses/142"
                    }
                }
            },
            {
                "id": 143,
                "name": "Closed - lost",
                "sort": 11000,
                "is_editable": false,
                "pipeline_id": 6964299,
                "color": "#D5D8DB",
                "type": 0,
                "account_id": 31361463,
                "_links": {
                    "self": {
                        "href": "https://devteam.kommo.com/api/v4/leads/pipelines/6964299/statuses/143"
                    }
                }
            }
        ]
    }
} 

Deleting a pipeline

Method

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

Description

This method allows to delete a pipeline from the account.

Limitations

  • The 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

Authorization type

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

Request header

Content-Type: application/json

HTTP response codes.

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

Response parameters

The 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

The method is available for all account users.

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

Response parameters

The method returns 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 The 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": 7,
    "_embedded": {
        "statuses": [
            {
                "id": 58141803,
                "name": "Incoming leads",
                "sort": 10,
                "is_editable": false,
                "pipeline_id": 6950551,
                "color": "#c1c1c1",
                "type": 1,
                "account_id": 31361463,
                "_links": {
                    "self": {
                        "href": "https://devteam.kommo.com/api/v4/leads/pipelines/6950551/statuses/58141803"
                    }
                }
            },
            {
                "id": 58141807,
                "name": "Initial contact",
                "sort": 20,
                "is_editable": true,
                "pipeline_id": 6950551,
                "color": "#99ccff",
                "type": 0,
                "account_id": 31361463,
                "_links": {
                    "self": {
                        "href": "https://devteam.kommo.com/api/v4/leads/pipelines/6950551/statuses/58141807"
                    }
                }
            },
            {
                "id": 58141811,
                "name": "Discussions",
                "sort": 30,
                "is_editable": true,
                "pipeline_id": 6950551,
                "color": "#ffff99",
                "type": 0,
                "account_id": 31361463,
                "_links": {
                    "self": {
                        "href": "https://devteam.kommo.com/api/v4/leads/pipelines/6950551/statuses/58141811"
                    }
                }
            },
            {
                "id": 58141815,
                "name": "Decision making",
                "sort": 40,
                "is_editable": true,
                "pipeline_id": 6950551,
                "color": "#ffcc66",
                "type": 0,
                "account_id": 31361463,
                "_links": {
                    "self": {
                        "href": "https://devteam.kommo.com/api/v4/leads/pipelines/6950551/statuses/58141815"
                    }
                }
            },
            {
                "id": 58141819,
                "name": "Contract discussion",
                "sort": 50,
                "is_editable": true,
                "pipeline_id": 6950551,
                "color": "#ffcccc",
                "type": 0,
                "account_id": 31361463,
                "_links": {
                    "self": {
                        "href": "https://devteam.kommo.com/api/v4/leads/pipelines/6950551/statuses/58141819"
                    }
                }
            },
            {
                "id": 142,
                "name": "Closed - won",
                "sort": 10000,
                "is_editable": false,
                "pipeline_id": 6950551,
                "color": "#CCFF66",
                "type": 0,
                "account_id": 31361463,
                "_links": {
                    "self": {
                        "href": "https://devteam.kommo.com/api/v4/leads/pipelines/6950551/statuses/142"
                    }
                }
            },
            {
                "id": 143,
                "name": "Closed - lost",
                "sort": 11000,
                "is_editable": false,
                "pipeline_id": 6950551,
                "color": "#D5D8DB",
                "type": 0,
                "account_id": 31361463,
                "_links": {
                    "self": {
                        "href": "https://devteam.kommo.com/api/v4/leads/pipelines/6950551/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

The method is available for all account users.

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

Response parameters

The 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 The 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.kommo.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.

You can pass status descriptions (optional).

Limitations

The method is available for administrator users only.

The following restrictions apply to status descriptions:

  • Only 3 status descriptions can be created for different user levels
  • You can not pass the same level in different descriptions
  • Maximum description length 1000 characters
  • You can send emojis in descriptions
  • You can pass the following levels in descriptions: newbie, candidate and master

Authorization type

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

Request header

Content-Type: application/json

Request body example

[
    {
        "name": "New status",
        "sort": 100,
        "color": "#fffeb2",
        "descriptions": [
            {
                "level": "newbie",
                "description": "Status for new"
            },
            {
                "level": "candidate",
                "description": "Status for candidate"
            },
            {
                "level":"master",
                "description": "Status for master"
            }
        ]
    },
    {
        "name": "New status 2",
        "sort": 200,
        "color": "#fffeb2"
    }
]

Body 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 The field will be returned unchanged in the response and will not be saved. Is not a mandatory parameter

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 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 added status models. The parameters are similar to the statuses list request parameters.

Response example

{
    "_total_items": 2,
    "_embedded": {
        "statuses": [
            {
                "id": 58223475,
                "name": "New status",
                "sort": 60,
                "is_editable": true,
                "pipeline_id": 6950551,
                "color": "#fffeb2",
                "type": 0,
                "account_id": 31361463,
                "request_id": "0",
                "_links": {
                    "self": {
                        "href": "https://devteam.kommo.com/api/v4/leads/pipelines/6950551/statuses/58223475"
                    }
                }
            },
            {
                "id": 58223479,
                "name": "New status 2",
                "sort": 70,
                "is_editable": true,
                "pipeline_id": 6950551,
                "color": "#fffeb2",
                "type": 0,
                "account_id": 31361463,
                "request_id": "1",
                "_links": {
                    "self": {
                        "href": "https://devteam.kommo.com/api/v4/leads/pipelines/6950551/statuses/58223479"
                    }
                }
            }
        ]
    }
}

Pipeline status edit

Method

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

Description

This method allows to edit a pipeline status.

You can pass status descriptions (optional).

Limitations

The method is available for administrator users only.

The following restrictions apply to status descriptions:

  • Only 3 status descriptions can be created for different user levels
  • You can not pass the same level in different descriptions
  • Maximum description length 1000 characters
  • You can send emojis in descriptions
  • You can pass the following levels in descriptions: newbie, candidate and master

Authorization type

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

Request header

Content-Type: application/json

Request body example

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

Body 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

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 The user is not authorized
400 Invalid data are given. Details are available in the request-response

Response parameters

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

Response example

{
    "id": 58221923,
    "name": "New status name",
    "sort": 20,
    "is_editable": true,
    "pipeline_id": 6950551,
    "color": "#c1e0ff",
    "type": 0,
    "account_id": 31361463,
    "request_id": "0",
    "_links": {
        "self": {
            "href": "https://devteam.kommo.com/api/v4/leads/pipelines/6950551/statuses/58221923"
        }
    }
}

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

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

Authorization type

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

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 The user is not authorized
400 Invalid data are given. Details are available in the request-response

Response parameters

The 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