Customers
In this section we will describe all available methods for the Customer entity
Table of Contents
- Enabling customers and changing the customers mode
- Customers list
- Getting a customer by its ID
- Adding customers
- Updating customers
- Transactions list
- Getting a transaction by its ID
- Adding transactions to a customer
- Deleting a trasaction
Enabling customers and changing the customers mode
Method
PATCH /api/v4/customers/mode
Description
This method allows to enable/disable the Customers functionality and change its mode.
Limitations
Method is available for administrator users only.
Request header
Content-Type: application/json
Request parameters
Fields “mode” and “is_enabled” are mandatory
Parameter | Data type | Description |
---|---|---|
mode | string | Customers mode (segments – dynamic segmentation, periodicity – recurring purchases) |
is_enabled | bool | Defines whether the customers functionality is enabled |
An example of the request
{
"mode": "segments",
"is_enabled": 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 |
---|---|
200 | The customers mode has been changed successfully |
402 | Current subscription tariff does not include customers functionality |
401 | User is not authorized |
400 | Invalid data given. Details are available in the request response |
Response parameters
Method returns the passed properties if successful
Response example
{
"mode": "segments",
"is_enabled": true
}
Customers list
Method
GET /api/v4/customers
Description
This method allows to get a list of leads 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 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) |
query | string|int | Search query (will perform a search by custom fields values) |
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 the customer models collection. The properties of a customer model are listed below.
Parameter | Data type | Description |
---|---|---|
id | int | Customer ID |
name | string | Customer name |
next_price | int | Expected purchase value |
next_date | int | Expected purchase date in the format of Unix Timestamp |
responsible_user_id | int | Customer responsible user ID |
periodicity | int | Periodicity (a required parameter when the recurring purchases mode is set) |
created_by | int | ID of the user who created the customer |
updated_by | int | ID of the user who updated the customer last |
created_at | int | Customer creation date in the format of Unix Timestamp |
updated_at | int | Customer update date in the format of Unix Timestamp |
closest_task_at | int | Date of the closest open task in the format of Unix Timestamp |
is_deleted | bool | Defines whether the customer was deleted |
custom_fields_values | array|null | An array of the current customer custom fields’ values |
ltv | int | Total purchase value |
purchases_count | int | Purchases count |
average_check | int | Average purchase value |
account_id | int | Account ID where the customer is located in |
_embedded | object | Embedded entities data |
_embedded[segments] | array | Segments the customer is added to |
_embedded[segments][0] | object | Segment model |
_embedded[segments][0][id] | int | Segment ID |
_embedded[tags] | array | Customer tags data array |
_embedded[tags][0] | object | Customer tag model |
_embedded[tags][0][id] | int | Tag ID |
_embedded[tags][0][name] | string | Tag name |
_embedded[contacts] | array | GET parameter “with” is required. Linked contacts data array |
_embedded[contacts][0] | object | Linked contact data |
_embedded[contacts][0][id] | int | Linked contact ID |
_embedded[contacts][0][is_main] | bool | Defines whether the contact is main for the customer |
_embedded[companies] | array | GET parameter “with” is required. Linked company data array. This array always consists of 1 element as a customer can have only 1 company linked to it |
_embedded[companies][0] | object | Linked company data |
_embedded[companies][0][id] | int | Linked company 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 |
Response example
{
"_page": 1,
"_links": {
"self": {
"href": "https://example.kommo.com/api/v4/customers?limit=2&with=contacts&page=1"
},
"next": {
"href": "https://example.kommo.com/api/v4/customers?limit=2&with=contacts&page=2"
}
},
"_embedded": {
"customers": [
{
"id": 1,
"name": "Customer 1",
"next_price": 214,
"next_date": 1589058000,
"responsible_user_id": 504141,
"status_id": 4740028,
"periodicity": 0,
"created_by": 504141,
"updated_by": 504141,
"created_at": 1582117365,
"updated_at": 1589651187,
"closest_task_at": null,
"is_deleted": false,
"custom_fields_values": null,
"ltv": 1231454,
"purchases_count": 11,
"average_check": 111950,
"account_id": 28805383,
"_links": {
"self": {
"href": "https://example.kommo.com/api/v4/customers/1"
}
},
"_embedded": {
"segments": [
{
"id": 43,
"_links": {
"self": {
"href": "https://example.kommo.com/api/v4/customers/segments/43"
}
}
},
{
"id": 45,
"_links": {
"self": {
"href": "https://example.kommo.com/api/v4/customers/segments/45"
}
}
},
{
"id": 47,
"_links": {
"self": {
"href": "https://example.kommo.com/api/v4/customers/segments/47"
}
}
},
{
"id": 51,
"_links": {
"self": {
"href": "https://example.kommo.com/api/v4/customers/segments/51"
}
}
}
],
"tags": [],
"contacts": [
{
"id": 7143559,
"is_main": false,
"_links": {
"self": {
"href": "https://example.kommo.com/api/v4/contacts/7143559"
}
}
},
{
"id": 9820781,
"is_main": true,
"_links": {
"self": {
"href": "https://example.kommo.com/api/v4/contacts/9820781"
}
}
}
]
}
},
{
"id": 134923,
"name": "Customer 2",
"next_price": 0,
"next_date": 1589403600,
"responsible_user_id": 504141,
"status_id": 4740028,
"periodicity": 0,
"created_by": 504141,
"updated_by": 504141,
"created_at": 1590943901,
"updated_at": 1590943901,
"closest_task_at": null,
"is_deleted": false,
"custom_fields_values": null,
"ltv": 0,
"purchases_count": 0,
"average_check": 0,
"account_id": 28805383,
"_links": {
"self": {
"href": "https://example.kommo.com/api/v4/customers/134923"
}
},
"_embedded": {
"segments": [],
"tags": [],
"contacts": [
{
"id": 3,
"is_main": true,
"_links": {
"self": {
"href": "https://example.kommo.com/api/v4/contacts/3"
}
}
}
]
}
}
]
}
}
Parameters for GET-parameters “with”
Parameter | Description |
---|---|
catalog_elements | Adds lists elements linked to the customer into the response |
contacts | Adds info on the contacts linked to the customer into the response |
companies | Adds info on the companies linked to the customer into the response |
Getting a customer by its ID
Method
GET /api/v4/customers/{id}
Description
This method allows to get a particular customer 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. 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 |
204 | The customer with the specified ID does not exist |
401 | User is not authorized |
Response parameters
Method returns a customer model. The properties of the customer model are listed below.
Parameter | Data type | Description |
---|---|---|
id | int | Customer ID |
name | string | Customer name |
next_price | int | Expected purchase value |
next_date | int | Expected purchase date in the format of Unix Timestamp |
responsible_user_id | int | Customer responsible user ID |
periodicity | int | Periodicity (a required parameter when the recurring purchases mode is set) |
created_by | int | ID of the user who created the customer |
updated_by | int | ID of the user who updated the customer last |
created_at | int | Customer creation date in the format of Unix Timestamp |
updated_at | int | Customer update date in the format of Unix Timestamp |
closest_task_at | int | Date of the closest open task in the format of Unix Timestamp |
is_deleted | bool | Defines whether the customer was deleted |
custom_fields_values | array|null | An array of the current customer custom fields’ values |
ltv | int | Total purchase value |
purchases_count | int | Purchases count |
average_check | int | Average purchase value |
account_id | int | Account ID where the customer is located in |
_embedded | object | Embedded entities data |
_embedded[segments] | array | Segments the customer is added to |
_embedded[segments][0] | object | Segment model |
_embedded[segments][0][id] | int | Segment ID |
_embedded[tags] | array | Customer tags data array |
_embedded[tags][0] | object | Customer tag model |
_embedded[tags][0][id] | int | Tag ID |
_embedded[tags][0][name] | string | Tag name |
_embedded[contacts] | array | GET parameter “with” is required. Linked contacts data array |
_embedded[contacts][0] | object | Linked contact data |
_embedded[contacts][0][id] | int | Linked contact ID |
_embedded[contacts][0][is_main] | bool | Defines whether the contact is main for the customer |
_embedded[companies] | array | GET parameter “with” is required. Linked company data array. This array always consists of 1 element as a customer can have only 1 company linked to it |
_embedded[companies][0] | object | Linked company data |
_embedded[companies][0][id] | int | Linked company 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 |
Response example
{
"id": 1,
"name": "Customer",
"next_price": 214,
"next_date": 1589058000,
"responsible_user_id": 504141,
"status_id": 4740028,
"periodicity": 0,
"created_by": 504141,
"updated_by": 504141,
"created_at": 1582117365,
"updated_at": 1589651187,
"closest_task_at": null,
"is_deleted": false,
"custom_fields_values": null,
"ltv": 1231454,
"purchases_count": 11,
"average_check": 111950,
"account_id": 28805383,
"_links": {
"self": {
"href": "https://example.kommo.com/api/v4/customers/1"
}
},
"_embedded": {
"segments": [
{
"id": 43,
"_links": {
"self": {
"href": "https://example.kommo.com/api/v4/customers/segments/43"
}
}
},
{
"id": 45,
"_links": {
"self": {
"href": "https://example.kommo.com/api/v4/customers/segments/45"
}
}
},
{
"id": 47,
"_links": {
"self": {
"href": "https://example.kommo.com/api/v4/customers/segments/47"
}
}
},
{
"id": 51,
"_links": {
"self": {
"href": "https://example.kommo.com/api/v4/customers/segments/51"
}
}
}
],
"tags": []
}
}
Parameters for GET-parameters “with”
Parameter | Description |
---|---|
catalog_elements | Adds lists elements linked to the customer into the response |
contacts | Adds info on the contacts linked to the customer into the response |
companies | Adds info on the companies linked to the customer into the response |
Adding customers
Method
POST /api/v4/customers
Description
This method allows adding multiple or singular customers into the account.
Limitations
Method is available in correspondence to the user rights.
Request header
Content-Type: application/json
Request parameters
Fields “name” and “next_date” are mandatory when the recurring purchases mode is set
Parameter | Data type | Description |
---|---|---|
name | string | Customer name |
next_price | int | Expected purchase value |
next_date | int | Expected purchase date in the format of Unix Timestamp |
responsible_user_id | int | Customer responsible user ID |
periodicity | int | Periodicity (a required parameter when the recurring purchases mode is set) |
created_by | int | ID of the user who created the customer |
updated_by | int | ID of the user who updated the customer last |
created_at | int | Customer creation date in the format of Unix Timestamp |
updated_at | int | Customer update date in the format of Unix Timestamp |
custom_fields_values | array|null | An array of the current customer custom fields’ values. Examples of custom fields structure |
_embedded | object | Embedded entities data |
_embedded[tags] | array | Customer tags data array |
_embedded[tags][0] | object | Customer 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 |
An example of the request
In the following example we’ll create 2 customers.
For the first one, we’ll specify the Name, Sale, Creator – Robot, and the value of a text field.
For the second one, we’ll specify the Name, will add a Tag, and add the customer into the segment.
[
{
"name": "Example customer 1",
"created_by": 0,
"custom_fields_values": [
{
"field_id": 294479,
"values": [
{
"value": "Text field value"
}
]
}
]
},
{
"name": "Example customer 2",
"_embedded": {
"tags": [
{
"name": "VIP customer"
}
],
"segments": [
{
"id": 81
}
]
}
}
]
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 | Customers 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 customers.
Response example
{
"_links": {
"self": {
"href": "https://example.kommo.com/api/v4/customers"
}
},
"_embedded": {
"customers": [
{
"id": 134957,
"request_id": "0"
"_links": {
"self": {
"href": "https://example.kommo.com/api/v4/customers/134957"
}
}
},
{
"id": 134959,
"request_id": "1"
"_links": {
"self": {
"href": "https://example.kommo.com/api/v4/customers/134959"
}
}
}
]
}
}
Updating customers
Method
PATCH /api/v4/customers
Description
This method allows updating multiple customers.
To update a singular customer, you can add the customer ID into the method URL (/api/v4/customers/{id}).
When updating multiple customers, an array of customer objects is passed. In case with a singular customer, the customer model is passed.
Limitations
Method is available in correspondence to the user rights.
Request header
Content-Type: application/json
Request parameters
No fields are mandatory
Parameter | Data type | Description |
---|---|---|
name | string | Customer name |
next_price | int | Expected purchase value |
next_date | int | Expected purchase date in the format of Unix Timestamp |
responsible_user_id | int | Customer responsible user ID |
periodicity | int | Periodicity (a required parameter when the recurring purchases mode is set) |
created_by | int | ID of the user who created the customer |
updated_by | int | ID of the user who updated the customer last |
created_at | int | Customer creation date in the format of Unix Timestamp |
updated_at | int | Customer update date in the format of Unix Timestamp |
custom_fields_values | array|null | An array of the current customer custom fields’ values. Examples of custom fields structure |
_embedded | object | Embedded entities data |
_embedded[tags] | array | Customer tags data array |
_embedded[tags][0] | object | Customer 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 |
An example of the request
[
{
"id": 1299433,
"name": "New customer title",
"_embedded": {
"tags": [
{
"name": "Tag 125"
}
]
}
}
]
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 | Customers 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 customers.
Response example
{
"_links": {
"self": {
"href": "https://example.kommo.com/api/v4/customers"
}
},
"_embedded": {
"customers": [
{
"id": 1299433,
"updated_at": 1589556420,
"request_id": "0",
"_links": {
"self": {
"href": "https://example.kommo.com/api/v4/customers/1299433"
}
}
}
]
}
}
Transactions list
Method
GET /api/v4/customers/transactions
Description
This method allows to get the list of transactions on the account.
You can also get a particular customer’s transactions using the /api/v4/customers/{customer_id}/transactions method.
Limitations
Method is available in correspondence to the user rights.
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) |
filter | object | Filter |
filter[id] | int|array | Filter by transaction ID |
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 transactions. The properties of the transaction model are listed below.
Parameter | Data type | Description |
---|---|---|
id | int | Transaction ID |
comment | string | Purchase commentary |
price | int | Purchase value |
completed_at | int | Date when the transaction was processed in the format of Unix Timestamp |
customer_id | int | Customer ID the transaction belongs to |
created_by | int | ID of the user who created the transaction |
updated_by | int | ID of the user who updated the transaction last |
created_at | int | Transaction creation date in the format of Unix Timestamp |
updated_at | int | Transaction update date in the format of Unix Timestamp |
is_deleted | bool | Defines whether the transaction was deleted |
account_id | int | Account ID where the customer is located in |
_embedded | object | Embedded entities data |
_embedded[customer] | object | Customer the transaction belongs to |
_embedded[customer][id] | int | Customer ID |
_embedded[catalog_elements] | array | 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 |
Response example
{
"_page": 1,
"_links": {
"self": {
"href": "http://example.kommo.com/api/v4/customers/transactions?filter%5Bid%5D%5B0%5D=134643&page=1&limit=50"
},
"next": {
"href": "http://example.kommo.comu/api/v4/customers/transactions?filter%5Bid%5D%5B0%5D=134643&page=2&limit=50"
}
},
"_embedded": {
"transactions": [
{
"id": 134643,
"price": 123,
"comment": null,
"completed_at": 1591005900,
"customer_id": 1000000158,
"created_by": 939801,
"updated_by": 939801,
"created_at": 1591005900,
"updated_at": 1591005900,
"is_deleted": false,
"account_id": 17079858,
"_links": {
"self": {
"href": "https://example.kommo.com/api/v4/customers/1000000158/transactions/134643"
}
},
"_embedded": {
"customer": {
"id": 1000000158,
"_links": {
"self": {
"href": "https://example.kommo.com/api/v4/customers/1000000158"
}
}
},
"catalog_elements": [
{
"id": 1677,
"metadata": {
"catalog_id": 1079,
"quantity": 10
}
}
]
}
}
]
}
}
Getting a transaction by its ID
Method
GET /api/v4/customers/transactions/{id}
Description
This method allows to get transaction data by its ID.
You can also get a particular customer’s transaction using the /api/v4/customers/{customer_id}/transactions/{id} method.
Limitations
Method is available in correspondence to the user rights.
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 transaction model. The properties of the transaction model are listed below.
Parameter | Data type | Description |
---|---|---|
id | int | Transaction ID |
comment | string | Purchase commentary |
price | int | Purchase value |
completed_at | int | Date when the transaction was processed in the format of Unix Timestamp |
customer_id | int | Customer ID the transaction belongs to |
created_by | int | ID of the user who created the transaction |
updated_by | int | ID of the user who updated the transaction last |
created_at | int | Transaction creation date in the format of Unix Timestamp |
updated_at | int | Transaction update date in the format of Unix Timestamp |
is_deleted | bool | Defines whether the transaction was deleted |
account_id | int | Account ID where the customer is located in |
_embedded | object | Embedded entities data |
_embedded[customer] | object | Customer the transaction belongs to |
_embedded[customer][id] | int | Customer ID |
_embedded[catalog_elements] | array | 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 |
Response example
{
"id": 14755,
"price": 123124,
"comment": "Transaction",
"completed_at": 1589025179,
"customer_id": 1,
"created_by": 504141,
"updated_by": 504141,
"created_at": 1589025179,
"updated_at": 1589025179,
"is_deleted": false,
"account_id": 28805383,
"_links": {
"self": {
"href": "https://example.kommo.com/api/v4/customers/1/transactions/14755"
}
},
"_embedded": {
"customer": {
"id": 1,
"_links": {
"self": {
"href": "https://example.kommo.com/api/v4/customers/1"
}
}
}
}
}
Adding transactions to a customer
Method
POST /api/v4/customers/{customer_id}/transactions
Description
This method allows to add multiple or singular transactions to a particular customer.
Limitations
Method is available in correspondence to the user rights.
Request header
Content-Type: application/json
Request parameters
Field “price” is mandatory
Parameter | Data type | Description |
---|---|---|
comment | string | Purchase commentary |
price | int | Purchase value |
completed_at | int | Date when the transaction was processed in the format of Unix Timestamp |
next_price | int | Expected next purchase value |
next_date | int | Expected next purchase date in the format of Unix Timestamp |
created_by | int | ID of the user who created the transaction |
_embedded[catalog_elements] | array | 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 |
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
[
{
"price":123,
"created_by":0,
"comment":"Commentary",
"_embedded":{
"catalog_elements":[
{
"id":1677,
"metadata":{
"catalog_id":1079,
"quantity":10
}
}
]
}
}
]
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 | Transactions 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 transactions.
Response example
{
"_links": {
"self": {
"href": "https://example.kommo.com/api/v4/customers"
}
},
"_embedded": {
"customers": [
{
"id": 134957,
"request_id": "0"
"_links": {
"self": {
"href": "https://example.kommo.com/api/v4/customers/134957"
}
}
},
{
"id": 134959,
"request_id": "1"
"_links": {
"self": {
"href": "https://example.kommo.com/api/v4/customers/134959"
}
}
}
]
}
}
Deleting a trasaction
Method
DELETE /api/v4/customers/transactions/{id}
Description
This method allows to delete a transaction from the account.
You can also delete a particular customer’s transaction using the /api/v4/customers/{customer_id}/transactions/{id} method.
Limitations
Method is available in correspondence to the user rights.
Request header
Content-Type: application/json
HTTP response codes.
Response code | Case |
---|---|
204 | Transaction has been successfully deleted |
401 | User is not authorized |
400 | Invalid data given. Details are available in the request response |
Response parameters
Method does not return a body.