Custom fields

A method that allows you to create and delete Custom fieldss one by one or one by one. The user will not be able to change their values ​​from the interface, but will be able to filter on them and view them. Creating and deleting a field is also possible from the interface.


Creating and deleting custom fields

Method URL

POST / api / v2 / fields

Parameters
Parameter Type Description
add array The list of fields to add
delete array List of fields to delete
add/name
require
string Field name
add/field_type int Field type
add/element_type int Entity type
add/origin
require
string The unique identifier of the service, which will be available for deleting and changing the field
add/is_editable bool
add/enums array(string) An array of values ​​for a list or multisession. Values ​​are indicated by string variables, separated by commas.
add/request_id int The unique identifier of the entry in the client program (parameteral parameter). Information about request_id is not saved anywhere.
add/is_required bool Required field
This property is only applicable to list fields
add/is_deletable bool The ability to delete a field in the interface
This property is only applicable to list fields
add/is_visible bool Field visibility in the interface
This property is only applicable to list fields
delete/id
require
int A unique identifier for the field that is to be deleted
delete/origin
require
string The unique identifier of the service on which the removal and modification of the field will be available
Entity Type
Parameter Description
1 Contact
2 Lead
3 Company
12 Customer
Field Type
Parameter Code Description
1 TEXT Common text field
2 NUMERIC Text field with the ability to transmit only digits
3 CHECKBOX A field indicating only the presence or absence of a property (for example: "yes" / "no")
4 SELECT A list type field with the ability to select one element
5 MULTISELECT A list type field with the ability to select multiple list items
6 DATE The date field returns and takes values ​​in the format (Y-m-d H: i: s)
7 URL A common text field for entering URLs
8 MULTITEXT The textarea field containing a large amount of text
9 TEXTAREA The textarea field containing a large amount of text
10 RADIOBUTTON Switch type field
11 STREETADDRESS Short address field
13 SMART_ADDRESS The address field (in the interface is a set of several fields)
14 BIRTHDAY The field of the date search type is carried out without taking into account the year, the values ​​in the format (Y-m-d H: i: s)
15 legal_entity The field is a legal entity (in the interface it is a set of several fields)
16 ITEMS Field of the catalog (the field is only available in user lists)

Request for adding new custom fields

Example response
  1. {
  2.       add: [
  3.          {
  4.             name: "Select colors",
  5.             field_type: "5",
  6.             element_type: "2",
  7.             origin: "528d0285c1f9180911159a9dc6f759b3_zendesk_widget",
  8.             is_editable: "0",
  9.             enums: [
  10.                "black",
  11.                "white",
  12.                "red",
  13.                "yellow",
  14.                "blue",
  15.                "green"
  16.             ]
  17.          }
  18.       ]
  19.    }

Request to delete an Custom fields.

Example response
  1. {
  2.    delete: [
  3.       {
  4.          id: "441506",
  5.          origin: "528d0285c1f9180911159a9dc6f759b3_zendesk_widget"
  6.       }
  7.    ]
  8. }
Response parameters
Parameter Description
id The unique identifier of the new entity
request_id The unique identifier of the entity in the client program, if request_id is not passed in the request, it is automatically generated
_links Array containing information about the request
_links/self An array containing information about the current request
_links/self/href Relative URL of the current request
_links/self/method The method of the current request
_embedded An array containing information adjacent to the query
_embedded/items An array containing information for each individual element

Response Headers contains the following headers:

  • Content-Type: application / hal + json

  • Runtime-Timestamp: 1508320306

Example response
  1. {
  2.    _link: {
  3.       self: {
  4.          href: "/api/v2/fields",
  5.          method: "post"
  6.       }
  7.    },
  8.    _embedded: {
  9.       items: [
  10.          {
  11.             id: 4400161,
  12.             _link: {
  13.                self: {
  14.                   href: "/api/v2/fields?id=4400161",
  15.                   method: "get"
  16.                }
  17.             }
  18.          }
  19.       ]
  20.    }
  21. }
Example integration

To add an Custom fields, you need to describe an array containing information about the Custom fields and put it into an array of the following form: $ fields ['add']. Our API also supports the simultaneous addition of several fields at once. To do this, we put several arrays in the $ fields ['add'] array, each of which describes the necessary data to add the corresponding custom field.

  1. $fields['add'] = array(
  2.    array(
  3.       'name' => "Selecting Colors",
  4.       'field_type'=> 5,
  5.       'element_type' => 2,
  6.       'origin' => "528d0285c1f9180911159a9dc6f759b3_zendesk_widget",
  7.       'is_editable' => 0,
  8.       'enums' => array(
  9.          "black",
  10.          "white",
  11.          "red",
  12.          "yellow",
  13.          "blue",
  14.          "green"
  15.       )
  16.    )
  17. )
  18. );
  19. /* Now prepare the data needed to query the server */
  20. $subdomain='test'; #Our account is a subdomain
  21. #Generate a link for the request
  22. $link='https://'.$subdomain.'.amocrm.com/api/v2/fields';
  23. /* We need to initiate a request to the server. We use the cURL library (supplied as part of PHP). More about
  24. work with this
  25. library you can read in the manual. */
  26. $curl=curl_init(); #Save the cURL session descriptor
  27. #Set the necessary parameters for the cURL session
  28. curl_setopt($curl,CURLOPT_RETURNTRANSFER,true);
  29. curl_setopt($curl,CURLOPT_USERAGENT,'amoCRM-API-client/1.0');
  30. curl_setopt($curl,CURLOPT_URL,$link);
  31. curl_setopt($curl,CURLOPT_CUSTOMREQUEST,'POST');
  32. curl_setopt($curl,CURLOPT_POSTFIELDS,json_encode($fields));
  33. curl_setopt($curl,CURLOPT_HTTPHEADER,array('Content-Type: application/json'));
  34. curl_setopt($curl,CURLOPT_HEADER,false);
  35. curl_setopt($curl,CURLOPT_COOKIEFILE,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
  36. curl_setopt($curl,CURLOPT_COOKIEJAR,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
  37. curl_setopt($curl,CURLOPT_SSL_VERIFYPEER,0);
  38. curl_setopt($curl,CURLOPT_SSL_VERIFYHOST,0);
  39. $out=curl_exec($curl); #Initiate a request to the API and save the response to a variable
  40. $code=curl_getinfo($curl,CURLINFO_HTTP_CODE);
  41. /* Now we can process the response received from the server. This is an example. You can process the data in your own way. */
  42. $code=(int)$code;
  43. $errors=array(
  44.   301=>'Moved permanently',
  45.   400=>'Bad request',
  46.   401=>'Unauthorized',
  47.   403=>'Forbidden',
  48.   404=>'Not found',
  49.   500=>'Internal server error',
  50.   502=>'Bad gateway',
  51.   503=>'Service unavailable'
  52. );
  53. try
  54. {
  55.   #If the response code is not 200 or 204, we return an error message
  56.  if($code!=200 && $code!=204)
  57.     throw new Exception(isset($errors[$code]) ? $errors[$code] : 'Undescribed error',$code);
  58. }
  59. catch(Exception $E)
  60. {
  61.   die('Error: '.$E->getMessage().PHP_EOL.'Error code: '.$E->getCode());
  62. }
  63. /*
  64.  The data is obtained in the JSON format, therefore, in order to obtain readable data,
  65.  e will have to translate the response into a format that PHP understands
  66.  */
  67. $Response=json_decode($out,true);
  68. $Response=$Response[_embedded']['items'];
  69. $output='The ID of the added fields:'.PHP_EOL;
  70. foreach($Response as $v)
  71.  if(is_array($v))
  72.    $output.=$v['id'].PHP_EOL;
  73. return $output;

The values ​​of Custom fields

In this section, you will learn how to correctly fill in the values ​​of Custom fieldss, depending on their type.

  • Before working with Custom fieldss, you need to know the id and the field type using the account method.

  • Pay attention to the nesting of arrays.

  • The value of "enum" is written to enum's id, not its value.

  • When using standard fields, you can write down the value of this enum, for example: 'WORK', 'SKYPE'.

Parameters
Parameter Type Description
id
require
int id of the Custom fields
values
require
array An array of extra field values
value
require
int/string Field Value
enum int/string The value of the field entity

An example of adding Custom fields values, for example, by creating a new entity element, "Lead". The structure of the part of the query code that is responsible for the values ​​of the Custom fieldss will be the same for all other entities.

Example integration
  1. $leads['add'] = array(
  2.     array(
  3.         'name'=>'Test_Lead',
  4.         //'date_create'=>123456789, //creation date
  5.         'status_id'=>142,       //Status of the lead
  6.         'sale'=>1000,        //Sale
  7.         'responsible_user_id'=>215302,
  8.         'tags' => 'test, fields',  //tags
  9.         "custom_fields"=>[
  10.             [
  11.             "id"=>6223784,     //id of the field
  12.             "values"=> [
  13.                 [
  14.                     "value"=>"791112345" //Field of type text
  15.                 ]
  16.  
  17.               ]
  18.             ],
  19.             [
  20.             "id"=>644732,           //id of the field
  21.             "values"=> [
  22.                 [
  23.                     "value"=>1519210  //A list type field, the value of the enum parameter takes the value
  24.                 ]
  25.               ]
  26.             ],
  27.             [
  28.                 "id"=>666558,   //id of the field
  29.                 "values"=> [
  30.                     [
  31.                         "value"=>"TEXT" //Type field text
  32.                     ]
  33.                 ]
  34.             ],
  35.             [
  36.                 "id"=>691604,   //id of the field
  37.                 "values"=> [
  38.                     [
  39.                         "value"=>1  //Field type checkbox, valid values ​​0 or 1
  40.                     ]
  41.                 ]
  42.             ],
  43.             [
  44.                 "id"=>691606,       //id of the field
  45.                 "values"=> [
  46.                     [
  47.                         "value"=>"1999/10/21"   //Date field, field value in the form YYYY / MM / DD
  48.                     ]
  49.                 ]
  50.             ],
  51.             [
  52.                 "id"=>692250,       //id of the field
  53.                 "values"=> [1662884,1662886]    //A field of the multisession type (it can take an array of values)
  54.             ],
  55.             [
  56.                 "id"=>692257,       //id of the field
  57.                 "values"=> [ //A field of the type of a legal entity (it can take an array of values)
  58.                     [
  59.                         "value"=> [ //The field takes an array of values
  60.                             "name" => "ООО 'Ecoworld'", // Company name. Required parameter for filling
  61.                             "entity_type" => 2, // Type of legal entity: 1 - IE, 2 - Legal entity.
  62.                             "vat_id" => 5009051111, // INN
  63.                             "kpp" => 500901001, // CAT
  64.                             "address" => "20011, Madison st. 2, NY", // Address
  65.                             "external_id" => "46b44a52-2a14-458f-92dd-280a3c6af8c8", // Uuid
  66.                         ]
  67.                     ]
  68.                 ]    
  69.             ],
  70.         ]
  71.     )
  72. );
  73.  
  74. $catalog_element["add"] = [
  75.     [
  76.         "name" => "00AM-000034",
  77.         "catalog_id" => 4966,
  78.         "custom_fields" => [
  79.             [
  80.             "id" => 4411241, // id of the field
  81.             "values"=> [ // A field of the type of list composition (can take an array of values)
  82.                 [
  83.                     "description" => "Coffee", // Name of goods
  84.                     "unit_price" => 1500, // Unit price
  85.                     "unit_type" => "piece", // Unit of measure
  86.                     "quantity" => 10, // Quantity of goods
  87.                     "discount" => [ // Discount
  88.                         "type" => "amount", // Discount type: amount - quantitative, percentage - percentage
  89.                         "value" => 100, // Discount amount
  90.                     ],
  91.                     "vat_rate_id" => 3, // ID of the VAT amount. The list of possible values ​​can be obtained by using the / api / v2 / account? With = custom_fields method after creating the field
  92.                     "external_uid" => '7466efa8-3671-11e8-318c-0050568904f0', // Uuid of the goods (parameteral parameter)
  93.                 ]
  94.               ]
  95.             ],
  96.         ],
  97.     ],
  98. ];