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

{
   delete: [
      {
         2456,
         2472,
         2483
      }
   ]
}

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'];