Lists

In this section, we will describe all available API methods for working with Lists

Table of Contents

Common information

  • It is possible to have no more than 10 lists on the account
  • There are 3 types of lists – regular, invoices, products
  • There can be only 1 list of each invoice and products type
  • List elements can be linked to the following entities: leads, customers, transactions

Available lists

Method

GET /api/v4/catalogs

Description

This method allows to get available lists on the account.

Limitations

Method is available for users with access to lists.

GET parameters

Parameter Data type Description
page int Sample page
limit int The number of the entities returned in the response of one request (limit – 250)

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

Parameter Data type Description
id int List ID
name string List name
created_by int The ID of the user who created the list
updated_by int The ID of the user who edited the list last
created_at int List creation date in the format of Unix Timestamp
updated_at int List edit date in the format of Unix Timestamp
sort int List sorting
type string List type
can_add_elements bool Defines whether list elements can be added via the interface (The parameter is applied for invoices list only)
can_show_in_cards bool Defines whether it is possible to add the list tab into the lead/customer card (The parameter is applied for invoices list only)
can_link_multiple bool Defines whether one element of the current list can be linked to several leads/customers
can_be_deleted bool Defines whether a list can be deleted via the interface
sdk_widget_code int Code of the widget that controls a list and can display its own element edit window (The parameter is applied for invoices list only)
account_id int Account ID where the list is located in

Response example


{
    "_page": 1,
    "_links": {
        "self": {
            "href": "https://example.kommo.com/api/v4/catalogs?page=1&limit=50"
        },
        "next": {
            "href": "https://example.kommo.com/api/v4/catalogs?page=2&limit=50"
        }
    },
    "_embedded": {
        "catalogs": [
            {
                "id": 4589,
                "name": "Regular list",
                "created_by": 504141,
                "updated_by": 504141,
                "created_at": 1590742040,
                "updated_at": 1590742040,
                "sort": 10,
                "type": "regular",
                "can_add_elements": true,
                "can_show_in_cards": false,
                "can_link_multiple": true,
                "can_be_deleted": true,
                "sdk_widget_code": null,
                "account_id": 28805383,
                "_links": {
                    "self": {
                        "href": "https://example.kommo.com/api/v4/catalogs/4589"
                    }
                }
            },
            {
                "id": 4521,
                "name": "Products",
                "created_by": 504141,
                "updated_by": 504141,
                "created_at": 1589390310,
                "updated_at": 1590742040,
                "sort": 20,
                "type": "products",
                "can_add_elements": true,
                "can_show_in_cards": false,
                "can_link_multiple": true,
                "can_be_deleted": false,
                "sdk_widget_code": null,
                "account_id": 28805383,
                "_links": {
                    "self": {
                        "href": "https://example.kommo.com/api/v4/catalogs/4521"
                    }
                }
            },
            {
                "id": 4517,
                "name": "Invoices",
                "created_by": 504141,
                "updated_by": 504141,
                "created_at": 1589379462,
                "updated_at": 1590742040,
                "sort": 30,
                "type": "invoices",
                "can_add_elements": false,
                "can_show_in_cards": false,
                "can_link_multiple": true,
                "can_be_deleted": true,
                "sdk_widget_code": null,
                "account_id": 28805383,
                "_links": {
                    "self": {
                        "href": "https://example.kommo.com/api/v4/catalogs/4517"
                    }
                }
            }
        ]
    }
}

Getting a list by its ID

Method

GET /api/v4/catalogs/{id}

Description

This method allows to get a particular list of data by its ID.

Limitations

The method is available for users with access to lists.

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

Parameter Data type Description
id int List ID
name string List name
created_by int ID of the user who created the list
updated_by int The ID of the user who edited the list last
created_at int List creation date in the format of Unix Timestamp
updated_at int List edit date in the format of Unix Timestamp
sort int List sorting
type string List type
can_add_elements bool Defines whether list elements can be added via the interface (The parameter is applied for invoices list only)
can_show_in_cards bool Defines whether it is possible to add the list tab into the lead/customer card (The parameter is applied for invoices list only)
can_link_multiple bool Defines whether one element of the current list can be linked to several leads/customers
can_be_deleted bool Defines whether a list can be deleted via the interface
sdk_widget_code int Code of the widget that controls a list and can display its own element edit window (The parameter is applied for invoices list only)
account_id int Account ID where the list is located in

Response example


{
    "id": 4589,
    "name": "Regular list",
    "created_by": 504141,
    "updated_by": 504141,
    "created_at": 1590742040,
    "updated_at": 1590742040,
    "sort": 10,
    "type": "regular",
    "can_add_elements": true,
    "can_show_in_cards": false,
    "can_link_multiple": true,
    "can_be_deleted": true,
    "sdk_widget_code": null,
    "account_id": 28805383,
    "_links": {
        "self": {
            "href": "https://example.kommo.com/api/v4/catalogs/4589"
        }
    }
}

Adding lists

Method

POST /api/v4/catalogs

Description

This method allows to add multiple lists to the account.

Limitations

The method is available for users with access to lists.

Request header

Content-Type: application/json

Request parameters

Parameter Data type Description
name string List name. Is a mandatory parameter
type string List type. Is not a mandatory parameter, по умолчанию – regular
sort int List sorting. Is not a mandatory parameter
can_add_elements bool Defines whether list elements can be added via the interface. Is not a mandatory parameter
can_link_multiple bool Defines whether one element of the current list can be linked to several leads/customers. Is not a mandatory parameter
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": "Test list",
        "can_add_elements": true,
        "can_link_multiple": false,
        "request_id": "123"
    }
]

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 Lists added 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 collection of created lists. The parameters are similar to the list data request parameters.

Response example


{
    "_links": {
        "self": {
            "href": "https://example.kommo.com/api/v4/catalogs"
        }
    },
    "_embedded": {
        "catalogs": [
            {
                "id": 5785,
                "name": "Test list",
                "created_by": 3944275,
                "updated_by": 3944275,
                "created_at": 1589397957,
                "updated_at": 1589397957,
                "sort": 10,
                "type": "regular",
                "can_add_elements": true,
                "can_show_in_cards": false,
                "can_link_multiple": false,
                "can_be_deleted": true,
                "account_id": 123123,
                "request_id": "123",
                "_links": {
                    "self": {
                        "href": "https://example.kommo.com/api/v4/catalogs/5785"
                    }
                }
            }
        ]
    }
}

Editing lists

Method

PATCH /api/v4/catalogs

Description

This method allows editing multiple lists.
To edit a singular list, you can add the list ID into the method URL (/api/v4/catalogs/{id}).
When editing multiple lists, an array of list objects is passed. In the case of a singular list, the list model is passed.

Limitations

The method is available for users with access to lists.

Request header

Content-Type: application/json

Request parameters

Parameter Data type Description
name string List name. Is a mandatory parameter
can_add_elements bool Defines whether list elements can be added via the interface. Is not a mandatory parameter
can_link_multiple bool Defines whether one element of the current list can be linked to several leads/customers. Is not a mandatory parameter
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

In the following example, we will edit a list using the /api/v4/catalogs/5787 method.


{
    "name": "New list name",
    "can_add_elements": true,
    "can_link_multiple": false
}

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 Lists edited successfully
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 edited lists or a list model. The parameters are similar to the list data request parameters.

Response example


{
    "id": 5787,
    "name": "New list name",
    "created_by": 3944275,
    "updated_by": 3944275,
    "created_at": 1589399557,
    "updated_at": 1589399886,
    "sort": 30,
    "type": "regular",
    "can_add_elements": true,
    "can_show_in_cards": false,
    "can_link_multiple": false,
    "can_be_deleted": true,
    "account_id": 123123,
    "request_id": "5787",
    "_links": {
        "self": {
            "href": "https://example.kommo.com/api/v4/catalogs/5787"
        }
    }
}

Available list elements

Method

GET /api/v4/catalogs/{catalog_id}/elements

Description

This method allows to get available list elements on the account.

Limitations

The method is available for users with access to lists.

GET parameters

Parameter Data type Description
page int Sample page
limit int The number of the entities returned in the response to one request (limit – 250)
query string|int Search query (will perform a search by custom fields values)
filter object Filter
filter[id] int|array Filter by element ID. Either a single ID or an array of IDs can be passed

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 list element models. The properties of the model are listed below.

Parameter Data type Description
id int List element ID
catalog_id int List ID
name string Element name
created_by int The ID of the user who created the element
updated_by int The ID of the user who edited the element last
created_at int Element creation date in the format of Unix Timestamp
updated_at int Element edit date in the format of Unix Timestamp
is_deleted bool Defines whether an element is deleted
custom_fields_values array|null An array of the current element custom fields’ values
account_id int Account ID where the element is located in

Response example


{
    "_page": 1,
    "_links": {
        "self": {
            "href": "https://example.kommo.com/api/v4/catalogs/4521/elements?page=1&limit=50"
        },
        "next": {
            "href": "https://example.kommo.com/api/v4/catalogs/4521/elements?page=2&limit=50"
        }
    },
    "_embedded": {
        "elements": [
            {
                "id": 525439,
                "name": "Element",
                "created_by": 504141,
                "updated_by": 504141,
                "created_at": 1589390333,
                "updated_at": 1590683336,
                "is_deleted": null,
                "custom_fields_values": [
                    {
                        "field_id": 271207,
                        "field_name": "SKU",
                        "field_code": "SKU",
                        "field_type": "text",
                        "values": [
                            {
                                "value": "dsg"
                            }
                        ]
                    },
                    {
                        "field_id": 271209,
                        "field_name": "Description",
                        "field_code": "DESCRIPTION",
                        "field_type": "textarea",
                        "values": [
                            {
                                "value": "Description"
                            }
                        ]
                    },
                    {
                        "field_id": 271211,
                        "field_name": "Price",
                        "field_code": "PRICE",
                        "field_type": "numeric",
                        "values": [
                            {
                                "value": "12"
                            }
                        ]
                    },
                    {
                        "field_id": 271213,
                        "field_name": "Group",
                        "field_code": "GROUP",
                        "field_type": "category",
                        "values": [
                            {
                                "value": "Devices",
                                "enum_id": 10663
                            }
                        ]
                    }
                ],
                "catalog_id": 4521,
                "account_id": 28805383,
                "_links": {
                    "self": {
                        "href": "https://example.kommo.com/api/v4/catalogs/4521/elements/525439"
                    }
                }
            }
        ]
    }
}

Getting a list element by its ID

Method

GET /api/v4/catalogs/{catalog_id}/elements/{id}

Description

This method allows to get a list element data by its ID.

Limitations

The method is available for users with access to lists.

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

Parameter Data type Description
id int List element ID
catalog_id int List ID
name string Element name
created_by int The ID of the user who created the element
updated_by int The ID of the user who edited the element last
created_at int Element creation date in the format of Unix Timestamp
updated_at int Element edit date in the format of Unix Timestamp
is_deleted bool Defines whether an element is deleted
custom_fields_values array|null An array of the current element custom fields’ values
account_id int Account ID where the element is located in

Response example


{
    "id": 525439,
    "name": "Element",
    "created_by": 504141,
    "updated_by": 504141,
    "created_at": 1589390333,
    "updated_at": 1590683336,
    "is_deleted": null,
    "custom_fields_values": [
        {
            "field_id": 271207,
            "field_name": "SKU",
            "field_code": "SKU",
            "field_type": "text",
            "values": [
                {
                    "value": "dsg"
                }
            ]
        },
        {
            "field_id": 271209,
            "field_name": "Description",
            "field_code": "DESCRIPTION",
            "field_type": "textarea",
            "values": [
                {
                    "value": "Mobile device"
                }
            ]
        },
        {
            "field_id": 271211,
            "field_name": "Price",
            "field_code": "PRICE",
            "field_type": "numeric",
            "values": [
                {
                    "value": "12"
                }
            ]
        },
        {
            "field_id": 271213,
            "field_name": "Group",
            "field_code": "GROUP",
            "field_type": "category",
            "values": [
                {
                    "value": "Devices",
                    "enum_id": 10663
                }
            ]
        }
    ],
    "catalog_id": 4521,
    "account_id": 28805383,
    "_links": {
        "self": {
            "href": "https://example.kommo.com/api/v4/catalogs/4521/elements/525439"
        }
    }
}

Adding list elements

Method

POST /api/v4/catalogs/{catalog_id}/elements

Description

This method allows to add multiple list elements into the account.

Limitations

The method is available for users with access to lists.

Request header

Content-Type: application/json

Request parameters

Parameter Data type Description
name string List element name. Is a mandatory parameter
custom_fields_values array An array of the current element custom fields’ values. Examples of custom fields structure
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 list element",
        "custom_fields_values": [
            {
                "field_id": 14263,
                "values": [
                    {
                        "value": 1000
                    }
                ]
            }
        ]
    }
]

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 Elements added 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 collection of created elements. The parameters are similar to the list element data request parameters.

Response example


{
    "_links": {
        "self": {
            "href": "https://example.kommo.com/api/v4/catalogs/1209/elements"
        }
    },
    "_embedded": {
        "elements": [
            {
                "id": 986757,
                "name": "New list element",
                "created_by": 3944275,
                "updated_by": 3944275,
                "created_at": 1589294541,
                "updated_at": 1589294541,
                "is_deleted": false,
                "custom_fields_values": [
                    {
                        "field_id": 14687,
                        "field_name": "Price",
                        "field_code": "PRICE",
                        "field_type": "numeric",
                        "values": [
                            {
                                "value": "1000"
                            }
                        ]
                    }
                ],
                "catalog_id": 1209,
                "account_id": 123123,
                "request_id": 0,
                "_links": {
                    "self": {
                        "href": "https://example.kommo.com/api/v4/catalogs/1209/elements/986757"
                    }
                }
            }
        ]
    }
}

Editing list elements

Method

PATCH /api/v4/catalogs/{catalog_id}/elements

Description

This method allows editing multiple list elements.
To edit a singular list element, you can add the element ID into the method URL (/api/v4/catalogs/{catalog_id}/elements/{id}).
When editing multiple elements, an array of element objects is passed. In the case of a singular element, the element model is passed.

Limitations

The method is available for users with access to lists.

Request header

Content-Type: application/json

Request parameters

Parameter Data type Description
name string List element name. Is a mandatory parameter
custom_fields_values array An array of the current element custom fields’ values. Examples of custom fields structure
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


[
    {
        "id": 986757,
        "name": "New element name"
    },
    {
        "id": 986753,
        "name": "New element name 2"
    }
]

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 Elements 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 collection of edited elements or an element model. The parameters are similar to the list element data request parameters.

Response example


{
    "_links": {
        "self": {
            "href": "https://example.kommo.com/api/v4/catalogs/1209/elements"
        }
    },
    "_embedded": {
        "elements": [
            {
                "id": 986757,
                "name": "New element name",
                "created_by": 3944275,
                "updated_by": 3944275,
                "created_at": 1589294541,
                "updated_at": 1589295769,
                "is_deleted": false,
                "custom_fields_values": [ ],
                "catalog_id": 1209,
                "account_id": 123123,
                "request_id": 986757,
                "_links": {
                    "self": {
                        "href": "https://example.kommo.com/api/v4/catalogs/1209/elements/986757"
                    }
                }
            },
            {
                "id": 986753,
                "name": "New element name 2",
                "created_by": 3944275,
                "updated_by": 3944275,
                "created_at": 1589294429,
                "updated_at": 1589295769,
                "is_deleted": false,
                "custom_fields_values": [],
                "catalog_id": 1209,
                "account_id": 123123,
                "request_id": 986753,
                "_links": {
                    "self": {
                        "href": "https://example.kommo.com/api/v4/catalogs/1209/elements/986753"
                    }
                }
            }
        ]
    }
}