Contacts

In this section we will describe all available methods for the Contact entity.

Table of Contents

Contacts List

Method

GET /api/v4/contacts

Description

This method allows to get a list of contacts in the account.

Limitations

Method is available in correspondence to the user rights.

GET parameters

Parameter Data type Description
with string This parameter takes a string which may consist of several values separated by commas.
page int Sample page
limit int The number of the entities returned in the response of one request (limit – 250)
query string|int Search query (will perform a search by custom fields values)
filter object Filter. Filters are described in detail in Filters API
order object List elements sorting
Fields available to sort by: created_at, updated_at, id.
Values available to sort by: asc, desc.
An example: /api/v4/contacts?order[updated_at]=asc

“with” Parameters

Parameter Description
catalog_elements Adds lists elements linked to the contact into the response
leads Adds info on the leads linked to the contact into the response
customers Adds info on the customers linked to the contact into the response

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 example

Method returns the contact models collection.

{
    "_page": 1,
    "_links": {
        "self": {
            "href": "https://devteam.kommo.com/api/v4/contacts"
        }
    },
    "_embedded": {
        "contacts": [
            {
                "id": 406322,
                "name": "Sam",
                "first_name": "Sam",
                "last_name": "",
                "responsible_user_id": 8375357,
                "group_id": 0,
                "created_by": 8375357,
                "updated_by": 8375357,
                "created_at": 1686670710,
                "updated_at": 1686670710,
                "closest_task_at": null,
                "is_deleted": false,
                "is_unsorted": false,
                "custom_fields_values": [
                    {
                        "field_id": 178382,
                        "field_name": "Phone",
                        "field_code": "PHONE",
                        "field_type": "multitext",
                        "values": [
                            {
                                "value": "19651796212",
                                "enum_id": 126290,
                                "enum_code": "WORK"
                            }
                        ]
                    }
                ],
                "account_id": 31361463,
                "_links": {
                    "self": {
                        "href": "https://devteam.kommo.com/api/v4/contacts/406322"
                    }
                },
                "_embedded": {
                    "tags": [],
                    "companies": [
                        {
                            "id": 406320,
                            "_links": {
                                "self": {
                                    "href": "https://devteam.kommo.com/api/v4/companies/406320"
                                }
                            }
                        }
                    ]
                }
            },
            {
                "id": 510866,
                "name": "Adam",
                "first_name": "Adam",
                "last_name": "",
                "responsible_user_id": 8375357,
                "group_id": 0,
                "created_by": 0,
                "updated_by": 0,
                "created_at": 1668784888,
                "updated_at": 1686754687,
                "closest_task_at": null,
                "is_deleted": false,
                "is_unsorted": false,
                "custom_fields_values": null,
                "account_id": 31361463,
                "_links": {
                    "self": {
                        "href": "https://devteam.kommo.com/api/v4/contacts/510866"
                    }
                },
                "_embedded": {
                    "tags": [],
                    "companies": [
                        {
                            "id": 510864,
                            "_links": {
                                "self": {
                                    "href": "https://devteam.kommo.com/api/v4/companies/510864"
                                }
                            }
                        }
                    ]
                }
            }
        ]
    }
}

Response parameters

The properties of a contact model are listed below.

Parameter Data type Description
id int Contact ID
name string Contact fullname
first_name string Contact first name
last_name string Contact last name
responsible_user_id int Contact responsible user ID
group_id int Group ID of the contact responsible user
created_by int ID of the user who created the contact
updated_by int ID of the user who updated the contact last
created_at int Contact creation date in the format of Unix Timestamp
updated_at int Contact update date in the format of Unix Timestamp
closest_task_at int Date of the closest open task in the format of Unix Timestamp
custom_fields_values array|null An array of the current contact custom fields’ values
account_id int Account ID where the contact is located in
_embedded object Embedded entities data
_embedded[tags] array Contact tags data array
_embedded[tags][0] object Contact tag model
_embedded[tags][0][id] int Tag ID
_embedded[tags][0][name] string Tag name
_embedded[companies] array Linked company data array. This array always consists of 1 element
_embedded[companies][0] object Linked company data
_embedded[companies][0][id] int Linked company ID
_embedded[customers] array GET parameter “with” is required. Linked customers data array
_embedded[customers][0] object Linked customer data
_embedded[customers][0][id] int Linked customer ID
_embedded[leads] array GET parameter “with” is required. Linked leads data array
_embedded[leads][0] object Linked lead data
_embedded[leads][0][id] int Linked lead ID
_embedded[catalog_elements] array GET parameter “with” is required. Linked lists’ elements data array
_embedded[catalog_elements][0] object Linked list element data
_embedded[catalog_elements][0][id] int Linked element ID
_embedded[catalog_elements][0][metadata] object Meta-data of the element
_embedded[catalog_elements][0][quantity] int Linked elements quantity
_embedded[catalog_elements][0][catalog_id] int ID of the linked element’s list

Getting a contact by its ID

Method

GET /api/v4/contacts/{id}

Description

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

Limitations

Method is available in correspondence to the user rights.

GET parameters

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

“with” parameters

Parameter Description
catalog_elements Adds lists elements linked to the contact into the response
leads Adds info on the leads linked to the contact into the response
customers Adds info on the customers linked to the contact into the response

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
204 The contact with the specified ID does not exist.
401 User is not authorized

Response example

Method returns a contact model.

{
    "id": 3,
    "name": "John Doe",
    "first_name": "John",
    "last_name": "Doe",
    "responsible_user_id": 504141,
    "group_id": 0,
    "created_by": 504141,
    "updated_by": 504141,
    "created_at": 1582117331,
    "updated_at": 1590943929,
    "closest_task_at": null,
    "custom_fields_values": [
        {
            "field_id": 3,
            "field_name": "Work phone",
            "field_code": "PHONE",
            "field_type": "multitext",
            "values": [
                {
                    "value": "+14155551234",
                    "enum_id": 1,
                    "enum": "WORK"
                }
            ]
        }
    ],
    "account_id": 28805383,
    "_links": {
        "self": {
            "href": "https://example.amocrm.com/api/v4/contacts/3"
        }
    },
    "_embedded": {
        "tags": [],
        "leads": [
            {
                "id": 1,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.com/api/v4/leads/1"
                    }
                }
            },
            {
                "id": 3916883,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.com/api/v4/leads/3916883"
                    }
                }
            }
        ],
        "customers": [
            {
                "id": 134923,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.com/api/v4/customers/134923"
                    }
                }
            }
        ],
        "catalog_elements": [],
        "companies": [
            {
                "id": 1,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.com/api/v4/companies/1"
                    }
                }
            }
        ]
    }
}

Response parameters

The properties of the contact model are listed below.

Parameter Data type Description
id int Contact ID
name string Contact fullname
first_name string Contact first name
last_name string Contact last name
responsible_user_id int Contact responsible user ID
group_id int Group ID of the contact responsible user
created_by int ID of the user who created the contact
updated_by int ID of the user who updated the contact last
created_at int Contact creation date in the format of Unix Timestamp
updated_at int Contact update date in the format of Unix Timestamp
closest_task_at int Date of the closest open task in the format of Unix Timestamp
custom_fields_values array|null An array of the current contact custom fields’ values
account_id int Account ID where the contact is located in
_embedded object Embedded entities data
_embedded[tags] array Contact tags data array
_embedded[tags][0] object Contact tag model
_embedded[tags][0][id] int Tag ID
_embedded[tags][0][name] string Tag name
_embedded[companies] array Linked company data array. This array always consists of 1 element.
_embedded[companies][0] object Linked company data
_embedded[companies][0][id] int Linked company ID
_embedded[customers] array GET parameter “with” is required. Linked customers data array
_embedded[customers][0] object Linked customer data
_embedded[customers][0][id] int Linked customer ID
_embedded[leads] array GET parameter “with” is required. Linked leads data array
_embedded[leads][0] object Linked lead data
_embedded[leads][0][id] int Linked lead ID
_embedded[catalog_elements] array GET parameter “with” is required. Linked lists’ elements data array
_embedded[catalog_elements][0] object Linked list element data
_embedded[catalog_elements][0][id] int Linked element ID
_embedded[catalog_elements][0][metadata] object Meta-data of the element
_embedded[catalog_elements][0][quantity] int Linked elements quantity
_embedded[catalog_elements][0][catalog_id] int ID of the linked element’s list

Adding contacts

Method

POST /api/v4/contacts

Description

This method allows adding multiple or singular contacts into the account

Limitations

Method is available in correspondence to the user rights.

Request header

Content-Type: application/json

Request body example

[
    {
        "first_name": "Peter",
        "last_name": "Parker",
        "custom_fields_values": [
            {
                "field_id": 178382,
                "values": [
                    {
                        "value": "+19651796214"
                    }
                ]
            }
        ]
    },
    {
        "name": "Jane Doe",
        "created_by": 8375357
    }
]

Body parameters

No fields are mandatory

Parameter Data type Description
name string Contact fullname
first_name string Contact first name
last_name string Contact last name
responsible_user_id int Contact responsible user ID
created_by int ID of the user who created the contact
updated_by int ID of the user who updated the contact last
created_at int Contact creation date in the format of Unix Timestamp
updated_at int Contact update date in the format of Unix Timestamp
custom_fields_values array An array of the current contact custom fields’ values. Examples of custom fields structure
_embedded object Embedded entities data
_embedded[tags] array Contact tags data array
_embedded[tags][0] object Contact tag model
_embedded[tags][0][id] int Tag ID
_embedded[tags][0][name] string Tag name
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
200 Contacts have been created successfully
401 User is not authorized
400 Invalid data given. Details are available in the request response

Response parameters

Method returns a collection of created contacts.

Response example

{
    "_links": {
        "self": {
            "href": "https://devteam.kommo.com/api/v4/contacts"
        }
    },
    "_embedded": {
        "contacts": [
            {
                "id": 963408,
                "is_deleted": false,
                "is_unsorted": false,
                "request_id": "0",
                "_links": {
                    "self": {
                        "href": "https://devteam.kommo.com/api/v4/contacts/963408"
                    }
                }
            },
            {
                "id": 963410,
                "is_deleted": false,
                "is_unsorted": false,
                "request_id": "1",
                "_links": {
                    "self": {
                        "href": "https://devteam.kommo.com/api/v4/contacts/963410"
                    }
                }
            }
        ]
    }
}

Updating Contacts

Method

PATCH /api/v4/contacts

Description

This method allows updating multiple contacts.

To update a singular contact, you can add the contact ID into the method URL (/api/v4/contacts/{id}).

When updating multiple contacts, an array of contact objects is passed. In case with a singular contact, the contact model is passed.

Limitations

Method is available in correspondence to the user rights.

Request header

Content-Type: application/json

Request body example

[
    {
        "id": 963410,
        "first_name": "John",
        "last_name": "Doe",
        "custom_fields_values": [
            {
                "field_id": 178382,
                "field_name": "Work phone",
                "values": [
                    {
                        "value": "+14155551234",
                        "enum_code": "WORK"
                    }
                ]
            }
        ]
    }
]

Body parameters

No fields are mandatory

Parameter Data type Description
name string Contact fullname
first_name string Contact first name
last_name string Contact last name
responsible_user_id int Contact responsible user ID
created_by int ID of the user who created the contact
updated_by int ID of the user who updated the contact last
created_at int Contact creation date in the format of Unix Timestamp
updated_at int Contact update date in the format of Unix Timestamp
custom_fields_values array An array of the current contact custom fields’ values. Examples of custom fields structure
_embedded object Embedded entities data
_embedded[tags] array Contact tags data array
_embedded[tags][0] object Contact tag model
_embedded[tags][0][id] int Tag ID
_embedded[tags][0][name] string Tag name
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
200 Contacts have been updated successfully
401 User is not authorized
400 Invalid data given. Details are available in the request response

Response parameters

Method returns a collection of updated contacts.

Response example

{
    "_links": {
        "self": {
            "href": "https://devteam.kommo.com/api/v4/contacts"
        }
    },
    "_embedded": {
        "contacts": [
            {
                "id": 963410,
                "name": "John Doe",
                "updated_at": 1687192924,
                "is_deleted": false,
                "is_unsorted": false,
                "_links": {
                    "self": {
                        "href": "https://devteam.kommo.com/api/v4/contacts/963410"
                    }
                }
            }
        ]
    }
}

Linking chats with contacts

Method

POST /api/v4/contacts/chats

Description

This method allows to link chat with a contact.

Chat can only be linked to 1 contact, however, the contact can be linked to several chats.

Limitations

Method is available for administrator users only.

The integration uuid should be specified in the channel settings for the integration calling this method.

Integration can only link chats from the channels it has access to.

Session cookies should not be passed, the method will return an error otherwise.

Request header

Content-Type: application/json

Request parameters

Parameter Data type Description
chat_id string This parameter takes an array of strings – chat uuids
contact_id int This parameter takes an array of integers – contact ids
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

[
    {
        "contact_id": 963410,
        "chat_id": "dd38cf63-e760-4846-9e1e-1b25d1898692"
    }
]

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 links

Parameter Data type Description
id int ID of the chat-to-contact link (can change if the chat link is changed)
contact_id int Contact ID
chat_id string Chat ID
request_id string String that’s passed in the request or an index number if none passed

Response example

{
    "_total_items": 1,
    "_embedded": {
        "chats": [
            {
                "chat_id": "dd38cf63-e760-4846-9e1e-1b25d1898692",
                "contact_id": 963410,
                "id": 101,
                "request_id": "0"
            }
        ]
    }
}

List of contact’s chats

Method

GET /api/v4/contacts/chats

Description

This method allows to get a list of contacts with the linked chat.

If a chat belongs to the Incoming Lead, the method will return an ID of the contact linked to the Incoming Lead.

Limitations

Method is available for administrator users only.

The integration uuid should be specified in the channel settings for the integration calling this method.

Integration can only request chats from the channels it has access to. Therefore, internal Kommo chats will not be returned after calling the method.

Session cookies should not be passed, the method will return an error otherwise.

GET parameters

Parameter Data type Description
chat_id string This parameter takes an array of strings – chat uuids
contact_id int This parameter takes an array of integers – contact ids

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 example

{
    "_total_items": 1,
    "_embedded": {
        "chats": [
            {
                "chat_id": "dd38cf63-e760-4846-9e1e-1b25d1898692",
                "contact_id": 966706, 
                "id": 101 
            } 
         ] 
    } 
}

Response parameters

Method returns a collection of links

Parameter Data type Description
id int ID of the chat-to-contact link (can change if the chat link is changed)
contact_id int Contact ID
chat_id string Chat ID