Lists

Adding, updating, and deleting lists

These methods are only available to users who have permission to access the lists. Methods allow you to add lists one by one or in batches, and also update data on existing lists and delete them.

Method URL

POST / api / v2 / catalogs

Parameters
Parameter Type Description
add array List of added lists
update array Updating existing lists
All the parameters that are described in add also work in the update
delete array List of lists to remove
add/name
require
string List Name
add/type string List type
"regular" - list, "invoices" - accounts
add/can_add_elements bool Adding an account from the interface
add/can_show_in_cards bool Possibility to add a tab with a list to the leads / customer card
add/can_link_multiple bool The ability to tie one element of this list to several leads / customers
add/request_id int Unique identifier of a record in the client program, optional parameter (information about request_id is not saved anywhere)
update/id
require
int The unique identifier of the list, which is indicated for the purpose of updating it
delete
require
array An array with unique list identifiers that are specified for deletion purposes

Example of request to add a list

Example
  1. {
  2.    add: [
  3.       {
  4.          name: "Products"
  5.       }
  6.    ]
  7. }

Example of a request to update the list

Example
  1. {
  2.    update: [
  3.       {
  4.          id: "2456",
  5.          name: "Products"
  6.       }
  7.    ]
  8. }

Example of request to delete lists

Example
  1. {
  2.    delete: [
  3.       {
  4.          2456,
  5.          2472,
  6.          2483
  7.       }
  8.    ]
  9. }
Response parameters
Parameter Description
id Unique identifier for the new entity
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/catalogs",
  5.          method: "post"
  6.       }
  7.    },
  8.    _embedded: {
  9.       items: [
  10.          {
  11.             id: 4223,
  12.             _link: {
  13.                self: {
  14.                   href: "/api/v2/catalogs?id=4223",
  15.                   method: "get"
  16.                }
  17.             }
  18.          }
  19.       ]
  20.    }
  21. }
Adding Lists

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

Our API also supports the simultaneous addition of multiple lists at once. To do this, we put several arrays into the array $catalogs['add'], each of which describes the necessary data to create the corresponding list.

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

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

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

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

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

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

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

List of Lists

Method for obtaining a list of account lists.

Method URL

GET / api / v2 / catalogs

GET parameters
Parameter Description
id Select item with given ID
Response parameters
Parameter Type Description
id int Unique list id
name string List Name
created_by int ID of the user who created the list
created_at timestamp Date of creation
sort int The parameter indicates where the list will be located
_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/catalogs",
  5.          method: "get"
  6.       }
  7.    },
  8.    _embedded: {
  9.       items: [
  10.          {
  11.             id: 4223,
  12.             name: "Products",
  13.             created_by: 504141,
  14.             created_at: 1508930391,
  15.             sort: 10,
  16.             _links: {
  17.                self: {
  18.                   href: "/api/v2/catalogs?id=4223",
  19.                   method: "get"
  20.                }
  21.             }
  22.          },
  23.          {
  24.             id: 4222,
  25.             name: "Sevices",
  26.             created_by: 504141,
  27.             created_at: 1508930288,
  28.             sort: 20,
  29.             _links: {
  30.                self: {
  31.                   href: "/api/v2/catalogs?id=4222",
  32.                   method: "get"
  33.                }
  34.             }
  35.          }
  36.       ]
  37.    }
  38. }
Example of the request:
  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.com/api/v2/catalogs';
  5. /* Note that you can pass other parameters in the reference that affect the output (see the documentation).
  6. Therefore, we can replace the link given above with one of the following, or combine the parameters as you need. */
  7. $link='https://'.$subdomain.'.amocrm.com/api/v2/catalogs';
  8. $link='https://'.$subdomain.'.amocrm.com/api/v2/catalogs?id=2634';
  9. /* We need to initiate a request to the server. We use the cURL library (supplied as part of PHP). Learn more about working with this
  10. library you can read in the manual. */
  11. $curl=curl_init(); #We save the cURL session handle
  12. #Set the necessary options for the cURL session
  13. curl_setopt($curl,CURLOPT_RETURNTRANSFER,true);
  14. curl_setopt($curl,CURLOPT_USERAGENT,'amoCRM-API-client/1.0');
  15. curl_setopt($curl,CURLOPT_URL,$link);
  16. curl_setopt($curl,CURLOPT_HEADER,false);
  17. curl_setopt($curl,CURLOPT_COOKIEFILE,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
  18. curl_setopt($curl,CURLOPT_COOKIEJAR,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
  19. curl_setopt($curl,CURLOPT_SSL_VERIFYPEER,0);
  20. curl_setopt($curl,CURLOPT_SSL_VERIFYHOST,0);
  21. Выполняем запрос к серверу.
  22. $out=curl_exec($curl); #Initiate a request to the API and save the response to a variable
  23. $code=curl_getinfo($curl,CURLINFO_HTTP_CODE);
  24. curl_close($curl);
  25. /* Now we can process the response received from the server. This is an example. You can process the data in your own way. */
  26. $code=(int)$code;
  27. $errors=array(
  28.   301=>'Moved permanently',
  29.   400=>'Bad request',
  30.   401=>'Unauthorized',
  31.   403=>'Forbidden',
  32.   404=>'Not found',
  33.   500=>'Internal server error',
  34.   502=>'Bad gateway',
  35.   503=>'Service unavailable'
  36. );
  37. try
  38. {
  39.   #If the response code is not 200 or 204, we return an error message
  40.  if($code!=200 && $code!=204)
  41.     throw new Exception(isset($errors[$code]) ? $errors[$code] : 'Undescribed error',$code);
  42. }
  43. catch(Exception $E)
  44. {
  45.   die('Error: '.$E->getMessage().PHP_EOL.'Error code: '.$E->getCode());
  46. }
  47. /*
  48.  The data is obtained in the JSON format, therefore, in order to obtain readable data,
  49.  We will have to translate the answer into a format that PHP understands
  50.  */
  51. $Response=json_decode($out,true);
  52. $Response=$Response['_embedded']['items'];