CUSTOMERS

Methods for working with Customers

The essence of the "leads" is similar. It consists of a predefined set of fields and additional accounts created by the administrator of the account. Each customer can be attached to one or more contacts or not attached to one.

Each customer can be assigned a responsibility to differentiate access rights between employees of the account.

The customer has a time period that indicates the position of the customer in the life cycle (business process). The list of time periods can be changed within the account, except for the first and three final system time periods.

Add, update, or delete customers

The method allows you to add customers one by one or in batch, and also update the data for existing customers and delete them.

URL of the method

POST /api/v2/customers

Parameters
Parameter Type Description
add array List of added customers
update array The list of existing customers where changes will be made. Everything described for adding is also relevant for updating customers
delete array The array of id deletable leads is separated by commas
add/name string Customer Name
add/next_date timestamp Date and time of the next purchase
add/created_at timestamp Date and time the customer was created
add/updated_at timestamp Date and time of the changes made in the customer card
add/responsible_user_id int id of the user responsible for the customer
add/created_by int id of the user who created the customer
add/next_price int Expected amount
add/periodicity int The frequency of purchases
add/tags string Tags that are attached to the customer. Set as a string string variable, inside a line, separated by commas
add/period_id int id of the digital consumer pipeline time period
add/contacts_id array (int) An array of ids of contacts that will be attached to the customer
add/company_id int id of an existing company that will be attached to the customer
add/custom_fields array Array of additional fields of the "customer" entity
add/custom_fields//id int id of the custom field of the entity "customer"
add/custom_fields//values array Array of values ​​of the custom field
add/custom_fields//values//value string The value of the custom field
add/custom_fields//values//enum string The early identifier of the preset choice for the list or multi-selection
update/id
require		 int id of the customer to be changed
update/updated_at
require		 timestamp Date and time of the change
update/unlink array An array containing information to detach a customer from other entity elements.
update/unlink/contacts_id array Array id of unlinked contacts
update/unlink/company_id int id of the company to be uninstalled
Response parameters
Parameter Description
id The unique identifier of the new entity
request_id The unique identifier of the entity in the client program, if request_id is not passed in the request, it is automatically generated
_links An array containing information about the query
_links/self An array containing information about the current request
_links/self/href Relative URL of the current request
_links/self/method The method of the current request
_embedded An array containing information adjacent to the query
_embedded/items An array containing information for each individual element

Response Headers contains the following headers:

  • Content-Type: application / hal + json

  • Runtime-Timestamp: 1508320306

Example of a request to add a new customer

Example response
  1. {
  2.    add: [
  3.       {
  4.          name: "Ecosports LLC",
  5.          next_date: "1508878800",
  6.          created_at: "1508533200",
  7.          responsible_user_id: "504141",
  8.          created_by: "504141",
  9.          next_price: "5000",
  10.          periodicity: "7",
  11.          tags: "sales, markers",
  12.          period_id: "15489654",
  13.          contacts_id: [
  14.             "496531"
  15.          ],
  16.          company_id: "475621",
  17.          custom_fields: [
  18.             {
  19.                id: "4400017",
  20.                values: [
  21.                   {
  22.                      value: "A very important customer"
  23.                   }
  24.                ]
  25.             },
  26.             {
  27.                id: "4400021",
  28.                values: [
  29.                   "3692471",
  30.                   "3692472"
  31.                ]
  32.             },
  33.             {
  34.                id: "4399655",
  35.                values: [
  36.                   {
  37.                      value: "Madison st, 1",
  38.                      subtype: "address_line_1"
  39.                   },
  40.                   {
  41.                      value: "Washington",
  42.                      subtype: "city"
  43.                   },
  44.                   {
  45.                      value: "20011",
  46.                      subtype: "zip"
  47.                   },
  48.                   {
  49.                      value: "US",
  50.                      subtype: "country"
  51.                   }
  52.                ]
  53.             }
  54.          ]
  55.       }
  56.    ]
  57. }
Example response
  1. {
  2.    _links: {
  3.       self: {
  4.          href: "/api/v2/customers",
  5.          method: "post"
  6.       }
  7.    },
  8.    _embedded: {
  9.       items: [
  10.          {
  11.             id: 466812,
  12.             request_id: 0,
  13.                _links: {
  14.                   self: {
  15.                      href: "/api/v2/customers?id=466812",
  16.                      method: "get"
  17.                   }
  18.                }
  19.          }
  20.       ]
  21.    }
  22. }

Example of a change request for a new customer

Example query
  1. {
  2.    update: [
  3.       {
  4.          id: "466791",
  5.          updated_at: "1508619600",
  6.          next_date: "1508878800",
  7.          next_price: "1508706000",
  8.          custom_fields: [
  9.             {
  10.                id: "4400021",
  11.                values: [
  12.                   "3692471",
  13.                   "3692472",
  14.                   "3692473"
  15.                ]
  16.             }
  17.          ]
  18.       }
  19.    ]
  20. }
Example query
  1. {
  2.    _links: {
  3.       self: {
  4.          href: "/api/v2/customers",
  5.          method: "post"
  6.       }
  7.    },
  8.    _embedded: {
  9.       items: [
  10.          {
  11.             id: 466791,
  12.             request_id: 466791,
  13.             _links: {
  14.                self: {
  15.                   href: "/api/v2/customers?id=466791",
  16.                   method: "get"
  17.                }
  18.             }
  19.          }
  20.       ]
  21.    }
  22. }
Customer removal

An example of a request to remove customers.

Example query
  1. {
  2.    delete: [
  3.       "466812",
  4.       "466811",
  5.       "466891"
  6.    ]
  7. }
Example response
  1. {
  2.    _links: {
  3.       self: {
  4.          href: "/api/v2/customers",
  5.          method: "post"
  6.       }
  7.    },
  8.    _embedded: {
  9.       items: {
  10.          deleted: [
  11.             {
  12.                id: 466815,
  13.                name: "Elizabeth"
  14.             },
  15.             {
  16.                id: 466816,
  17.                name: "Jennifer"
  18.             }
  19.          ]
  20.       }
  21.    }
  22. }

List of Customers

Method for obtaining a list of customers with the possibility of filtering and pagination.

URL of the method

GET / api / v2 / customers

GET parameters
Parameter Description
id Select the element with the given ID (If this parameter is specified, all the others are ignored). It is possible to transfer in the form of an array consisting of several IDs)
limit_rows Number of selectable rows (system limit 500)
limit_offset Selection reference (from which row to choose). Works only if limit_rows is also specified
filter/main_user// Select the element by the responsible user (you need to transfer the array with the user ID.
filter/date Select an element by the date of creation or editing (you need to transfer an array with the parameters type, from, to)
filter/date/type Select an item by creation or editing date. Date type: create or modify.
filter/date/from The date from which to start the selection. In the format MM / HH / YYYY. The parameter is set in conjunction with the filter / date / type parameter.
filter/date/to The date to which you want to select. In the format MM / HH / YYYY. The parameter is set in conjunction with the filter / date / type parameter.
filter/next_date Select element by date trace. purchase (you need to pass an array with the parameters from, to)
filter/next_date/from Similarly filter / date / from
filter/next_date/to Similarly filter / date / to

Response Headers contains the following headers:

  • Content-Type: application / hal + json

  • Runtime-Timestamp: 1508320306

Response parameters
Parameter Type Description
id int Unique identifier of the "customer"
name
require		 string Element name
responsible_user_id int id of the user responsible for the customer
created_by int id of the user who created the customer
created_at timestamp Date and time the customer was created
updated_at timestamp Date and time of the change of the customer
account_id int id of the account in which the customer was created
updated_by int id of the user who changed the customer
is_deleted bool The customer was deleted or not deleted.
main_contact array An array containing information about the main contact of the customer
main_contact/id int id of the main contact of the customer
tags array An array containing information on tags attached to a given customer
tags/id int id of the tag attached to this customer
tags/name string The name of the tag attached to this customer
custom_fields array An array containing information on additional fields specified for a given customer
custom_fields/id int id of the additional field
custom_fields/name string Name of the additional field
custom_fields/values array An array containing information on additional fields specified for a given customer
custom_fields/values//value string The value of the additional field
custom_fields/values//enum string Early identifier of the preset option for the list or multi-selection
custom_fields/is_system bool Is the extra field systemic
contacts array An array containing information on contacts attached to a given customer
contacts/id int id of the contact attached to the lead
company array An array containing information about a company that is attached to a given customer
company/id int id of the company that is attached to this lead
company/name string the name of the company that is attached to the lead
next_price int Expected amount
closest_task_at timestamp The time of the nearest task for the given customer
period_id timestamp Unique period identifier, digital pipeline of customers
periodicity int Periodicity
next_date
require		 timestamp Next purchase date
_links array Array containing information about the request
_links/self array An array containing information about the current request
_links/self/href string Relative URL of the current request
_links/self/method string Method of the current request
_embedded array An array containing information adjacent to the query
_embedded/items array An array containing information for each individual element
Example query

Example GET request list of customers created on 10/10/2017 https://example.amocrm.com/api/v2/customers?filter[date][type]=create&filter[date][from]=10.10.2017

Example response
  1. {
  2.    _links: {
  3.       self: {
  4.          href: "/api/v2/customers",
  5.          method: "get"
  6.       }
  7.    },
  8.    _embedded: {
  9.       items: [
  10.          {
  11.             id: 466791,
  12.             name: "Catherine",
  13.             responsible_user_id: 504141,
  14.             created_by: 504141,
  15.             created_at: 1508500193,
  16.             updated_at: 1508659120,
  17.             account_id: 13667499,
  18.             updated_by: 504141,
  19.             is_deleted: false,
  20.             main_contact: {
  21.                id: 1099181,
  22.                _links: {
  23.                   self: {
  24.                      href: "/api/v2/contacts?id=1099181",
  25.                      method: "get"
  26.                   }
  27.                }
  28.             },
  29.             tags: [
  30.                {
  31.                   id: 61869,
  32.                   name: "Sales"
  33.                },
  34.                {
  35.                   id: 61870,
  36.                   name: "Markers"
  37.                }
  38.             ],
  39.             custom_fields: [
  40.                {
  41.                   id: 4400017,
  42.                   name: "Remarks",
  43.                   values: [
  44.                      {
  45.                         value: "Delayed payment"
  46.                      }
  47.                   ],
  48.                   is_system: false
  49.                },
  50.                {
  51.                   id: 4400021,
  52.                   name: "Multi-select",
  53.                   values: [
  54.                      {
  55.                         value: "3",
  56.                         enum: "3692471"
  57.                      },
  58.                      {
  59.                         value: "4",
  60.                         enum: "3692472"
  61.                      },
  62.                      {
  63.                         value: "5",
  64.                         enum: "3692473"
  65.                      }
  66.                   ],
  67.                   is_system: false
  68.                },
  69.             ],
  70.             contacts: {
  71.                id: [
  72.                   1099181
  73.                ],
  74.                _links: {
  75.                   self: {
  76.                      href: "/api/v2/contacts?id=1099181",
  77.                      method: "get"
  78.                   }
  79.                }
  80.             },
  81.             company: {
  82.                id: 1099180,
  83.                name: SpetsGorStroy LLC,
  84.                _links: {
  85.                   self: {
  86.                      href: "/api/v2/companies?id=1099180",
  87.                      method: "get"
  88.                   }
  89.                }
  90.             },
  91.             next_price: 1508706000,
  92.             closest_task_at: 1508705940,
  93.             period_id: 112804,
  94.             periodicity: 0,
  95.             next_date: 1508878800,
  96.             _links: {
  97.                self: {
  98.                   href: "/api/v2/customers?id=466791",
  99.                   method: "get"
  100.                }
  101.             }
  102.          }
  103.       ]
  104.    }
  105. }

An example of integration working with the "Customer"

To add a customer, you need to describe an array containing information about the customer. Our API also supports the simultaneous addition of multiple customers. To do this, we place several arrays in the query array, each of which describes the necessary data for creating the corresponding customer.

Example of integration
  1. $customers['add'] = array(
  2.    array(
  3.       'name' => 'Jerry',
  4.       'next_date' => '1508792400',
  5.       'created_at' => '1508619600',
  6.       'responsible_user_id' => 504141,
  7.       'created_by' => 504141,
  8.       'next_price' => 7000,
  9.       'periodicity' => 7,
  10.       'tags' => "Sales, Pencils",
  11.       'period_id' => 153795,
  12.       'contacts_id' => array(468986,468979),
  13.       'company_id' => 356463,
  14.       'custom_fields' => array(
  15.          array(
  16.             'id' => 4400017,
  17.             'values' => array(
  18.                array(
  19.                   'value' => "Important Customer"
  20.                )
  21.             )
  22.          ),
  23.          array(
  24.             'id' => 4400021,
  25.             'values' => array(
  26.                "3692469",
  27.                "3692470",
  28.                "3692471"
  29.             )
  30.          ),
  31.       array(
  32.         'id'=>458615, #The unique identifier of the additional field to be filled
  33.        'values'=>array(
  34.           array(
  35.             'value' => 'Address line 1',
  36.             'subtype' => 'address_line_1',
  37.           ),
  38.           array(
  39.             'value' => 'Address line 2',
  40.             'subtype' => 'address_line_2',
  41.           ),
  42.           array(
  43.             'value' => 'City',
  44.             'subtype' => 'city',
  45.           ),
  46.           array(
  47.             'value' => 'State',
  48.             'subtype' => 'state',
  49.           ),
  50.           array(
  51.             'value' => '203',
  52.             'subtype' => 'zip',
  53.           ),
  54.           array(
  55.             'value' => 'US',
  56.             'subtype' => 'country',
  57.           )
  58.         )
  59.       )
  60. )
  61. ),
  62.   array(
  63.     'name'=>'Jason',
  64.     'created_at'=>1298904164,
  65.     'next_date' => '1508782500',
  66.     'next_price'=>600200,
  67.     'responsible_user_id'=>215309,
  68.     'custom_fields'=>array(
  69.       array(
  70.         #A non-standard additional field such as the "multi-select" that we created
  71.        'id'=>426106,
  72.         'values'=>array(
  73.           1237756,
  74.           1237758
  75.         )
  76.       )
  77.     )
  78. )
  79. );
  80. /* Now prepare the data needed to query the server */
  81. $subdomain='test'; #Our account - subdomain
  82. #Generate a link for the request
  83. $link='https://'.$subdomain.'.amocrm.com/api/v2/customers';
  84. /* We need to initiate a request to the server. We use the cURL library (supplied as part of PHP). More about
  85. work with this
  86. library you can
  87. read the manual. */
  88. $curl=curl_init(); #Save the cURL session descriptor
  89. #Set the necessary options for the cURL session
  90. curl_setopt($curl,CURLOPT_RETURNTRANSFER,true);
  91. curl_setopt($curl,CURLOPT_USERAGENT,'amoCRM-API-client/1.0');
  92. curl_setopt($curl,CURLOPT_URL,$link);
  93. curl_setopt($curl,CURLOPT_CUSTOMREQUEST,'POST');
  94. curl_setopt($curl,CURLOPT_POSTFIELDS,json_encode($customers));
  95. curl_setopt($curl,CURLOPT_HTTPHEADER,array('Content-Type: application/json'));
  96. curl_setopt($curl,CURLOPT_HEADER,false);
  97. curl_setopt($curl,CURLOPT_COOKIEFILE,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
  98. curl_setopt($curl,CURLOPT_COOKIEJAR,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
  99. curl_setopt($curl,CURLOPT_SSL_VERIFYPEER,0);
  100. curl_setopt($curl,CURLOPT_SSL_VERIFYHOST,0);
  101. $out=curl_exec($curl); #Initiate a request to the API and save the response to a variable
  102. $code=curl_getinfo($curl,CURLINFO_HTTP_CODE);
  103. /* Now we can process the response received from the server. This is an example. You can process the data in your own way. */
  104. $code=(int)$code;
  105. $errors=array(
  106.   301=>'Moved permanently',
  107.   400=>'Bad request',
  108.   401=>'Unauthorized',
  109.   403=>'Forbidden',
  110.   404=>'Not found',
  111.   500=>'Internal server error',
  112.   502=>'Bad gateway',
  113.   503=>'Service unavailable'
  114. );
  115. try
  116. {
  117.   #If the response code is not 200 or 204, we return an error message
  118.  if($code!=200 && $code!=204)
  119.     throw new Exception(isset($errors[$code]) ? $errors[$code] : 'Undescribed error',$code);
  120. }
  121. catch(Exception $E)
  122. {
  123.   die('Error: '.$E->getMessage().PHP_EOL.'Error code: '.$E->getCode());
  124. }

Transactions

A transaction is an entity that describes the basic characteristics of a purchase (date and amount). Is an addition for the "customer".

Adding and Deleting Transactions

The method allows you to add and delete transactions one by one or batch.

Parameters
Parameter Type Description
add array List of added transactions
add/customer_id int Unique customer ID
add/date timestamp Date of purchase
add/price int Amount of the purchase made
add/comment string Comment for purchase
add/next_date timestamp Expected date of purchase
add/next_price int Expected purchase amount
delete array(int) An array with unique transaction IDs that are specified for deletion purposes
Response parameters
Parameter Type Description
items array(int) The array of id created deals
_links array Array containing information about the request
_links/self array An array containing information about the current request
_links/self/href string Relative URL of the current request
_links/self/method string Method of the current request
_embedded array An array containing information adjacent to the query
_embedded/items array An array containing information for each individual element

Response Headers contains the following headers:

  • Content-Type: application / hal + json

  • Runtime-Timestamp: 1508320306

Example of a request to add a transaction

Example query
  1. {
  2.    add: [
  3.       {
  4.          customer_id: "466791",
  5.          date: "1507582800",
  6.          price: "15000",
  7.          comment: "Everything went well",
  8.          next_date: "1508878800",
  9.          next_price: "20000"
  10.       }
  11.    ]
  12. }
Example response
  1. {
  2.    _links: {
  3.       self: {
  4.          href: "/api/v2/transactions",
  5.          method: "post"
  6.       }
  7.    },
  8.    _embedded: {
  9.       items: [
  10.          {
  11.             id: 5396,
  12.             _links: {
  13.                self: {
  14.                   href: "/api/v2/transactions?id=5396",
  15.                   method: "get"
  16.                }
  17.             }
  18.          }
  19.       ]
  20.    }
  21. }

Example request to delete transactions

Example query
  1. {
  2.    delete: [
  3.       "4589",
  4.       "4588",
  5.       "4587"
  6.    ]
  7. }
Commenting on Transactions

Method for adding and modifying the comment of an existing transaction. If you change the comment of an existing transaction, the transaction itself is not updated.

Method URL

POST / api / v2 / transactions /

Parameters
Parameter Type Description
update array List of added / modified comments
update/transaction_id
require		 int Unique transaction identifier
update/comments
require		 string Comment text
Response parameters
Parameter Type Description
items array Array of added / modified comments
id int id of the added / changed comment
_links array Array containing information about the request
_links/self array An array containing information about the current request
_links/self/href string Relative URL of the current request
_links/self/method string Method of the current request
_embedded array An array containing information adjacent to the query
_embedded/items array An array containing information for each individual element

Response Headers contains the following headers:

  • Content-Type: application / hal + json

  • Runtime-Timestamp: 1508320306

Example query
  1. {
  2.    update: [
  3.       {
  4.          transaction_id: "5396",
  5.          comment: "Draw up a contract"
  6.       }
  7.    ]
  8. }
Example response
  1. {
  2.    _links: {
  3.       self: {
  4.          href: "/api/v2/transactions",
  5.          method: "post"
  6.       }
  7.    },
  8.    _embedded: {
  9.       items: [
  10.          {
  11.             id: 5396,
  12.             _links: {
  13.                self: {
  14.                   href: "/api/v2/transactions?id=5396",
  15.                   method: "get"
  16.                }
  17.             }
  18.          }
  19.       ]
  20.    }
  21. }
Example integration
  1. $transactions['add'] = array(
  2.   array(
  3.     'price'=>3000,
  4.     'date'=>1476813651,
  5.     'customer_id'=>33221355,
  6.     'comment' => "example"
  7.   ),
  8.   array(
  9.     'price'=>9500,
  10.     'date'=>14762143651,
  11.     'customer_id'=>75321111,
  12.     'comment' => "example 2"
  13.   )
  14. );
  15. /* Now prepare the data needed to query the server */
  16. $subdomain='test'; #Our account is a subdomain
  17. #Generate a link for the request
  18. $link='https://'.$subdomain.'.amocrm.com/api/v2/transactions';
  19. /* We need to initiate a request to the server. We use the cURL library (supplied as part of PHP). More about
  20. work with this
  21. library you can
  22. read the manual. */
  23. $curl=curl_init(); #Save the cURL session descriptor
  24. #Set the necessary options for the cURL session
  25. curl_setopt($curl,CURLOPT_RETURNTRANSFER,true);
  26. curl_setopt($curl,CURLOPT_USERAGENT,'amoCRM-API-client/1.0');
  27. curl_setopt($curl,CURLOPT_URL,$link);
  28. curl_setopt($curl,CURLOPT_CUSTOMREQUEST,'POST');
  29. curl_setopt($curl,CURLOPT_POSTFIELDS,json_encode($transactions));
  30. curl_setopt($curl,CURLOPT_HTTPHEADER,array('Content-Type: application/json'));
  31. curl_setopt($curl,CURLOPT_HEADER,false);
  32. curl_setopt($curl,CURLOPT_COOKIEFILE,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
  33. curl_setopt($curl,CURLOPT_COOKIEJAR,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
  34. curl_setopt($curl,CURLOPT_SSL_VERIFYPEER,0);
  35. curl_setopt($curl,CURLOPT_SSL_VERIFYHOST,0);
  36. $out=curl_exec($curl); #Initiate a request to the API and save the response to a variable
  37. $code=curl_getinfo($curl,CURLINFO_HTTP_CODE);
  38. /* Now we can process the response received from the server. This is an example. You can process the data in your own way. */
  39. $code=(int)$code;
  40. $errors=array(
  41.   301=>'Moved permanently',
  42.   400=>'Bad request',
  43.   401=>'Unauthorized',
  44.   403=>'Forbidden',
  45.   404=>'Not found',
  46.   500=>'Internal server error',
  47.   502=>'Bad gateway',
  48.   503=>'Service unavailable'
  49. );
  50. try
  51. {
  52.   #If the response code is not 200 or 204, we return an error message
  53.  if($code!=200 && $code!=204)
  54.     throw new Exception(isset($errors[$code]) ? $errors[$code] : 'Undescribed error',$code);
  55. }
  56. catch(Exception $E)
  57. {
  58.   die('Error: '.$E->getMessage().PHP_EOL.'Error code: '.$E->getCode());
  59. }

Transaction List

A method for obtaining a list of transactions with the ability to filter.

Method URL

GET / api / v2 / transactions

GET parameters
Parameters Description
id Select transaction with given id
customer_id Select transaction that is tied to the customer with the specified id
limit_rows Number of selectable rows (system limit 500)
limit_offset Selection reference (from which row to choose). Works only if limit_rows is also specified
Response parameters
Parameter Type Description
items array Array of selected transactions
items/id int Unique transaction identifier
items/created_by int ID of the user who created the transaction
items/created_at timestamp Date and time the transaction was created
items/updated_at timestamp Date and time of transaction change
items/account_id int id of the account on which the transaction was created
items/updated_by int id of the user who changed the transaction
items/is_deleted bool Deleted transaction or not
items/comment string Comment
items/price int Purchase amount
items/date timestamp Date of purchase
items/customer array An array containing information about the customer
items/customer/id int id customer
_links array Array containing information about the request
_links/self array An array containing information about the current request
_links/self/href string Relative URL of the current request
_links/self/method string Method of the current request
_embedded array An array containing information adjacent to the query
_embedded/items array An array containing information for each individual element
Example query

Example GET request list of customers created on 10/10/2017 https://example.amocrm.com/api/v2/transactions?limit_rows=50&customer_id=46879

Example response
  1. {
  2.    _links: {
  3.       self: {
  4.          href: "/api/v2/transactions",
  5.          method: "get"
  6.       }
  7.    },
  8.    _embedded: {
  9.       items: [
  10.          {
  11.             id: 5400,
  12.             created_by: 504141,
  13.             created_at: 1508671514,
  14.             updated_at: 1508671514,
  15.             account_id: 13667499,
  16.             updated_by: 504141,
  17.             is_deleted: false,
  18.             comment: "",
  19.             price: 55555,
  20.             date: 1508360400,
  21.             customer: {
  22.                id: 466791,
  23.                _links: {
  24.                   self: {
  25.                      href: "/api/v2/customers?id=466791",
  26.                      method: "get"
  27.                   }
  28.                }
  29.             },
  30.             _links: {
  31.                self: {
  32.                   href: "/api/v2/transactions?id=5400",
  33.                   method: "get"
  34.                }
  35.             }
  36.          },
  37.          {
  38.             id: 5399,
  39.             created_by: 504141,
  40.             created_at: 1508665872,
  41.             updated_at: 1508665872,
  42.             account_id: 13667499,
  43.             updated_by: 504141,
  44.             is_deleted: false,
  45.             comment: "",
  46.             price: 15000,
  47.             date: 1507582800,
  48.             customer: {
  49.                id: 466791,
  50.                _links: {
  51.                   self: {
  52.                      href: "/api/v2/customers?id=466791",
  53.                      method: "get"
  54.                   }
  55.                }
  56.             },
  57.             _links: {
  58.                self: {
  59.                   href: "/api/v2/transactions?id=5399",
  60.                   method: "get"
  61.                }
  62.             }
  63.          }
  64.       ]
  65.    }
  66. }

Stages of customers

Stages of customer is a sequence of steps that a potential customer (customer) is taking on the pipeline of customers before buying. In amoCRM, you can create your own periods to track the progress of the customer. The customer pipeline can contain 10 periods "before purchase" (including "recently bought", "bought today" and "not bought"). The administrator of the account can configure the periods on the Digital Pipeline page. These methods are only available to the account administrator

Add, delete, and update customer stages

The method allows you to change data by period. When changing, you need to transfer a complete list of periods, including those already existing. When deleting a period, you need to exclude it from the query.

Method URL

POST / api / v2 / customers_periods

Parameters
Parameter Type Description
update array Редактирование периодов покупателя
update//period int Number of days in the period. IMPORTANT!!! This parameter determines the fixed length of the period and does not coincide with the number of days "before purchase". The number of days before the purchase is calculated by adding this parameter for all periods from the "purchase day" to the right to the left. For example: to get "90, 30 and 10 days before the purchase," you need to create 3 periods of 10, 20 and 60 days: 1) 10 + 20 = 30 days before the purchase. 2) 30 + 60 = 90 days before purchase.
update//id int The unique identifier of the pipeline. (If the id is not passed, a new period will be created).
update//color string Period color
update//sort int The period ordinal of the period when displayed (Periods are displayed to the right of the left starting from the "purchase day").
Available color periods
Code Sample
#fffeb2 color example
#fffd7f color example
#fff000 color example
#ffeab2 color example
#ffdc7f color example
#ffce5a color example
#ffdbdb color example
#ffc8c8 color example
#ff8f92 color example
#d6eaff color example
#c1e0ff color example
#98cbff color example
#ebffb1 color example
#deff81 color example
#87f2c0 color example
#f9deff color example
#f3beff color example
#ccc8f9 color example
#eb93ff color example
#f2f3f4 color example
#e6e8ea color example
Response parameters
Parameter Type Description
items array An array of created / modified periods
items/id int Unique period identifier
items//type string The type of the period (before, after). The after type can only be edited.
items//period int Number of days in the period
items//color string The color of the period
items//sort int The period ordinal of the period in the display
items/after_buy int Number of days after purchase (period "not bought")
_links array Array containing information about the request
_links/self array An array containing information about the current request
_links/self/href string Relative URL of the current request
_links/self/method string Method of the current request
_embedded array An array containing information adjacent to the query
_embedded/items array An array containing information for each individual element

Response Headers contains the following headers:

  • Content-Type: application / hal + json

  • Runtime-Timestamp: 1508320306

Example query
  1. {
  2.    update: [
  3.       {
  4.          period: "5",
  5.          id: "15563",
  6.          color: "#000000",
  7.          sort: "1"
  8.       }
  9.    ]
  10. }
Example response
  1. {
  2.    _links: {
  3.       self: {
  4.          href: "/api/v2/customers_periods",
  5.          method: "post"
  6.       }
  7.    },
  8.    _embedded: {
  9.       items: [
  10.          {
  11.             id: 112805,
  12.             type: "after",
  13.             period: 60,
  14.             color: "#fd5598",
  15.             sort: 0,
  16.             after_buy: 60,
  17.             _links: {
  18.                self: {
  19.                   href: "/api/v2/customers_periods",
  20.                   method: "get"
  21.                }
  22.             }
  23.          }
  24.       ]
  25.    }
  26. }
An example of integration working with stages of customers
  1. $customers_periods['update'] = array(
  2.   [
  3.     "period" => 10,
  4.     "color" => "#fffd7f",
  5.     "sort" => 0
  6.   ],
  7.   [
  8.     "id" => 110412,
  9.     "period" => 20,
  10.     "color" => "#ffdc7f",
  11.     "sort" => 1
  12.   ],
  13.   [
  14.     "id" => 110157,
  15.     "period" => 60,
  16.     "color" => "#ccc8f9",
  17.     "sort" => 2
  18.   ],
  19. );
  20. /* Now prepare the data needed to query the server */
  21. $subdomain='test'; #Our account is a subdomain
  22. #Generate a link for the request
  23. $link='https://'.$subdomain.'.amocrm.com/api/v2/customers_periods';
  24. /* We need to initiate a request to the server. We use the cURL library (supplied as part of PHP). More about
  25. work with this
  26. library you can
  27. read the manual. */
  28. $curl=curl_init(); #Save the cURL session descriptor
  29. #Set the necessary options for the cURL session
  30. curl_setopt($curl,CURLOPT_RETURNTRANSFER,true);
  31. curl_setopt($curl,CURLOPT_USERAGENT,'amoCRM-API-client/1.0');
  32. curl_setopt($curl,CURLOPT_URL,$link);
  33. curl_setopt($curl,CURLOPT_CUSTOMREQUEST,'POST');
  34. curl_setopt($curl,CURLOPT_POSTFIELDS,json_encode(;customers_periods));
  35. curl_setopt($curl,CURLOPT_HTTPHEADER,array('Content-Type: application/json'));
  36. curl_setopt($curl,CURLOPT_HEADER,false);
  37. curl_setopt($curl,CURLOPT_COOKIEFILE,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
  38. curl_setopt($curl,CURLOPT_COOKIEJAR,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
  39. curl_setopt($curl,CURLOPT_SSL_VERIFYPEER,0);
  40. curl_setopt($curl,CURLOPT_SSL_VERIFYHOST,0);
  41. $out=curl_exec($curl); #Initiate a request to the API and save the response to a variable
  42. $code=curl_getinfo($curl,CURLINFO_HTTP_CODE);
  43. /* Now we can process the response received from the server. This is an example. You can process the data in your own way. */
  44. $code=(int)$code;
  45. $errors=array(
  46.   301=>'Moved permanently',
  47.   400=>'Bad request',
  48.   401=>'Unauthorized',
  49.   403=>'Forbidden',
  50.   404=>'Not found',
  51.   500=>'Internal server error',
  52.   502=>'Bad gateway',
  53.   503=>'Service unavailable'
  54. );
  55. try
  56. {
  57.   #If the response code is not 200 or 204, we return an error message
  58.  if($code!=200 && $code!=204)
  59.     throw new Exception(isset($errors[$code]) ? $errors[$code] : 'Undescribed error',$code);
  60. }
  61. catch(Exception $E)
  62. {
  63.   die('Error: '.$E->getMessage().PHP_EOL.'Error code: '.$E->getCode());
  64. }

List of customer stages

Method for obtaining a list of periods. The GET request is sent without any additional parameters.

Method URL

GET / api / v2 / customers_periods

Response parameters
Parameter Type Description
items array An array of created / modified periods
items/id int Unique period identifier
items//type string The type of the period (before, after). The after type can only be edited.
items//period int Number of days in the period
items//color string The color of the period
items//sort int The period ordinal of the period in the display
items/after_buy int Number of days after purchase (period "not bought")
_links array Array containing information about the request
_links/self array An array containing information about the current request
_links/self/href string Relative URL of the current request
_links/self/method string Method of the current request
_embedded array An array containing information adjacent to the query
_embedded/items array An array containing information for each individual element
Example query

Example GET request list of stages of customers https://example.amocrm.com/api/v2/customers_periods

Example response
  1. {
  2.    _links: {
  3.       self: {
  4.          href: "/api/v2/customers_periods",
  5.          method: "get"
  6.       }
  7.    },
  8.    _embedded: {
  9.       items: [
  10.          {
  11.             id: 112815,
  12.             type: "before",
  13.             period: 5,
  14.             color: "#e6e8ea",
  15.             sort: 1,
  16.             before_buy: 5
  17.          },
  18.          {
  19.             id: 112805,
  20.             type: "after",
  21.             period: 60,
  22.             color: "#fd5598",
  23.             sort: 0,
  24.             after_buy: 60
  25.          }
  26.       ]
  27.    }
  28. }