Customers

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

Table of Contents

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 correspondense 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)
filter object Filter. Filters are described in detail in the separate article

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.amocrm.com/api/v4/customers?limit=2&with=contacts&page=1"
        },
        "next": {
            "href": "https://example.amocrm.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.amocrm.com/api/v4/customers/1"
                    }
                },
                "_embedded": {
                    "segments": [
                        {
                            "id": 43,
                            "_links": {
                                "self": {
                                    "href": "https://example.amocrm.com/api/v4/customers/segments/43"
                                }
                            }
                        },
                        {
                            "id": 45,
                            "_links": {
                                "self": {
                                    "href": "https://example.amocrm.com/api/v4/customers/segments/45"
                                }
                            }
                        },
                        {
                            "id": 47,
                            "_links": {
                                "self": {
                                    "href": "https://example.amocrm.com/api/v4/customers/segments/47"
                                }
                            }
                        },
                        {
                            "id": 51,
                            "_links": {
                                "self": {
                                    "href": "https://example.amocrm.com/api/v4/customers/segments/51"
                                }
                            }
                        }
                    ],
                    "tags": [],
                    "contacts": [
                        {
                            "id": 7143559,
                            "is_main": false,
                            "_links": {
                                "self": {
                                    "href": "https://example.amocrm.com/api/v4/contacts/7143559"
                                }
                            }
                        },
                        {
                            "id": 9820781,
                            "is_main": true,
                            "_links": {
                                "self": {
                                    "href": "https://example.amocrm.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.amocrm.com/api/v4/customers/134923"
                    }
                },
                "_embedded": {
                    "segments": [],
                    "tags": [],
                    "contacts": [
                        {
                            "id": 3,
                            "is_main": true,
                            "_links": {
                                "self": {
                                    "href": "https://example.amocrm.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 correspondense 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.amocrm.com/api/v4/customers/1"
        }
    },
    "_embedded": {
        "segments": [
            {
                "id": 43,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.com/api/v4/customers/segments/43"
                    }
                }
            },
            {
                "id": 45,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.com/api/v4/customers/segments/45"
                    }
                }
            },
            {
                "id": 47,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.com/api/v4/customers/segments/47"
                    }
                }
            },
            {
                "id": 51,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.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 correspondense 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.amocrm.com/api/v4/customers"
        }
    },
    "_embedded": {
        "customers": [
            {
                "id": 134957,
                "request_id": "0"
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.com/api/v4/customers/134957"
                    }
                }
            },
            {
                "id": 134959,
                "request_id": "1"
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.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 correspondense 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.amocrm.com/api/v4/customers"
        }
    },
    "_embedded": {
        "customers": [
            {
                "id": 1299433,
                "updated_at": 1589556420,
                "request_id": "0",
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.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 correspondense 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.amocrm.com/api/v4/customers/transactions?filter%5Bid%5D%5B0%5D=134643&page=1&limit=50"
        },
        "next": {
            "href": "http://example.amocrm.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.amocrm.com/api/v4/customers/1000000158/transactions/134643"
                    }
                },
                "_embedded": {
                    "customer": {
                        "id": 1000000158,
                        "_links": {
                            "self": {
                                "href": "https://example.amocrm.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 a 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 correspondense 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.amocrm.com/api/v4/customers/1/transactions/14755"
        }
    },
    "_embedded": {
        "customer": {
            "id": 1,
            "_links": {
                "self": {
                    "href": "https://example.amocrm.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 correspondense 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.amocrm.com/api/v4/customers"
        }
    },
    "_embedded": {
        "customers": [
            {
                "id": 134957,
                "request_id": "0"
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.com/api/v4/customers/134957"
                    }
                }
            },
            {
                "id": 134959,
                "request_id": "1"
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.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 correspondense 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.