Common information

Custom fields can be added to leads, contacts, companies, and lists
Method URL depends on the entity

Available field types

Type	Name
text	Text
numeric	Number
checkbox	Checkbox
select	List
multiselect	Multiselect list
date	Date
url	URL
textarea	Text area
radiobutton	Switch
streetaddress	Short address
smart_address	Address
birthday	Birthday
legal_entity	Tax ID
date_time	Date and time
price	Price
category	Category
file	File
chained_list	Catalogs and lists
tracking_data	Tracking data
linked_entity	Linking to another element
monetary	Monetary

Field types availability for entities

Field type	Contact	Lead	Company	List
Text	✅	✅	✅	✅
Number	✅	✅	✅	✅
Checkbox	✅	✅	✅	✅
List	✅	✅	✅	✅
Multiselect list	✅	✅	✅	✅
Multitext	✅	❌	❌	❌
Date	✅	✅	✅	✅
URL	✅	✅	✅	✅
Date and time	✅	✅	✅	✅
Text area	✅	✅	✅	✅
Switch	✅	✅	✅	✅
Short address	✅	✅	✅	✅
Address	✅	✅	✅	❌
Birthday	✅	✅	✅	❌
Tax ID	✅	✅	✅	❌
Price	❌	❌	❌	✅
Category	❌	❌	❌	✅
Products	❌	❌	❌	✅
File	✅	✅	✅	✅
Monetary	✅	✅	✅	✅
Linked entity	❌	❌	❌	✅
Chained list	❌	✅	❌	❌

Examples of filling in different types of fields via API

Below we will consider examples of requests for filling values of different types of fields.

Regardless of the field type, all values are passed in the custom_fields_values array objects. To fill a field, you need to pass its ID or character code, as well as the values themselves.

Parameter	Data type	Description
custom_fields_values	array	An array containing information on the values of additional fields defined for the entity
custom_fields_values[0]	object	An object containing information on the value of the optional field set for the entity
custom_fields_values[field_id]	int	ID of the field whose value you are filling
custom_fields_values[field_code]	string	The character code of the field whose value you are filling (you must pass either field_id or field_code to fill it)
custom_fields_values[values]	array	Array of fillable values
custom_fields_values[values][0]	object	Object of the field value. The structure of the object depends on the field type

Fields type:

text, numeric, textarea, price, streetaddress, tracking_data, monetary

In this example, consider a query to fill fields of type text, numeric, textarea, price, streetaddress, tracking_data, monetary.

Parameter	Data type	Description
value	string	Field value

...
"custom_fields_values": [
    {
        "field_id": 3,
        "values": [
            {
                "value": "Field value"
            }
        ]
    },
    {
        "field_id": 103,
        "values": [
            {
                "value": "1.5"
            }
        ]
    },
    {
        "field_id": 203,
        "values": [
            {
                "value": "string1\nstring2"
            }
        ]
    },
    {
        "field_id": 303,
        "values": [
            {
                "value": "100"
            }
        ]
    },
    {
        "field_id": 403,
        "values": [
            {
                "value": "940 Mission Rd South San Francisco, California(CA), 94080, "
            }
        ]
    }
],
...

checkbox

In this example, let's consider a request to fill fields of the checkboxtype.

Parameter	Data Type	Description
value	bool	Field value

...
"custom_fields_values": [
    {
        "field_id": 5,
        "values": [
            {
                "value": true
            }
        ]
    }
],
...

url

In this example, let's look at a query to populate fields of type url.

Parameter	Data type	Description
value	string	Field Value. Delegated URL

...
"custom_fields_values": [
    {
        "field_id": 7,
        "values": [
            {
                "value": "https://www.kommo.com/"
            }
        ]
    }
],
...

date, date_time, birthday

In this example, consider a query to populate fields of type date, date_time, birthday.

Parameter	Data type	Description
value	int\|string	Field value - Unix Timestamp or time stamp in RFC-3339 format

...
"custom_fields_values": [
    {
        "field_id": 9,
        "values": [
            {
                "value": 1577836800
            }
        ]
    },
    {
        "field_id": 109,
        "values": [
            {
                "value": 1591965296
            }
        ]
    },
    {
        "field_id": 209,
        "values": [
            {
                "value": 1586476800
            }
        ]
    }
],
...

select, multiselect, radiobutton, category

In this example, consider a query to fill fields like select, multiselect, radiobutton, category. A value can be passed as a value, either a character code of the value or the ID of the value.

Parameter	Data type	Description
value	string	Field value
enum_id	int	Field value ID (enum)
enum code	string	Field value symbolic code (enum)

...
"custom_fields_values": [
    {
        "field_id": 11,
        "values": [
            {
                "value": "value 1"
            }
        ]
    },
    {
        "field_id": 111,
        "values": [
            {
                "enum_id": 17
            },
            {
                "enum_id": 19
            }
        ]
    },
    {
        "field_id": 211,
        "values": [
            {
                "value": "value 4"
            }
        ]
    }
],
...

smart_address

In this example, consider a query to populate fields of type smart_address. The field accepts multiple values. The value and enum_idor enum_codefields must be passed in the value.

Parameter	Data type	Description
value	string	Field value
enum_id	int	Field value. Available values: 1 - First line of address, 2 - Second line of address, 3 - City, 4 - Region, 5 - Postal code, 6 - Country
enum_code	string	Field value code. Available values: address_line_1 - First line of address, address_line_2 - Second line of address, city - City, state - Region, zip - Postal code, country - Country

...
"custom_fields_values": [
    {
        "field_id": 13,
        "values": [
            {
                "value": "940 Mission Rd",
                "enum_id": 1
            },
            {
                "value": "San Francisco",
                "enum_code": "city"
            },
            {
                "value": "California",
                "enum_code": "state"
            },
            {
                "value": "94080",
                "enum_id": 5
            },
            {
                "value": "US",
                "enum_code": "country"
            }
        ]
    }
],
...

multitext

In this example, let's consider a request to fill fields of multitext type (Phone, Email). The field accepts multiple values. The value and enum_idor enum_codefields must be passed in the value.

Parameter	Data type	Description
value	string	Field value
enum_id	int	Field value ID
enum_code	string	Field Value Code. Available values for the Phone field are WORK - work, WORKDD - work direct, MOB - mobile, FAX - fax, HOME - home, OTHER - other. Available values for the Email field are WORK - work, PRIV - personal, OTHER - other.

...
"custom_fields_values": [
    {
        "field_id": 31,
        "values": [
            {
                "value": "+18001111111",
                "enum_id": 48224
            },
            {
                "value": "+18002222222",
                "enum_code": "HOME"
            }
        ]
    }
],
...

legal_entity

In this example, let's consider a query to fill fields of type legal_entity. It is obligatory to pass the name field in the value.

Parameter	Data type	Description
value	string	Field value
value[name]	string	Organization name
value[entity_type]	int	Legal entity type. 1 - Private, 2 - Legal
value[address]	string	Organization address
value[real_address]	string	Organization real address
value[bank_account_number]	int	Bank account number
value[director]	string	SEO name
value[vat_id]	int	Organization TIN number (or your country equivalent)
value[tax_registration_reason_code]	string	Tax registration reason code
value[bank_code]	string	Bank code
value[external_uid]	string	External system ID

...
"custom_fields_values": [
    {
        "field_id": 25,
        "values": [
            {
                "value": {
                    "name": "The Origin Lab",
                    "entity_type": 1,
                    "vat_id": "123123123",
                    "tax_registration_reason_code": 213,
                    "address": "San Francisco",                  
                    "external_uid": "uuid"
                }
            }
        ]
    }
],
...

linked_entity

In this example, consider a query to populate a field of type linked_entity.

Parameter	Data type	Description
value	object	Field value
value[name]	string	Displayed field value. Transmitted for instantaneous display
value[entity_id]	int	Linked entity ID
value[entity_type]	string	Linked entity type (contacts, companies, etc.)
value[catalog_id]	int\|null	List ID, if link is specified

...
"custom_fields_values": [
  {
    "field_id": 1150977,
    "values": [
      {
        "value": {
          "name": "John Hancock",
          "entity_id": 24833339,
          "entity_type": "contacts",
          "catalog_id": null
        }
      }
    ]
  },
  {
    "field_id": 1150979,
    "values": [
      {
        "value": {
          "name": "Product 1",
          "entity_id": 527597,
          "entity_type": "catalog_elements",
          "catalog_id": 6319
        }
      }
    ]
  }
],
...

chained_list

In this example, consider a request to populate a field of type chained_list. The field supports multiple values, up to 5 elements.

Parameter	Data type	Description
catalog_id	int	List ID, if a link to the list is specified
catalog_element_id	int	ID of the list item, if a link to the list is specified

...
"custom_fields_values": [
  {
    "field_id": 1150985,
    "values": [
      {
        "catalog_id": 1001,
        "catalog_element_id": 12235
      },
      {
        "catalog_id": 1007,
        "catalog_element_id": 12243
      }
    ]
  }
],
...

file

In this example, consider a query to populate a field of type file.

Parameter	Data type	Description
value	object	Field value
value[file_uuid]	string	UUID of a file in the file service
value[version_uuid]	string	UUID of the file version in the file service
value[file_name]	string	File name
value[file_size]	int	File size

...
"custom_fields_values": [
  {
    "field_id": 1150985,
    "values": [
      {
        "value": {
          "file_uuid": "3b454645-5c7f-4539-9ef9-0dd1b3638dad",
          "version_uuid": "13db6652-b3ed-4fff-aed8-0c6f3c43b887",
          "file_name": "wiki.odt",
          "file_size": 20763,
        }
      }
    ]
  }
],
...