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

{
      add: [
         {
            name: "Select colors",
            field_type: "5",
            element_type: "2",
            origin: "528d0285c1f9180911159a9dc6f759b3_zendesk_widget",
            is_editable: "0",
            enums: [
               "black",
               "white",
               "red",
               "yellow",
               "blue",
               "green"
            ]
         }
      ]
   }

Request to delete an Custom fields.

Example response

{
   delete: [
      {
         id: "441506",
         origin: "528d0285c1f9180911159a9dc6f759b3_zendesk_widget"
      }
   ]
}

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

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

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.

$fields['add'] = array(
   array(
      'name' => "Selecting Colors",
      'field_type'=> 5,
      'element_type' => 2,
      'origin' => "528d0285c1f9180911159a9dc6f759b3_zendesk_widget",
      'is_editable' => 0,
      'enums' => array(
         "black",
         "white",
         "red",
         "yellow",
         "blue",
         "green"
      )
   )
)
);
/* Now prepare the data needed to query the server */
$subdomain='test'; #Our account is a subdomain
#Generate a link for the request
$link='https://'.$subdomain.'.amocrm.com/api/v2/fields';
/* 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(); #Save the cURL session descriptor
#Set the necessary parameters 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($fields));
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,
 e will have to translate the response into a format that PHP understands
 */
$Response=json_decode($out,true);
$Response=$Response[_embedded']['items'];
$output='The ID of the added fields:'.PHP_EOL;
foreach($Response as $v)
 if(is_array($v))
   $output.=$v['id'].PHP_EOL;
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

$leads['add'] = array(
    array(
        'name'=>'Test_Lead',
        //'date_create'=>123456789, //creation date
        'status_id'=>142,       //Status of the lead
        'sale'=>1000,        //Sale
        'responsible_user_id'=>215302,
        'tags' => 'test, fields',  //tags
        "custom_fields"=>[
            [
            "id"=>6223784,     //id of the field
            "values"=> [
                [
                    "value"=>"791112345" //Field of type text
                ]
 
              ]
            ],
            [
            "id"=>644732,           //id of the field
            "values"=> [
                [
                    "value"=>1519210  //A list type field, the value of the enum parameter takes the value
                ]
              ]
            ],
            [
                "id"=>666558,   //id of the field
                "values"=> [
                    [
                        "value"=>"TEXT" //Type field text
                    ]
                ]
            ],
            [
                "id"=>691604,   //id of the field
                "values"=> [
                    [
                        "value"=>1  //Field type checkbox, valid values ​​0 or 1
                    ]
                ]
            ],
            [
                "id"=>691606,       //id of the field
                "values"=> [
                    [
                        "value"=>"1999/10/21"   //Date field, field value in the form YYYY / MM / DD
                    ]
                ]
            ],
            [
                "id"=>692250,       //id of the field
                "values"=> [1662884,1662886]    //A field of the multisession type (it can take an array of values)
            ],
            [
                "id"=>692257,       //id of the field
                "values"=> [ //A field of the type of a legal entity (it can take an array of values)
                    [
                        "value"=> [ //The field takes an array of values
                            "name" => "ООО 'Ecoworld'", // Company name. Required parameter for filling
                            "entity_type" => 2, // Type of legal entity: 1 - IE, 2 - Legal entity.
                            "vat_id" => 5009051111, // INN
                            "kpp" => 500901001, // CAT
                            "address" => "20011, Madison st. 2, NY", // Address
                            "external_id" => "46b44a52-2a14-458f-92dd-280a3c6af8c8", // Uuid
                        ]
                    ]
                ]    
            ],
        ]
    )
);
 
$catalog_element["add"] = [
    [
        "name" => "00AM-000034",
        "catalog_id" => 4966,
        "custom_fields" => [
            [
            "id" => 4411241, // id of the field
            "values"=> [ // A field of the type of list composition (can take an array of values)
                [
                    "description" => "Coffee", // Name of goods
                    "unit_price" => 1500, // Unit price
                    "unit_type" => "piece", // Unit of measure
                    "quantity" => 10, // Quantity of goods
                    "discount" => [ // Discount
                        "type" => "amount", // Discount type: amount - quantitative, percentage - percentage
                        "value" => 100, // Discount amount
                    ],
                    "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
                    "external_uid" => '7466efa8-3671-11e8-318c-0050568904f0', // Uuid of the goods (parameteral parameter)
                ]
              ]
            ],
        ],
    ],
];