Users and Roles

In this section we will describe all available methods for working with Users and their Roles via API

Table of Contents

User list

Method

GET /api/v4/users

Description

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

Limitations

Method is available for administrator users only.

GET parameters

Parameter Data type Description
with string This parameter takes a string which may consist of several values separated by commas. This method supports the following parameters.
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
403 Insufficient rights to call this method
401 User is not authorized

Response parameters

Method returns a collection of user models. The properties of the model are listed below.
Rights objects have a common structure. Depending on the entity type these objects contain available actions as keys and the rights for the action as a value. For example, rights[leads][view]=A.

Parameter Data type Description
id int User ID
name string User fullname
email string User email
lang string User language. One of the following: ru, en, es, pt
rights object User rights
rights[leads] object Leads access rights object
rights[contacts] object Contacts access rights object
rights[companies] object Companies access rights object
rights[tasks] object Tasks access rights object
rights[mail_access] bool Defines whether Mail functionality is allowed for the user
rights[catalog_access] bool Defines whether Lists functionality is allowed for the user
rights[is_admin] bool Defines whether the user has administrator rights
rights[is_free] bool Defines whether it is a free user
rights[is_active] bool Defines whether the user is active
rights[group_id] int|null ID of the user’s group
rights[role_id] int|null ID of the user’s role
rights[status_rights] array An array of the objects that define statuses rights
rights[status_rights][0] object An object of status rights
rights[status_rights][0][entity_type] string Entity type. Only lead entity is supported at the moment
rights[status_rights][0][pipeline_id] int ID of the pipeline the status is located in
rights[status_rights][0][status_id] int Status ID
rights[status_rights][0][rights] object Rights object

Response example

        
{
    "_total_items": 2,
    "_page": 1,
    "_page_count": 1,
    "_links": {
        "self": {
            "href": "https://example.kommo.com/api/v4/users/?with=role%2Cgroup"
        }
    },
    "_embedded": {
        "users": [
            {
                "id": 123123,
                "name": "Example user",
                "email": "user@example.com",
                "lang": "en",
                "rights": {
                    "leads": {
                        "view": "A",
                        "edit": "A",
                        "add": "A",
                        "delete": "A",
                        "export": "A"
                    },
                    "contacts": {
                        "view": "A",
                        "edit": "A",
                        "add": "A",
                        "delete": "A",
                        "export": "A"
                    },
                    "companies": {
                        "view": "A",
                        "edit": "A",
                        "add": "A",
                        "delete": "A",
                        "export": "A"
                    },
                    "tasks": {
                        "edit": "A",
                        "delete": "A"
                    },
                    "mail_access": false,
                    "catalog_access": false,
                    "status_rights": [
                        {
                            "entity_type": "leads",
                            "pipeline_id": 2194576,
                            "status_id": 30846277,
                            "rights": {
                                "view": "A",
                                "edit": "A",
                                "delete": "A"
                            }
                        },
                        {
                            "entity_type": "leads",
                            "pipeline_id": 2212201,
                            "status_id": 30965377,
                            "rights": {
                                "view": "A",
                                "edit": "A",
                                "delete": "A"
                            }
                        }
                    ],
                    "is_admin": false,
                    "is_free": false,
                    "is_active": true,
                    "group_id": null,
                    "role_id": null
                },
                "_links": {
                    "self": {
                        "href": "https://example.kommo.com/api/v4/users/123123/"
                    }
                },
                "_embedded": {
                   "roles": [
                        {
                            "id": 3141,
                            "name": "Manager",
                            "_links": {
                                "self": {
                                    "href": "https://example.kommo.com/api/v4/roles/3141"
                                }
                            }
                        }
                    ],
                    "groups": [
                        {
                            "id": 267688,
                            "name": "Managers"
                        }
                    ]
                }
            },
            {
                "id": 321321,
                "name": "Example user 2",
                "email": "user@example.com",
                "lang": "ru",
                "rights": {
                    "leads": {
                        "view": "A",
                        "edit": "A",
                        "add": "G",
                        "delete": "D",
                        "export": "M"
                    },
                    "contacts": {
                        "view": "A",
                        "edit": "A",
                        "add": "G",
                        "delete": "M",
                        "export": "D"
                    },
                    "companies": {
                        "view": "A",
                        "edit": "G",
                        "add": "G",
                        "delete": "D",
                        "export": "D"
                    },
                    "tasks": {
                        "edit": "A",
                        "delete": "A"
                    },
                    "mail_access": true,
                    "catalog_access": true,
                    "status_rights": null,
                    "is_admin": true,
                    "is_free": false,
                    "is_active": true,
                    "group_id": null,
                    "role_id": null
                },
                "_links": {
                    "self": {
                        "href": "https://example.kommo.com/api/v4/users/321321"
                    }
                },
                "_embedded": {
                    "roles": [],
                    "groups": []
                }
            }
        ]
    }
}

Parameters for GET-parameters “with”

Parameter Description
role Adds the user’s role into the response
group Adds the user’s group into the response

Getting user data by its ID

Method

GET /api/v4/users/{id}

Description

This method allows to get the data of the user on the account by user’s ID.

Limitations

Method is available for administrator users only.

GET parameters

Parameter Data type Description
with string This parameter takes a string which may consist of several values separated by commas. This method supports the following parameters.

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
403 Insufficient rights to call this method
401 User is not authorized

Response parameters

Method returns a user model. The properties of the model are listed below.
Rights objects have a common structure. Depending on the entity type these objects contain available actions as keys and the rights for the action as a value. For example, rights[leads][view]=A.

Parameter Data type Description
id int User ID
name string User fullname
email string User email
lang string User language. One of the following: ru, en, es, pt
rights object User rights
rights[leads] object Leads access rights object
rights[contacts] object Contacts access rights object
rights[companies] object Companies access rights object
rights[tasks] object Tasks access rights object
rights[mail_access] bool Defines whether Mail functionality is allowed for the user
rights[catalog_access] bool Defines whether Lists functionality is allowed for the user
rights[is_admin] bool Defines whether the user has administrator rights
rights[is_free] bool Defines whether it is a free user
rights[is_active] bool Defines whether the user is active
rights[group_id] int|null ID of the user’s group
rights[role_id] int|null ID of the user’s role
rights[status_rights] array An array of the objects that define statuses rights
rights[status_rights][0] object An object of status rights
rights[status_rights][0][entity_type] string Entity type. Only lead entity is supported at the moment
rights[status_rights][0][pipeline_id] int ID of the pipeline the status is located in
rights[status_rights][0][status_id] int Status ID
rights[status_rights][0][rights] object Rights object

Response example

        
{
    "id": 185848,
    "name": "John Doe",
    "email": "test@example.com",
    "lang": "en",
    "rights": {
        "leads": {
            "view": "M",
            "edit": "M",
            "add": "D",
            "delete": "M",
            "export": "M"
        },
        "contacts": {
            "view": "M",
            "edit": "M",
            "add": "D",
            "delete": "M",
            "export": "M"
        },
        "companies": {
            "view": "M",
            "edit": "M",
            "add": "D",
            "delete": "M",
            "export": "M"
        },
        "tasks": {
            "edit": "A",
            "delete": "A"
        },
        "mail_access": false,
        "catalog_access": true,
        "status_rights": [
            {
                "entity_type": "leads",
                "pipeline_id": 3166396,
                "status_id": 142,
                "rights": {
                    "view": "D",
                    "edit": "D",
                    "delete": "D",
                    "export": "D"
                }
            },
            {
                "entity_type": "leads",
                "pipeline_id": 3166396,
                "status_id": 32311027,
                "rights": {
                    "view": "D",
                    "edit": "D",
                    "delete": "D"
                }
            },
            {
                "entity_type": "leads",
                "pipeline_id": 3104455,
                "status_id": 31881115,
                "rights": {
                    "view": "D",
                    "edit": "D",
                    "delete": "D"
                }
            }
        ],
        "is_admin": false,
        "is_free": false,
        "is_active": true,
        "group_id": null,
        "role_id": null
    },
    "_links": {
        "self": {
            "href": "https://example.kommo.com/api/v4/users/185848"
        }
    }
}

Parameters for GET-parameters “with”

Parameter Description
role Adds the user role into the response
group Adds the user group into the response

Adding users

Method

POST /api/v4/users

Description

This method allows to add multiple users to the account.

Limitations

  • Method is available for administrator users only.
  • Method allows adding up 10 users with a single request.
  • Method becomes unavaila if the number of users exceed 100.

Request header

Content-Type: application/json

Request parameters

For this method, the request parameters have the following dependencies:

  • If a valid “role_id” value is passed then the values of the following fields will be ignored: rights[leads], rights[tasks], rights[contacts], rights[companies], rights[status_rights],
    rights[mail_access], rights[catalog_access]
  • If the value “true” is passed into the “is_free” field then the values of the following fields will be ignored: rights[leads], rights[tasks], rights[contacts], rights[companies], rights[status_rights],
    rights[mail_access], rights[catalog_access], rights[role_id], rights[group_id]
  • If the value “null” is passed into the rights[group_id] field, the user will be added to the default “Sales Office” group
  • “Administrator” and “Free user” are not concidered roles, they are defined by special flags: rights[is_free]
    and rights[is_admin]
  • If the fields rights[status_rights] with the value “null” is passed, the user will receive “restricted” rights for Incoming Leads statuses
  • Fields rights[leads], rights[tasks], rights[contacts], rights[companies] should take the rights dependencies into account.
Parameter Data type Description
name string User fullname. The value should not: contain special symbols except .@-_, consist of spaces, contain links; and should be no longer than 50 symbols. The field is mandatory if the new user is created
email string User email. The field is mandatory
password string User password, should be no less than 6 symbols long and contain atleast 1 digit, capital, and lower-case letter. The field is mandatory if the new user is created
lang string User language. One of the following: ru, en, es, pt. The field is not mandatory, by default – the account language (ru, en, es, or pt)
rights object User rights. The field is not mandatory, by default all access is restricted
rights[leads] object Leads access rights object. The field is mandatory if the “role_id” isn’t passed and the “is_free” flag isn’t set
rights[contacts] object Contacts access rights object. The field is mandatory if the “role_id” isn’t passed and the “is_free” flag isn’t set
rights[companies] object Companies access rights object. The field is mandatory if the “role_id” isn’t passed and the “is_free” flag isn’t set
rights[tasks] object Tasks access rights object. The field is mandatory if the “role_id” isn’t passed and the “is_free” flag isn’t set
rights[status_rights] array|null An array of the objects that define statuses rights. The field is not mandatory, by default: null
rights[mail_access] bool Defines whether Mail functionality is allowed for the user. The field is not mandatory, by default: false
rights[catalog_access] bool Defines whether Lists functionality is allowed for the user. The field is not mandatory, by default: false
rights[is_free] bool Defines whether it is a free user. The field is not mandatory, by default: false
rights[role_id] int|null ID of the user’s role. The field is not mandatory, by default: null
rights[group_id] int|null ID of the user’s group. The field is not mandatory, by default: null
request_id string Field that will be returned unchanged in the response and will not be saved. Is not a mandatory field

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
201 Users have been successfully created
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 created users. The parameters are similar to the user list request parameters.

Response example

        
{
    "_total_items": 1,
    "_embedded": {
        "users": [
            {
                "id": 6029791,
                "name": "testUser",
                "email": "user_add-test@example.com",
                "lang": "en",
                "rights": {
                    "leads": {
                        "view": "A",
                        "edit": "A",
                        "add": "A",
                        "delete": "A",
                        "export": "D"
                    },
                    "contacts": {
                        "view": "A",
                        "edit": "A",
                        "add": "A",
                        "delete": "A",
                        "export": "D"
                    },
                    "companies": {
                        "view": "A",
                        "edit": "A",
                        "add": "A",
                        "delete": "A",
                        "export": "D"
                    },
                    "tasks": {
                        "edit": "A",
                        "delete": "A"
                    },
                    "mail_access": false,
                    "catalog_access": false,
                    "status_rights": [
                        {
                            "entity_type": "leads",
                            "pipeline_id": 2020444,
                            "status_id": 29652544,
                            "rights": {
                                "view": "D",
                                "edit": "D",
                                "delete": "D"
                            }
                        },
                        {
                            "entity_type": "leads",
                            "pipeline_id": 2275606,
                            "status_id": 31411840,
                            "rights": {
                                "view": "D",
                                "edit": "D",
                                "delete": "D"
                            }
                        }
                    ],
                    "is_admin": false,
                    "role_id": null,
                    "is_free": false,
                    "group_id": null,
                    "is_active": true
                },
                "request_id": "1",
                "_links": {
                    "self": {
                        "href": "https://test.kommo.com/api/v4/users/6029791"
                    }
                }
            }
        ]
    }
}

User roles list

Method

GET /api/v4/roles

Description

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

Limitations

Method is available for administrator users only.

GET parameters

Parameter Data type Description
with string This parameter takes a string which may consist of several values separated by commas. This method supports the following parameters.
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
403 Insufficient rights to call this method
401 User is not authorized

Response parameters

Method returns a collection of role models. The properties of the model are listed below.
Rights objects have a common structure. Depending on the entity type these objects contain available actions as keys and the rights for the action as a value. For example, rights[leads][view]=A.

Parameter Data type Description
id int Role ID
name string Role name
rights object User rights
rights[leads] object Leads access rights object
rights[contacts] object Contacts access rights object
rights[companies] object Companies access rights object
rights[tasks] object Tasks access rights object
rights[mail_access] bool Defines whether Mail functionality is allowed for the user
rights[catalog_access] bool Defines whether Lists functionality is allowed for the user
rights[is_admin] bool Defines whether the user has administrator rights
rights[is_free] bool Defines whether it is a free user
rights[is_active] bool Defines whether the user is active
rights[group_id] int|null ID of the user’s group
rights[role_id] int|null ID of the user’s role
rights[status_rights] array An array of the objects that define statuses rights
rights[status_rights][0] object An object of status rights
rights[status_rights][0][entity_type] string Entity type. Only lead entity is supported at the moment
rights[status_rights][0][pipeline_id] int ID of the pipeline the status is located in
rights[status_rights][0][status_id] int Status ID
rights[status_rights][0][rights] object Rights object
_embedded[users] array An array containing IDs of users with the current role

Response example

        
{
    "_total_items": 1,
    "_page": 1,
    "_page_count": 1,
    "_links": {
        "self": {
            "href": "https://example.kommo.com/api/v4/roles?with=users&page=1&limit=50"
        }
    },
    "_embedded": {
        "roles": [
            {
                "id": 107995,
                "name": "Supervisor",
                "rights": {
                    "leads": {
                        "view": "A",
                        "edit": "A",
                        "add": "A",
                        "delete": "A",
                        "export": "A"
                    },
                    "contacts": {
                        "view": "A",
                        "edit": "A",
                        "add": "A",
                        "delete": "A",
                        "export": "A"
                    },
                    "companies": {
                        "view": "A",
                        "edit": "A",
                        "add": "A",
                        "delete": "A",
                        "export": "A"
                    },
                    "tasks": {
                        "edit": "A",
                        "delete": "A"
                    },
                    "mail_access": false,
                    "catalog_access": false,
                    "status_rights": [
                        {
                            "entity_type": "leads",
                            "pipeline_id": 3104455,
                            "status_id": 31881115,
                            "rights": {
                                "edit": "A",
                                "view": "A",
                                "delete": "A"
                            }
                        },
                        {
                            "entity_type": "leads",
                            "pipeline_id": 3166396,
                            "status_id": 32311027,
                            "rights": {
                                "edit": "A",
                                "view": "A",
                                "delete": "A"
                            }
                        }
                    ]
                },
                "_links": {
                    "self": {
                        "href": "https://example.kommo.com/api/v4/roles/107995"
                    }
                },
                "_embedded": {
                    "users": []
                }
            }
        ]
    }
}

Parameters for GET-parameters “with”

Parameter Description
users Adds IDs of users with the current role into the response

Getting a role data by its ID

Method

GET /api/v4/roles/{id}

Description

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

Limitations

Method is available for administrator users only.

GET parameters

Parameter Data type Description
with string This parameter takes a string which may consist of several values separated by commas. This method supports the following parameters.

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
403 Insufficient rights to call this method
401 User is not authorized

Response parameters

Method returns a user role model. The properties of the model are listed below.
Rights objects have a common structure. Depending on the entity type these objects contain available actions as keys and the rights for the action as a value. For example, rights[leads][view]=A.

Parameter Data type Description
id int Role ID
name string Role name
rights object User rights
rights[leads] object Leads access rights object
rights[contacts] object Contacts access rights object
rights[companies] object Companies access rights object
rights[tasks] object Tasks access rights object
rights[mail_access] bool Defines whether Mail functionality is allowed for the user
rights[catalog_access] bool Defines whether Lists functionality is allowed for the user
rights[is_admin] bool Defines whether the user has administrator rights
rights[is_free] bool Defines whether it is a free user
rights[is_active] bool Defines whether the user is active
rights[group_id] int|null ID of the user’s group
rights[role_id] int|null ID of the user’s role
rights[status_rights] array An array of the objects that define statuses rights
rights[status_rights][0] object An object of status rights
rights[status_rights][0][entity_type] string Entity type. Only lead entity is supported at the moment
rights[status_rights][0][pipeline_id] int ID of the pipeline the status is located in
rights[status_rights][0][status_id] int Status ID
rights[status_rights][0][rights] object Rights object
_embedded[users] array An array containing IDs of users with the current role

Response example

        
{
    "id": 107995,
    "name": "Example Role",
    "rights": {
        "leads": {
            "view": "A",
            "edit": "A",
            "add": "A",
            "delete": "A",
            "export": "A"
        },
        "contacts": {
            "view": "A",
            "edit": "A",
            "add": "A",
            "delete": "A",
            "export": "A"
        },
        "companies": {
            "view": "A",
            "edit": "A",
            "add": "A",
            "delete": "A",
            "export": "A"
        },
        "tasks": {
            "edit": "A",
            "delete": "A"
        },
        "mail_access": false,
        "catalog_access": false,
        "status_rights": [
            {
                "entity_type": "leads",
                "pipeline_id": 3104455,
                "status_id": 31881115,
                "rights": {
                    "edit": "A",
                    "view": "A",
                    "delete": "A"
                }
            },
            {
                "entity_type": "leads",
                "pipeline_id": 3166396,
                "status_id": 32311027,
                "rights": {
                    "edit": "A",
                    "view": "A",
                    "delete": "A"
                }
            }
        ]
    },
    "_links": {
        "self": {
            "href": "https://example.kommo.com/api/v4/roles/107995"
        }
    }
}

Parameters for GET-parameters “with”

Parameter Description
users Adds IDs of users with the current role into the response

Adding roles

Method

POST /api/v4/roles

Description

This method allows to add multiple roles to the account.

Limitations

Method is available for administrator users only.

Request header

Content-Type: application/json

Request parameters

Parameter Data type Description
name string Role name
rights object User rights. The field is not mandatory, by default all access is restricted
rights[leads] object Leads access rights object. The field is mandatory if the “role_id” isn’t passed and the “is_free” flag isn’t set
rights[contacts] object Contacts access rights object. The field is mandatory if the “role_id” isn’t passed and the “is_free” flag isn’t set
rights[companies] object Companies access rights object. The field is mandatory if the “role_id” isn’t passed and the “is_free” flag isn’t set
rights[tasks] object Tasks access rights object. The field is mandatory if the “role_id” isn’t passed and the “is_free” flag isn’t set
rights[status_rights] array|null An array of the objects that define statuses rights. The field is not mandatory, by default: null
rights[mail_access] bool Defines whether Mail functionality is allowed for the user. The field is not mandatory, by default: false
rights[catalog_access] bool Defines whether Lists functionality is allowed for the user. The field is not mandatory, by default: false
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": "role 3",
        "rights": {
            "leads": {
                "add": "A",
                "edit": "G",
                "view": "G",
                "delete": "G",
                "export": "G"
            },
            "tasks": {
                "edit": "A",
                "delete": "A"
            },
            "contacts": {
                "add": "A",
                "edit": "A",
                "view": "A",
                "delete": "A",
                "export": "A"
            },
            "companies": {
                "add": "A",
                "edit": "A",
                "view": "A",
                "delete": "A",
                "export": "A"
            },
            "mail_access": true,
            "status_rights": [
                {
                    "entity_type": "leads",
                    "pipeline_id": 16056,
                    "status_id": 20542166,
                    "rights": {
                        "edit": "A",
                        "view": "A",
                        "delete": "A",
                        "export": "A"
                    }
                }
            ],
            "catalog_access": true
        }
    }
]

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
201 Roles have been successfully created
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 created roles. The parameters are similar to the role list request parameters.

Response example

        
{
    "_total_items": 1,
    "_embedded": {
        "roles": [
            {
                "id": 901,
                "name": "role 3",
                "rights": {
                    "leads": {
                        "add": "A",
                        "edit": "G",
                        "view": "G",
                        "delete": "G",
                        "export": "G"
                    },
                    "tasks": {
                        "edit": "A",
                        "delete": "A"
                    },
                    "contacts": {
                        "add": "A",
                        "edit": "A",
                        "view": "A",
                        "delete": "A",
                        "export": "A"
                    },
                    "companies": {
                        "add": "A",
                        "edit": "A",
                        "view": "A",
                        "delete": "A",
                        "export": "A"
                    },
                    "mail_access": true,
                    "status_rights": [
                        {
                            "entity_type": "leads",
                            "pipeline_id": 12730,
                            "status_id": 20542166,
                            "rights": {
                                "edit": "A",
                                "view": "A",
                                "delete": "A",
                                "export": "A"
                            }
                        },
                        {
                            "entity_type": "leads",
                            "pipeline_id": 16056,
                            "status_id": 20583101,
                            "rights": {
                                "edit": "D",
                                "view": "D",
                                "delete": "D"
                            }
                        }
                    ],
                    "catalog_access": true
                },
                "_links": {
                    "self": {
                        "href": "https://example.kommo.com/api/v4/roles/901/"
                    }
                }
            }
        ]
    }
}

Editing a role

Method

PATCH /api/v4/roles

Description

This method allows to edit a user role.

Limitations

Method is available for administrator users only.

Request header

Content-Type: application/json

Request parameters

No fields are mandatory, however, the request can’t be empty.
If the rights[status_rights] parameter has a value “null” or [] then current lead statuses rights for this role will be deleted.
In that case, Incoming Leads statuses rights will be set as “restricted”.

Parameter Data type Description
name string Role name
rights object User rights. The field is not mandatory, by default all access is restricted
rights[leads] object Leads access rights object. The field is mandatory if the “role_id” isn’t passed and the “is_free” flag isn’t set
rights[contacts] object Contacts access rights object. The field is mandatory if the “role_id” isn’t passed and the “is_free” flag isn’t set
rights[companies] object Companies access rights object. The field is mandatory if the “role_id” isn’t passed and the “is_free” flag isn’t set
rights[tasks] object Tasks access rights object. The field is mandatory if the “role_id” isn’t passed and the “is_free” flag isn’t set
rights[status_rights] array|null An array of the objects that define statuses rights. The field is not mandatory, by default: null
rights[mail_access] bool Defines whether Mail functionality is allowed for the user. The field is not mandatory, by default: false
rights[catalog_access] bool Defines whether Lists functionality is allowed for the user. The field is not mandatory, by default: false

An example of the request

        
{
    "name": "role 3 modified",
    "rights": {
        "contacts": {
            "add": "A",
            "edit": "D",
            "view": "D",
            "delete": "D",
            "export": "D"
        },
        "status_rights":  null
    }
}

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

Response parameters

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

Response example

        
{
    "id": 901,
    "name": "role 3 modified",
    "rights": {
        "leads": {
            "add": "A",
            "edit": "G",
            "view": "G",
            "delete": "G",
            "export": "G"
        },
        "tasks": {
            "edit": "A",
            "delete": "A"
        },
        "contacts": {
            "add": "A",
            "edit": "D",
            "view": "D",
            "delete": "D",
            "export": "D"
        },
        "companies": {
            "add": "A",
            "edit": "A",
            "view": "A",
            "delete": "A",
            "export": "A"
        },
        "mail_access": true,
        "status_rights": [
            {
                "entity_type": "leads",
                "pipeline_id": 16056,
                "status_id": 20583101,
                "rights": {
                    "edit": "D",
                    "view": "D",
                    "delete": "D"
                }
            }
        ],
        "catalog_access": true
    },
    "_links": {
        "self": {
            "href": "https://example.kommo.com/api/v4/roles/901/"
        }
    }
}

Deleting a role

Method

DELETE /api/v4/roles/{id}

Description

This method allows to delete a user role 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 role 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

General user rights designations

Value Parameter Description
A access Functionality is fully available
G group Functionality is available if the current user participates in the same user group with the responsible user
M main Functionality is available if the current user is the resposible user
D denied Functionality is unavailable

The following user rights can be customized:

  1. Create
  2. View
  3. Edit
  4. Delete
  5. Export

Access calculation priority follows this order (taking the lead entity as an example):

  1. General rights are applied first
  2. Next, special status rights are applied (limiting/extending user rights)
  3. At last, “View” rights can be extended if a user is subscribed to the lead chat

Additional features

  • “Create” rights and status rights can only have one of the following values: A, D
  • Incoming leads statuses don’t have “Export” rights
  • Customer entity rights are inherited from the lead entity rights

User rights dependencies

Rights on different actions are dependant on each other, e.g. if a user is restricted from Viewing leads, than “Edit”, “Delete”, and “Export” actions will also be restricted automatically.

In the table below we showcased the possible rights values based on their mutual dependencies.

Rights View Create Edit Delete Export
A D A G M D A G M D A G M D A G M D
Create A – + + + + + + + + + + + + + + + +
D – + + + + + + + + + + + + + + + +
View A + + – – – + + + + + + + + + + + +
G + + – – – – + + + – + + + – + + +
M + + – – – – – + + – – + + – – + +
D + + – – – – – – + – – – + – – – +
Edit A + + + – – – – – – + + + + + + + +
G + + + + – – – – – – + + + + + + +
M + + + + + – – – – – – + + + + + +
D + + + + + + – – – – – – + + + + +
Delete A + + + – – – + – – – – – – + + + +
G + + + + – – + + – – – – – + + + +
M + + + + + – + + + – – – – + + + +
D + + + + + + + + + + – – – + + + +
Export A + + + – – – + + + + + + + + – – –
G + + + + – – + + + + + + + + – – –
M + + + + + – + + + + + + + + – – –
D + + + + + + + + + + + + + + – – –