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)
]
]
],
],
],
];