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
{
add: [
{
catalog_id: "4220",
name: "Pencil",
custom_fields: [
{
id: "4400050",
values: [
{
value: "100"
}
]
},
{
id: "4400062",
values: [
"3692539",
"3692540"
]
}
]
}
]
}
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
{
_link: {
self: {
href: "/api/v2/catalog_elements",
method: "post"
}
},
_embedded: {
items: [
{
id: 41870,
request_id: 0,
_link: {
self: {
href: "/api/v2/catalog_elements?id=41870",
method: "get"
}
}
}
]
}
}
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
$catalog_elements['add'] = array(
array(
'catalog_id'=>2534,
'name'=>'Black iPhone',
),
array(
'catalog_id'=>2534,
'name'=>'Really Black iPhone',
)
);
/* Now prepare the data needed to query the server */
$subdomain='test'; #Our account is a subdomain
#We form the reference for the query
$link='https://'.$subdomain.'.kommo.com/api/v2/catalog_elements';
/* We need to initiate a request to the server. We use the cURL library (supplied as part of PHP). More about
work 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());
}
/*
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 list items:'.PHP_EOL;
foreach($Response as $v)
if(is_array($v))
$output.=$v['id'].PHP_EOL;
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
$catalog_elements['update']=array(
array(
'catalog_id'=>2534,
'id'=> 35431,
'name'=>'Explosive Galaxy Note 7',
),
array(
'catalog_id'=>2534,
'id'=> 35431,
'name'=>'MacBook Pro 2016',
)
);
/* Now prepare the data needed to query the server */
$subdomain='test'; #Our account is a subdomain
#We form the reference for the query
$link='https://'.$subdomain.'.kommo.com/api/v2/catalog_elements';
We need to initiate a request to the server. We use the cURL library (supplied as part of PHP). More about
work 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($catalog_elements));
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 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 the 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
$catalog_elements['delete']=array(
35159,
35164
);
/* Now prepare the data needed to query the server */
$subdomain='test'; #Our account is a subdomain
#We form the reference for the query
$link='https://'.$subdomain.'.kommo.com/api/v2/catalog_elements';
/* We need to initiate a request to the server. We use the cURL library (supplied as part of PHP). More about
work 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($catalog_elements));
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 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
{
_links: {
self: {
href: "/api/v2/catalog_elements?catalog_id=4220",
method: "get"
}
},
_embedded: {
items: [
{
id: 41873,
name: "Markers",
created_by: 504141,
created_at: 1509003163,
updated_at: 1509003163,
updated_by: 504141,
is_deleted: false,
custom_fields: [
{
id: 4400049,
name: "Vendor code",
values: [
{
value: "416"
}
],
is_system: true
},
{
id: 4400050,
name: "Amount",
values: [
{
value: "250"
}
],
is_system: true
},
{
id: 4400051,
name: "Price",
values: [
{
value: "80"
}
],
is_system: true
},
{
id: 4400062,
name: "Multilist",
values: [
{
value: "2",
enum: "3692540"
},
{
value: "3",
enum: "3692541"
}
],
is_system: false
}
],
catalog_id: 4220,
_links: {
self: {
href: "/api/v2/catalog_elements?id=41873&catalog_id=4220",
method: "get"
}
}
},
{
id: 41872,
name: "Pencils",
created_by: 504141,
created_at: 1509003145,
updated_at: 1509003145,
updated_by: 504141,
is_deleted: false,
custom_fields: [
{
id: 4400049,
name: "Vendor code",
values: [
{
value: "415"
}
],
is_system: true
},
{
id: 4400050,
name: "Amount",
values: [
{
value: "300"
}
],
is_system: true
},
{
id: 4400051,
name: "Price",
values: [
{
value: "75"
}
],
is_system: true
},
{
id: 4400062,
name: "Multilist",
values: [
{
value: "1",
enum: "3692539"
},
{
value: "2",
enum: "3692540"
}
],
is_system: false
}
],
catalog_id: 4220,
_links: {
self: {
href: "/api/v2/catalog_elements?id=41872&catalog_id=4220",
method: "get"
}
}
}
]
}
}
Example of integration
/* 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/catalog_elements';
/* Note that you can pass other parameters in the reference that affect the output (see
documentation).
СTherefore, we can replace the link given above with one of the following, or combine the parameters
in the way that you want. */
$link='https://'.$subdomain.'.kommo.com/api/v2/catalog_elements?catalog_id=2634';
$link='https://'.$subdomain.'.kommo.com/api/v2/catalog_elements?catalog_id=2634&term=request';
$link='https://'.$subdomain.'.kommo.com/api/v2/catalog_elements?catalog_id=2634&id=47856';
/* We need to initiate a request to the server. We use the cURL library (supplied as part of PHP). More about
work 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'];