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.'.amocrm.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.'.amocrm.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 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.'.amocrm.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.'.amocrm.ru/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.'.amocrm.ru/api/v2/catalog_elements?catalog_id=2634';
$link='https://'.$subdomain.'.amocrm.ru/api/v2/catalog_elements?catalog_id=2634&term=запрос';
$link='https://'.$subdomain.'.amocrm.ru/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'];