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
- Leads pipelines list
- Getting a leads pipeline by its ID
- Adding pipelines
- Pipeline edit
- Deleting a pipeline
- Pipeline statuses list
- Getting a leads pipeline status data by its ID
- Adding statuses to the pipeline
- Pipeline status edit
- Deleting a pipeline status
- Available status colors
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.
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 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.kommo.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.kommo.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.kommo.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.kommo.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.kommo.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.kommo.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.kommo.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
The 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 | The user is not authorized |
Response parameters
The method returns 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://example.kommo.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://example.kommo.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://example.kommo.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://example.kommo.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://example.kommo.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://example.kommo.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
The 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 | The 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 | 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://example.kommo.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.kommo.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.kommo.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.kommo.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.kommo.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.kommo.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
The 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 | 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": 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.kommo.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.kommo.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.kommo.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.kommo.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.kommo.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
- 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
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.
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": 1,
"_links": {
"self": {
"href": "https://example.kommo.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.kommo.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.kommo.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.kommo.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.kommo.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.kommo.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.kommo.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
The 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 | 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.
Limitations
The 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 | The field 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 | 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": 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.kommo.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.kommo.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
The 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 | 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": 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.kommo.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
- The 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 | 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 |