Methods of List Elements

Adding, updating, or deleting list elements

These methods are only available to users who have permission to access the lists.

The method allows you to add list items one by one or in batches, and also to update data on already existing elements and delete them.

Method URL

POST / api / v2 / catalog_elements

Parameters
Parameter Type Description
add array List of added list items
update array Updating existing list items
All the parameters that are described in add also work in the update
delete array Array of deleted list items
add/catalog_id
require
string List ID
add/name
require
string Name of element
add/request_id int Unique identifier of a record in the client program, optional parameter (information about request_id is not saved anywhere)
add/custom_fields array Additional fields
add/custom_fields// array Inside it will be a description of each additional field
add/custom_fields//id int The unique identifier of the additional field to be filled (see Account Information)
add/custom_fields//values array Inside there will be another array, with the value
add/custom_fields//values// array Here, the values of add. fields, and, if necessary, an additional type (for fields like "multi-list" we simply list the id of the selected values)
add/custom_fields//values//value string Value of an additional field
add/custom_fields//values//enum string Selectable type of additional field (for example, phone home, work, etc.)
add/custom_fields//values//subtype string The type of the additional field element to change. Attention, all types not specified will be erased
update/id
require
int The unique identifier of the list item, which is indicated for the purpose of updating it
update/updated_at
require
int The unique identifier of the list item, which is indicated for the purpose of updating it
Example
  1. {
  2.    add: [
  3.       {
  4.          catalog_id: "4220",
  5.          name: "Pencil",
  6.          custom_fields: [
  7.             {
  8.                id: "4400050",
  9.                values: [
  10.                   {
  11.                      value: "100"
  12.                   }
  13.                ]
  14.             },
  15.             {
  16.                id: "4400062",
  17.                values: [
  18.                   "3692539",
  19.                   "3692540"
  20.                ]
  21.             }
  22.          ]
  23.       }
  24.    ]
  25. }
Response parameters
Parameter Description
id Unique identifier for a new directory entry
request_id The unique identifier of the entity in the client program, if the 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 Current request method
_embedded An array containing information adjacent to the query
_embedded/items An array containing information for each individual element
Example
  1. {
  2.    _link: {
  3.       self: {
  4.          href: "/api/v2/catalog_elements",
  5.          method: "post"
  6.       }
  7.    },
  8.    _embedded: {
  9.       items: [
  10.          {
  11.             id: 41870,
  12.             request_id: 0,
  13.             _link: {
  14.                self: {
  15.                   href: "/api/v2/catalog_elements?id=41870",
  16.                   method: "get"
  17.                }
  18.             }
  19.          }
  20.       ]
  21.    }
  22. }
Adding Items

To create a new list item, you need to describe an array containing information about it and put it into an array of the following form: $catalog_elements['add']

Our API also supports the simultaneous addition of several list items at once. To do this, we place several arrays in the array $catalog_elements['add'], each of which describes the necessary data to create the corresponding list.

Here you can see the structure of custom fields using an array of a list item.

Example
  1. $catalog_elements['add'] = array(
  2.   array(
  3.       'catalog_id'=>2534,
  4.     'name'=>'Black iPhone',
  5.   ),
  6.   array(
  7.       'catalog_id'=>2534,
  8.     'name'=>'Really Black iPhone',
  9.   )
  10. );
  11. /* Now prepare the data needed to query the server */
  12. $subdomain='test'; #Our account is a subdomain
  13. #We form the reference for the query
  14. $link='https://'.$subdomain.'.amocrm.com/api/v2/catalog_elements';
  15. /* We need to initiate a request to the server. We use the cURL library (supplied as part of PHP). More about
  16. work with this
  17. library you can read in the manual. */
  18. $curl=curl_init(); #We save the cURL session handle
  19. #Set the necessary options for the cURL session
  20. curl_setopt($curl,CURLOPT_RETURNTRANSFER,true);
  21. curl_setopt($curl,CURLOPT_USERAGENT,'amoCRM-API-client/1.0');
  22. curl_setopt($curl,CURLOPT_URL,$link);
  23. curl_setopt($curl,CURLOPT_CUSTOMREQUEST,'POST');
  24. curl_setopt($curl,CURLOPT_POSTFIELDS,json_encode($catalogs));
  25. curl_setopt($curl,CURLOPT_HTTPHEADER,array('Content-Type: application/json'));
  26. curl_setopt($curl,CURLOPT_HEADER,false);
  27. curl_setopt($curl,CURLOPT_COOKIEFILE,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
  28. curl_setopt($curl,CURLOPT_COOKIEJAR,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
  29. curl_setopt($curl,CURLOPT_SSL_VERIFYPEER,0);
  30. curl_setopt($curl,CURLOPT_SSL_VERIFYHOST,0);
  31. $out=curl_exec($curl); #Initiate a request to the API and save the response to a variable
  32. $code=curl_getinfo($curl,CURLINFO_HTTP_CODE);
  33. /* Now we can process the response received from the server. This is an example. You can process the data in your own way. */
  34. $code=(int)$code;
  35. $errors=array(
  36.   301=>'Moved permanently',
  37.   400=>'Bad request',
  38.   401=>'Unauthorized',
  39.   403=>'Forbidden',
  40.   404=>'Not found',
  41.   500=>'Internal server error',
  42.   502=>'Bad gateway',
  43.   503=>'Service unavailable'
  44. );
  45. try
  46. {
  47.   #If the response code is not 200 or 204, we return an error message
  48.  if($code!=200 && $code!=204)
  49.     throw new Exception(isset($errors[$code]) ? $errors[$code] : 'Undescribed error',$code);
  50. }
  51. catch(Exception $E)
  52. {
  53.   die('Error: '.$E->getMessage().PHP_EOL.'Error code: '.$E->getCode());
  54. }
  55. /*
  56.  The data is obtained in the JSON format, therefore, in order to obtain readable data,
  57.  We will have to translate the answer into a format that PHP understands
  58.  */
  59. $Response=json_decode($out,true);
  60. $Response=$Response['_embedded']['items'];
  61. $output='ID of added list items:'.PHP_EOL;
  62. foreach($Response as $v)
  63.   if(is_array($v))
  64.     $output.=$v['id'].PHP_EOL;
  65. return $output;
Updating elements

To update a list item, you need to create an array containing information about it and put it into an array of the following form: $catalog_elements['update']

Our API also supports the simultaneous updating of several list items at once. To do this, we put several arrays in the array $catalog_elements['update'], each of which describes the necessary data for updating the corresponding element.

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

To delete a list item, you need to describe an array containing information about it and put it into an array of the following form: $catalog_elements['delete']

Our API also supports simultaneous deletion of several list items at once. To do this, we put several elements into the array $catalog_elements['delete'], each of which describes the necessary data to delete the corresponding element.

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

List of list elements

A method for retrieving items in the account list.

Method URL

GET / api / v2 / catalog_elements

GET parameters
Parameter Description
id Select item with given id
catalog_id
require
Select data from a specific list
term Search query for item name
Answer parameters
Parameter Type Description
id int Unique item identifier
name string Item name
created_at timestamp Date of creation
updated_at timestamp Date of change
catalog_id int id of the list in which the item is located
created_by id id of the user who created the lead
is_deleted bool Deleted item or not
custom_fields array An array of additional list item fields
custom_fields//id int Unique identifier for the additional field
custom_fields//name string Name of additional field
custom_fields//values array An array of values of the current additional field
custom_fields//values//value string Value of the current additional field
custom_fields//values//enum string Early identifier of pre-selected option for list or multisession
custom_fields//is_system bool Is an additional field systemic or not
_links array An array containing information about the query
_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 Current request method
_embedded array An array containing information adjacent to the query
_embedded/items array An array containing information for each individual element
Example
  1. {
  2.    _links: {
  3.       self: {
  4.          href: "/api/v2/catalog_elements?catalog_id=4220",
  5.          method: "get"
  6.       }
  7.    },
  8.    _embedded: {
  9.       items: [
  10.          {
  11.             id: 41873,
  12.             name: "Markers",
  13.             created_by: 504141,
  14.             created_at: 1509003163,
  15.             updated_at: 1509003163,
  16.             updated_by: 504141,
  17.             is_deleted: false,
  18.             custom_fields: [
  19.                {
  20.                   id: 4400049,
  21.                   name: "Vendor code",
  22.                   values: [
  23.                      {
  24.                         value: "416"
  25.                      }
  26.                   ],
  27.                   is_system: true
  28.                },
  29.                {
  30.                   id: 4400050,
  31.                   name: "Amount",
  32.                   values: [
  33.                      {
  34.                         value: "250"
  35.                      }
  36.                   ],
  37.                   is_system: true
  38.                },
  39.                {
  40.                   id: 4400051,
  41.                   name: "Price",
  42.                   values: [
  43.                      {
  44.                         value: "80"
  45.                      }
  46.                   ],
  47.                   is_system: true
  48.                },
  49.                {
  50.                   id: 4400062,
  51.                   name: "Multilist",
  52.                   values: [
  53.                      {
  54.                         value: "2",
  55.                         enum: "3692540"
  56.                      },
  57.                      {
  58.                         value: "3",
  59.                         enum: "3692541"
  60.                      }
  61.                   ],
  62.                   is_system: false
  63.                }
  64.             ],
  65.             catalog_id: 4220,
  66.             _links: {
  67.                self: {
  68.                   href: "/api/v2/catalog_elements?id=41873&catalog_id=4220",
  69.                   method: "get"
  70.                }
  71.             }
  72.          },
  73.          {
  74.             id: 41872,
  75.             name: "Pencils",
  76.             created_by: 504141,
  77.             created_at: 1509003145,
  78.             updated_at: 1509003145,
  79.             updated_by: 504141,
  80.             is_deleted: false,
  81.             custom_fields: [
  82.                {
  83.                   id: 4400049,
  84.                   name: "Vendor code",
  85.                   values: [
  86.                      {
  87.                         value: "415"
  88.                      }
  89.                   ],
  90.                   is_system: true
  91.                },
  92.                {
  93.                   id: 4400050,
  94.                   name: "Amount",
  95.                   values: [
  96.                      {
  97.                         value: "300"
  98.                      }
  99.                   ],
  100.                   is_system: true
  101.                },
  102.                {
  103.                   id: 4400051,
  104.                   name: "Price",
  105.                   values: [
  106.                      {
  107.                         value: "75"
  108.                      }
  109.                   ],
  110.                   is_system: true
  111.                },
  112.                {
  113.                   id: 4400062,
  114.                   name: "Multilist",
  115.                   values: [
  116.                      {
  117.                         value: "1",
  118.                         enum: "3692539"
  119.                      },
  120.                      {
  121.                         value: "2",
  122.                         enum: "3692540"
  123.                      }
  124.                   ],
  125.                   is_system: false
  126.                }
  127.             ],
  128.             catalog_id: 4220,
  129.             _links: {
  130.                self: {
  131.                   href: "/api/v2/catalog_elements?id=41872&catalog_id=4220",
  132.                   method: "get"
  133.                }
  134.             }
  135.          }
  136.       ]
  137.    }
  138. }
Example of integration
  1. /* First, we need to initialize the data needed to compose the query. */
  2. $subdomain='test'; #Our account is a subdomain
  3. #We form the reference for the query
  4. $link='https://'.$subdomain.'.amocrm.ru/api/v2/catalog_elements';
  5. /* Note that you can pass other parameters in the reference that affect the output (see
  6. documentation).
  7. СTherefore, we can replace the link given above with one of the following, or combine the parameters
  8. in the way that you want. */
  9. $link='https://'.$subdomain.'.amocrm.ru/api/v2/catalog_elements?catalog_id=2634';
  10. $link='https://'.$subdomain.'.amocrm.ru/api/v2/catalog_elements?catalog_id=2634&term=запрос';
  11. $link='https://'.$subdomain.'.amocrm.ru/api/v2/catalog_elements?catalog_id=2634&id=47856';
  12. /* We need to initiate a request to the server. We use the cURL library (supplied as part of PHP). More about
  13. work with this
  14. library you can read in the manual. */
  15. $curl=curl_init(); #We save the cURL session handle
  16. #Set the necessary options for the cURL session
  17. curl_setopt($curl,CURLOPT_RETURNTRANSFER,true);
  18. curl_setopt($curl,CURLOPT_USERAGENT,'amoCRM-API-client/1.0');
  19. curl_setopt($curl,CURLOPT_URL,$link);
  20. curl_setopt($curl,CURLOPT_HEADER,false);
  21. curl_setopt($curl,CURLOPT_COOKIEFILE,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
  22. curl_setopt($curl,CURLOPT_COOKIEJAR,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
  23. curl_setopt($curl,CURLOPT_SSL_VERIFYPEER,0);
  24. curl_setopt($curl,CURLOPT_SSL_VERIFYHOST,0);
  25. /* Выполняем запрос к серверу. */
  26. $out=curl_exec($curl); #Initiate a request to the API and save the response to a variable
  27. $code=curl_getinfo($curl,CURLINFO_HTTP_CODE);
  28. curl_close($curl);
  29. /* Now we can process the response received from the server. This is an example. You can process the data in your own way. */
  30. $code=(int)$code;
  31. $errors=array(
  32.   301=>'Moved permanently',
  33.   400=>'Bad request',
  34.   401=>'Unauthorized',
  35.   403=>'Forbidden',
  36.   404=>'Not found',
  37.   500=>'Internal server error',
  38.   502=>'Bad gateway',
  39.   503=>'Service unavailable'
  40. );
  41. try
  42. {
  43.   #If the response code is not 200 or 204, we return an error message
  44.  if($code!=200 && $code!=204)
  45.     throw new Exception(isset($errors[$code]) ? $errors[$code] : 'Undescribed error',$code);
  46. }
  47. catch(Exception $E)
  48. {
  49.   die('Error: '.$E->getMessage().PHP_EOL.'Error code: '.$E->getCode());
  50. }
  51. /*
  52.  The data is obtained in the JSON format, therefore, in order to obtain readable data,
  53.  We will have to translate the answer into a format that PHP understands
  54.  */
  55. $Response=json_decode($out,true);
  56. $Response=$Response['_embedded']['items'];