Customers Stages and Segments

In this section we will describe all available methods for customers Segments and Stages

Table of Contents

Common information

There are 2 Customers modes present – dynamic segmentation and recurring purchases.
In recurring purchases mode, a customer can only be located in 1 status and move between statuses based on different conditions, next purchase date, next purchase value.
In dynamic segmentation mode, a customer can be linked to several segments at once. Every segment has its entry and exit conditions as well as custom fields.
At the moment, there are no API methods for editing or creation of conditions both for statuses and segments.

  • In recurring purchases mode, no more than 30 statuses can be created including system statuses.
  • In dynamic segmentation mode, no more than 100 segments can be created.
  • Segments can have no more than 30 custom fields.

Stages list

Method

GET /api/v4/customers/statuses

Description

This method allows to get a list of customers stages 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
422 Recurring purchases mode is not enabled

Response parameters

Method returns a stage models collection. The properties of the stage model are listed below.

Parameter Data type Description
id int Stage ID
name string Stage name
sort int Status sorting
is_default bool Defines whether it is a system stage
color string Stage color. The list of available colors
type int Stage type (0 – regular stage, 1 – expected purchase, 2 – did not purchase, 3 – closed, 4 – recently purchased)
conditions array Stage change conditions
account_id int Account ID the stage is located in

Response example


{
    "_total_items": 6,
    "_links": {
        "self": {
            "href": "https://example.kommo.com/api/v4/customers/statuses"
        }
    },
    "_embedded": {
        "statuses": [
            {
                "id": 4740010,
                "name": "Recently purchased",
                "sort": 0,
                "is_default": true,
                "conditions": [],
                "color": "#ccff66",
                "type": 4,
                "account_id": 28805383,
                "_links": {
                    "self": {
                        "href": "https://example.kommo.com/api/v4/customers/statuses/4740010"
                    }
                }
            },
            {
                "id": 4740013,
                "name": "Stage 1",
                "sort": 1,
                "is_default": false,
                "conditions": [],
                "color": "#fd5598",
                "type": 0,
                "account_id": 28805383,
                "_links": {
                    "self": {
                        "href": "https://example.kommo.com/api/v4/customers/statuses/4740013"
                    }
                }
            },
            {
                "id": 4740025,
                "name": "Expected purchase",
                "sort": 2,
                "is_default": true,
                "conditions": [
                    [
                        {
                            "type": "before_purchase",
                            "match": {
                                "value": 0
                            },
                            "conditions": [
                                {
                                    "value": 0
                                }
                            ]
                        }
                    ]
                ],
                "color": "#99ccff",
                "type": 3,
                "account_id": 28805383,
                "_links": {
                    "self": {
                        "href": "https://example.kommo.com/api/v4/customers/statuses/4740025"
                    }
                }
            },
            {
                "id": 4740028,
                "name": "Did not purchase",
                "sort": 4,
                "is_default": true,
                "conditions": [],
                "color": "#fd5598",
                "type": 2,
                "account_id": 28805383,
                "_links": {
                    "self": {
                        "href": "https://example.kommo.com/api/v4/customers/statuses/4740028"
                    }
                }
            },
            {
                "id": 4740031,
                "name": "Closed",
                "sort": 5,
                "is_default": true,
                "conditions": [
                    [
                        {
                            "type": "after_today",
                            "match": {
                                "value": 60
                            },
                            "conditions": [
                                {
                                    "value": 60
                                }
                            ]
                        }
                    ]
                ],
                "color": "#d5d8db",
                "type": 3,
                "account_id": 28805383,
                "_links": {
                    "self": {
                        "href": "https://example.kommo.com/api/v4/customers/statuses/4740031"
                    }
                }
            }
        ]
    }
}

Getting a customers stage by its ID

Method

GET /api/v4/customers/statuses/{id}

Description

This method allows to get a customers stage 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
422 Recurring purchases mode is not enabled

Response parameters

Method returns a stage model. The properties of the stage model are listed below.

Parameter Data type Description
id int Stage ID
name string Stage name
sort int Stage sorting
is_default bool Defines whether it is a system stage
color string Stage color. The list of available colors
type int Stage type (0 – regular stage, 1 – expected purchase, 2 – did not purchase, 3 – closed, 4 – recently purchased)
conditions array Stage change conditions
account_id int Account ID the stage is located in

Response example


{
    "id": 4051135,
    "name": "Example stage",
    "sort": 2,
    "is_default": false,
    "conditions": [
        [
            {
                "type": "tag",
                "options": {
                    "name": "Tags"
                },
                "logic_operator": "or",
                "conditions": [
                    {
                        "id": 174727,
                        "name": "Condition"
                    }
                ],
                "match": {
                    "value": [
                        174727
                    ],
                    "logic": "or"
                },
                "tmpl": "tag_customers"
            }
        ],
        []
    ],
    "color": "#ccc8f9",
    "type": 0,
    "account_id": 321321,
    "_links": {
        "self": {
            "href": "https://example.kommo.com/api/v4/customers/statuses/4051135"
        }
    }
}

Adding stages into the customers pipeline

Method

POST /api/v4/customers/statuses

Description

This method allows to add multiple or singular customers stages intp the account.

Limitations

Method is available for administrator users only.

Request header

Content-Type: application/json

Request parameters

Parameter Data type Description
name string Stage name. Is a mandatory parameter
sort int Stage sorting. Is a mandatory parameter
color string Stage 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 field

An example of the request


[
    {
        "name": "New stage",
        "sort": 100,
        "color": "#fffeb2"
    },
    {
        "name": "New stage 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 Stages 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 stages.

Response example


{
    "_total_items": 2,
    "_links": {
        "self": {
            "href": "https://example.kommo.com/api/v4/customers/statuses"
        }
    },
    "_embedded": {
        "statuses": [
            {
                "id": 5649280,
                "request_id": "0",
                "_links": {
                    "self": {
                        "href": "https://example.kommo.com/api/v4/customers/statuses/5649280"
                    }
                }
            },
            {
                "id": 5649283,
                "request_id": "1",
                "_links": {
                    "self": {
                        "href": "https://example.kommo.com/api/v4/customers/statuses/5649283"
                    }
                }
            }
        ]
    }
}

Updating a customers stage

Method

PATCH /api/v4/customers/statuses/{id}

Description

This method allows to update a customers stage.

Limitations

Method is available for administrator users only.

Request header

Content-Type: application/json

Request parameters

To update a stage, at least one parameter should be passed

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

An example of the request


{
    "name": "New stage 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 Stage updated 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 updated stage. The parameters are similar to the stages list request parameters.

Response example


{
    "id": 5649280,
    "name": "New stage name",
    "sort": 5,
    "is_default": false,
    "conditions": [],
    "color": "#c1e0ff",
    "type": 0,
    "account_id": 28805383,
    "request_id": "0",
    "_links": {
        "self": {
            "href": "https://example.kommo.com/api/v4/customers/statuses/5649280"
        }
    }
}

Deleting a customers stage

Method

DELETE /api/v4/customers/statuses/{id}

Description

This method allows to delete a customers stage from the account.

Limitations

  • Method is available for administrator users only
  • System stages can’t be deleted
  • Customers located in the deleted stage will be moved to different stages based off set conditions

Request header

Content-Type: application/json

HTTP response codes.

Response code Case
204 The stage 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

Segments list

Method

GET /api/v4/customers/segments

Description

This method allows to get a list of customers segments 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
422 Dynamic segmentation mode is not enabled

Response parameters

Method returns a segment models collection. The properties of the segment model are listed below.

Parameter Data type Description
id int Segment ID
created_at int Segment creation date in the format of Unix Timestamp
updated_at int Segment update date in the format of Unix Timestamp
name string Segment name
customers_count int The number of customers in the segment
color string Segment color. The list of available colors
custom_fields_values array|null An array of the segment custom fields’ values
available_products_price_types array|null Availables prices for the segment. Is an array of the “price” type catalogs’ IDs
account_id int Account ID the segment is located in

Response example


{
    "_total_items": 2,
    "_page": 1,
    "_page_count": 1,
    "_links": {
        "self": {
            "href": "https://example.kommo.com/api/v4/customers/segments?page=1&limit=50"
        }
    },
    "_embedded": {
        "segments": [
            {
                "id": 51,
                "created_at": 1589615328,
                "updated_at": 1591089010,
                "account_id": 28805383,
                "name": "Segment 1",
                "color": "6610f2",
                "available_products_price_types": [
                    288891
                ],
                "customers_count": 0,
                "custom_fields_values": [
                    {
                        "values": [
                            {
                                "value": true
                            }
                        ],
                        "field_id": 269471,
                        "field_name": "Checkbox type field",
                        "field_code": "MYSUPERCHECKBOX",
                        "field_type": "checkbox"
                    },
                    {
                        "values": [
                            {
                                "value": "Value 1",
                                "enum_id": 381857
                            }
                        ],
                        "field_id": 269473,
                        "field_name": "Select type field",
                        "field_code": null,
                        "field_type": "select"
                    },
                    {
                        "values": [
                            {
                                "value": "12424"
                            }
                        ],
                        "field_id": 272427,
                        "field_name": "Text type field",
                        "field_code": null,
                        "field_type": "text"
                    }
                ],
                "_links": {
                    "self": {
                        "href": "https://example.kommo.com/api/v4/customers/segments/51"
                    }
                }
            },
            {
                "id": 21,
                "created_at": 1587376544,
                "updated_at": 1587376544,
                "account_id": 28805383,
                "name": "Segment 2",
                "color": "4a001f",
                "available_products_price_types": [
                    271211
                ],
                "customers_count": 0,
                "custom_fields_values": [],
                "_links": {
                    "self": {
                        "href": "https://example.kommo.com/api/v4/customers/segments/21"
                    }
                }
            }
        ]
    }
}

Getting a customers segment by its ID

Method

GET /api/v4/customers/segments/{id}

Description

This method allows to get a customers segment 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
422 Dynamic segmentation mode is not enabled

Response parameters

Method returns a segment model. The properties of the segment model are listed below.

Parameter Data type Description
id int Segment ID
created_at int Segment creation date in the format of Unix Timestamp
updated_at int Segment update date in the format of Unix Timestamp
name string Segment name
customers_count int The number of customers in the segment
color string Segment color. The list of available colors
custom_fields_values array|null An array of the segment custom fields’ values
available_products_price_types array|null Availables prices for the segment. Is an array of the “price” type catalogs’ IDs
account_id int Account ID the segment is located in

Response example


{
    "id": 51,
    "created_at": 1589615328,
    "updated_at": 1591089010,
    "account_id": 28805383,
    "name": "New segment",
    "color": "6610f2",
    "available_products_price_types": [
        288891
    ],
    "customers_count": 0,
    "custom_fields_values": [
        {
            "values": [
                {
                    "value": true
                }
            ],
            "field_id": 269471,
            "field_name": "Checkbox type field",
            "field_code": "MYSUPERCHECKBOX",
            "field_type": "checkbox"
        },
        {
            "values": [
                {
                    "value": "Value 1",
                    "enum_id": 381857
                }
            ],
            "field_id": 269473,
            "field_name": "Select type field",
            "field_code": null,
            "field_type": "select"
        },
        {
            "values": [
                {
                    "value": "12424"
                }
            ],
            "field_id": 272427,
            "field_name": "Text type field",
            "field_code": null,
            "field_type": "text"
        }
    ],
    "_links": {
        "self": {
            "href": "https://shard151.kommo.com/api/v4/customers/segments/51"
        }
    }
}

Adding a customers segment

Method

POST /api/v4/customers/segments

Description

This method allows to add a customers segment into the account.

Limitations

Method is available for administrator users only.

Request header

Content-Type: application/json

Request parameters

To add a segment, at least a mandatory “name” parameter should be passed

Parameter Data type Description
name string Segment name
available_products_price_types array Availables prices for the segment. Is an array of the “price” type catalogs’ IDs
color string Segment color. The list of available colors
custom_fields_values array|null An array of the segment custom fields’ values. Examples of custom fields structure

An example of the request


{
    "name": "Example segment",
    "color": "ae003f",
    "custom_fields_values": [
        {
            "field_id": 245035,
            "field_name": "Segment description",
            "values": [
                {
                    "value": "This is an example segment"
                }
            ]
        },
        {
            "field_id": 245351,
            "values": [
                {
                    "enum_id": 387477
                }
            ]
        }
    ]
}

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 Segment added 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 added segment. The parameters are similar to the segments list request parameters.

Response example


{
    "id": 17,
    "created_at": 1589462149,
    "updated_at": 1589462149,
    "account_id": 123123,
    "name": "Example segment",
    "color": "ae003f",
    "available_products_price_types": [],
    "customers_count": 0,
    "custom_fields_values": [
        {
            "values": [
                {
                    "value": "This is an example segment"
                }
            ],
            "field_id": 245035,
            "field_name": "Segment description",
            "field_code": null,
            "field_type": "text"
        },
        {
            "values": [
                {
                    "value": "multiselect field value",
                    "enum_id": 387477
                }
            ],
            "field_id": 245351,
            "field_name": "multiselect field",
            "field_code": null,
            "field_type": "multiselect"
        }
    ],
    "_links": {
        "self": {
            "href": "https://example.kommo.com/api/v4/customers/segments/17"
        }
    }
}

Updating a customers segment

Method

PATCH /api/v4/customers/segments/{id}

Description

This method allows to update a customers segment.

Limitations

Method is available for administrator users only.

Request header

Content-Type: application/json

Request parameters

To update a segment, at least one parameter should be passed

Parameter Data type Description
name string Segment name
available_products_price_types array Availables prices for the segment. Is an array of the “price” type catalogs’ IDs
color string Segment color. The list of available colors
custom_fields_values array|null An array of the segment custom fields’ values. Examples of custom fields structure
request_id string Field that will be returned unchanged in the response and will not be saved. Is not a mandatory field

An example of the request


{
    "name": "New segment name",
    "color": "ae003f",
    "custom_fields_values": [
        {
            "field_id": 245035,
            "field_name": "Segment description",
            "values": [
                {
                    "value": "New segment description"
                }
            ]
        }
    ]
}

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 Segment updated 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 updated segment. The parameters are similar to the segments list request parameters.

Response example


{
    "id": 17,
    "created_at": 1589462149,
    "updated_at": 1589463844,
    "account_id": 123123,
    "name": "New segment name",
    "color": "ae003f",
    "available_products_price_types": [],
    "customers_count": 0,
    "custom_fields_values": [
        {
            "values": [
                {
                    "value": "New segment description"
                }
            ],
            "field_id": 245035,
            "field_name": "Segment description",
            "field_code": null,
            "field_type": "text"
        },
    ],
    "_links": {
        "self": {
            "href": "https://example.kommo.com/api/v4/customers/segments/17"
        }
    }
}

Deleting a customers segment

Method

DELETE /api/v4/customers/segments/{id}

Description

This method allows to delete a customers segment from the account.

Limitations

Method is available for administrator users only.

Request header

Content-Type: application/json

HTTP response codes.

Response code Case
204 The segment 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 stage colors

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

Available segment colors

Color Color code
10599d
2176ff
006acc
07a0c3
247ba0
177e89
046e8f
598381
0c7c59
495f41
00a44b
08605f
bf2600
06d6a0
e14945
79b473
ae003f
a2ad59
cd0f53
8e936d
832161
2e5339
bf126f
6f7c12
ff5376
dd1c1a
bb304e
631d76
9d2b32
4a001f
b118c8
6a0f49
6610f2
b38a58
8963ba
4b3666
932f6d
6b2d5c
6461a0
4f517d