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

{
   add: [
      {
         name: "Products"
      }
   ]
}

Example of a request to update the list

Example

{
   update: [
      {
         id: "2456",
         name: "Products"
      }
   ]
}

Example of request to delete lists

Example

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

{
   _link: {
      self: {
         href: "/api/v2/catalogs",
         method: "post"
      }
   },
   _embedded: {
      items: [
         {
            id: 4223,
            _link: {
               self: {
                  href: "/api/v2/catalogs?id=4223",
                  method: "get"
               }
            }
         }
      ]
   }
}

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

$catalogs['add'] = array(
  array(
    'name'=>'Tariffs',
  ),
  array(
    'name'=>'Products',
  )
);
/* Now prepare the data needed to query the server */
$subdomain='test'; #Our account - subdomain
#We form the link for the query
$link='https://'.$subdomain.'.kommo.com/api/v2/catalogs';
/* 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
library you can read in the manual. */
$curl=curl_init(); #Save the Session Descriptor with URL
#Set the necessary options for the session withURL
curl_setopt($curl,CURLOPT_RETURNTRANSFER,true);
curl_setopt($curl,CURLOPT_USERAGENT,'amoCRM-API-client/1.0');
curl_setopt($curl,CURLOPT_URL,$link);
curl_setopt($curl,CURLOPT_CUSTOMREQUEST,'POST');
curl_setopt($curl,CURLOPT_POSTFIELDS,json_encode($catalogs));
curl_setopt($curl,CURLOPT_HTTPHEADER,array('Content-Type: application/json'));
curl_setopt($curl,CURLOPT_HEADER,false);
curl_setopt($curl,CURLOPT_COOKIEFILE,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
curl_setopt($curl,CURLOPT_COOKIEJAR,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
curl_setopt($curl,CURLOPT_SSL_VERIFYPEER,0);
curl_setopt($curl,CURLOPT_SSL_VERIFYHOST,0);
$out=curl_exec($curl); #Initiate a request to the API and save the response to a variable
$code=curl_getinfo($curl,CURLINFO_HTTP_CODE);
/* Now we can process the response received from the server. This is an example. You can process the data in your own way. */
$code=(int)$code;
$errors=array(
  301=>'Moved permanently',
  400=>'Bad request',
  401=>'Unauthorized',
  403=>'Forbidden',
  404=>'Not found',
  500=>'Internal server error',
  502=>'Bad gateway',
  503=>'Service unavailable'
);
try
{
  #If the response code is not 200 or 204, we return an error message
 if($code!=200 && $code!=204)
    throw new Exception(isset($errors[$code]) ? $errors[$code] : 'Undescribed error',$code);
}
catch(Exception $E)
{
  die('Error: '.$E->getMessage().PHP_EOL.'Error code: '.$E->getCode());
}
/*
 The data is obtained in the JSON format, therefore, in order to obtain readable data,
 We will have to translate the answer into a format that PHP understands
 */
$Response=json_decode($out,true);
$Response=$Response['_embedded']['items'];
$output='ID of added catalogs:'.PHP_EOL;
foreach($Response as $v)
  if(is_array($v))
    $output.=$v['id'].PHP_EOL;
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

$catalogs['update']=array(
  array(
    'id'=> 2561,
    'name'=>'Products',
  ),
  array(
    'id'=> 2562,
    'name'=>'Cars',
  )
);
/* Now prepare the data needed to query the server */
$subdomain='test'; #Our account - subdomain
#We form the reference for the query
$link='https://'.$subdomain.'.kommo.com/api/v2/catalogs';
/* 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
library you can read in the manual. */
$curl=curl_init(); #We save the cURL session handle
#Set the necessary options for the cURL session
curl_setopt($curl,CURLOPT_RETURNTRANSFER,true);
curl_setopt($curl,CURLOPT_USERAGENT,'amoCRM-API-client/1.0');
curl_setopt($curl,CURLOPT_URL,$link);
curl_setopt($curl,CURLOPT_CUSTOMREQUEST,'POST');
curl_setopt($curl,CURLOPT_POSTFIELDS,json_encode($catalogs));
curl_setopt($curl,CURLOPT_HTTPHEADER,array('Content-Type: application/json'));
curl_setopt($curl,CURLOPT_HEADER,false);
curl_setopt($curl,CURLOPT_COOKIEFILE,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
curl_setopt($curl,CURLOPT_COOKIEJAR,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
curl_setopt($curl,CURLOPT_SSL_VERIFYPEER,0);
curl_setopt($curl,CURLOPT_SSL_VERIFYHOST,0);
$out=curl_exec($curl); #Initiate a request to the API and save the response to a variable
$code=curl_getinfo($curl,CURLINFO_HTTP_CODE);
/* Now we can process the response received from the server. This is an example. You can process the data in your own way. */
$code=(int)$code;
$errors=array(
  301=>'Moved permanently',
  400=>'Bad request',
  401=>'Unauthorized',
  403=>'Forbidden',
  404=>'Not found',
  500=>'Internal server error',
  502=>'Bad gateway',
  503=>'Service unavailable'
);
try
{
  #If the response code is not 200 or 204, we return an error message
 if($code!=200 && $code!=204)
    throw new Exception(isset($errors[$code]) ? $errors[$code] : 'Undescribed error',$code);
}
catch(Exception $E)
{
  die('Error: '.$E->getMessage().PHP_EOL.'Error code: '.$E->getCode());
}

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 the 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

$catalogs['delete']=array(
  2561,
  2562
);
/* Now prepare the data needed to query the server */
$subdomain='test'; #Our account- subdomain
#We form the reference for the query
$link='https://'.$subdomain.'.kommo.com/api/v2/catalogs';
/* 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
library you can read in the manual. */
$curl=curl_init(); #We save the cURL session handle
#Set the necessary options for the cURL session
curl_setopt($curl,CURLOPT_RETURNTRANSFER,true);
curl_setopt($curl,CURLOPT_USERAGENT,'amoCRM-API-client/1.0');
curl_setopt($curl,CURLOPT_URL,$link);
curl_setopt($curl,CURLOPT_CUSTOMREQUEST,'POST');
curl_setopt($curl,CURLOPT_POSTFIELDS,json_encode($catalogs));
curl_setopt($curl,CURLOPT_HTTPHEADER,array('Content-Type: application/json'));
curl_setopt($curl,CURLOPT_HEADER,false);
curl_setopt($curl,CURLOPT_COOKIEFILE,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
curl_setopt($curl,CURLOPT_COOKIEJAR,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
curl_setopt($curl,CURLOPT_SSL_VERIFYPEER,0);
curl_setopt($curl,CURLOPT_SSL_VERIFYHOST,0);
$out=curl_exec($curl); #Initiate a request to the API and save the response to a variable
$code=curl_getinfo($curl,CURLINFO_HTTP_CODE);
/* Now we can process the response received from the server. This is an example. You can process the data in your own way. */
$code=(int)$code;
$errors=array(
  301=>'Moved permanently',
  400=>'Bad request',
  401=>'Unauthorized',
  403=>'Forbidden',
  404=>'Not found',
  500=>'Internal server error',
  502=>'Bad gateway',
  503=>'Service unavailable'
);
try
{
  #If the response code is not 200 or 204, we return an error message
 if($code!=200 && $code!=204)
    throw new Exception(isset($errors[$code]) ? $errors[$code] : 'Undescribed error',$code);
}
catch(Exception $E)
{
  die('Error: '.$E->getMessage().PHP_EOL.'Error code: '.$E->getCode());
}

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

{
   _links: {
      self: {
         href: "/api/v2/catalogs",
         method: "get"
      }
   },
   _embedded: {
      items: [
         {
            id: 4223,
            name: "Products",
            created_by: 504141,
            created_at: 1508930391,
            sort: 10,
            _links: {
               self: {
                  href: "/api/v2/catalogs?id=4223",
                  method: "get"
               }
            }
         },
         {
            id: 4222,
            name: "Sevices",
            created_by: 504141,
            created_at: 1508930288,
            sort: 20,
            _links: {
               self: {
                  href: "/api/v2/catalogs?id=4222",
                  method: "get"
               }
            }
         }
      ]
   }
}

Example of the request:

/* First, we need to initialize the data needed to compose the query. */
$subdomain='test'; #Our account is a subdomain
#We form the reference for the query
$link='https://'.$subdomain.'.kommo.com/api/v2/catalogs';
/* Note that you can pass other parameters in the reference that affect the output (see the documentation).
Therefore, we can replace the link given above with one of the following, or combine the parameters as you need. */
$link='https://'.$subdomain.'.kommo.com/api/v2/catalogs';
$link='https://'.$subdomain.'.kommo.com/api/v2/catalogs?id=2634';
/* 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
library you can read in the manual. */
$curl=curl_init(); #We save the cURL session handle
#Set the necessary options for the cURL session
curl_setopt($curl,CURLOPT_RETURNTRANSFER,true);
curl_setopt($curl,CURLOPT_USERAGENT,'amoCRM-API-client/1.0');
curl_setopt($curl,CURLOPT_URL,$link);
curl_setopt($curl,CURLOPT_HEADER,false);
curl_setopt($curl,CURLOPT_COOKIEFILE,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
curl_setopt($curl,CURLOPT_COOKIEJAR,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
curl_setopt($curl,CURLOPT_SSL_VERIFYPEER,0);
curl_setopt($curl,CURLOPT_SSL_VERIFYHOST,0);
Выполняем запрос к серверу.
$out=curl_exec($curl); #Initiate a request to the API and save the response to a variable
$code=curl_getinfo($curl,CURLINFO_HTTP_CODE);
curl_close($curl);
/* Now we can process the response received from the server. This is an example. You can process the data in your own way. */
$code=(int)$code;
$errors=array(
  301=>'Moved permanently',
  400=>'Bad request',
  401=>'Unauthorized',
  403=>'Forbidden',
  404=>'Not found',
  500=>'Internal server error',
  502=>'Bad gateway',
  503=>'Service unavailable'
);
try
{
  #If the response code is not 200 or 204, we return an error message
 if($code!=200 && $code!=204)
    throw new Exception(isset($errors[$code]) ? $errors[$code] : 'Undescribed error',$code);
}
catch(Exception $E)
{
  die('Error: '.$E->getMessage().PHP_EOL.'Error code: '.$E->getCode());
}
/*
 The data is obtained in the JSON format, therefore, in order to obtain readable data,
 We will have to translate the answer into a format that PHP understands
 */
$Response=json_decode($out,true);
$Response=$Response['_embedded']['items'];