---
updatedAt: 2025-07-11T10:43:58.000Z
---

Fetch the complete documentation index at: https://developers.kommo.com/llms.txt. Use this file to discover all available pages before exploring further. Append .md to any documentation page URL to get its markdown version.

# Custom fields and field groups

# 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](https://developers.kommo.com/reference/custom-fields#text-numeric-textarea-price-streetaddress-tracking_data-monetary)
* [numeric](https://developers.kommo.com/reference/custom-fields#text-numeric-textarea-price-streetaddress-tracking_data-monetary)
* [checkbox](https://developers.kommo.com/reference/custom-fields#checkbox)
* [select](https://developers.kommo.com/reference/custom-fields#select-multiselect-radiobutton-category)
* [multiselect](https://developers.kommo.com/reference/custom-fields#select-multiselect-radiobutton-category)
* [date](https://developers.kommo.com/reference/custom-fields#date-date_time-birthday)
* [url](https://developers.kommo.com/reference/custom-fields#url)
* [textarea](https://developers.kommo.com/reference/custom-fields#text-numeric-textarea-price-streetaddress-tracking_data-monetary)
* [radiobutton](https://developers.kommo.com/reference/custom-fields#select-multiselect-radiobutton-category)
* [streetaddress](https://developers.kommo.com/reference/custom-fields#text-numeric-textarea-price-streetaddress-tracking_data-monetary)
* [smart\_address](https://developers.kommo.com/reference/custom-fields#smart_address)
* [legal\_entity](https://developers.kommo.com/reference/custom-fields#legal_entity)
* [birthday](https://developers.kommo.com/reference/custom-fields#date-date_time-birthday)
* [date\_time](https://developers.kommo.com/reference/custom-fields#date-date_time-birthday)
* [price](https://developers.kommo.com/reference/custom-fields#text-numeric-textarea-price-streetaddress-tracking_data-monetary)
* [category](https://developers.kommo.com/reference/custom-fields#select-multiselect-radiobutton-category)
* [multitext](https://developers.kommo.com/reference/custom-fields#multitext)
* [tracking\_data](https://developers.kommo.com/reference/custom-fields#text-numeric-textarea-price-streetaddress-tracking_data-monetary)
* [linked\_entity](https://developers.kommo.com/reference/custom-fields#linked_entity)
* [chained\_list](https://developers.kommo.com/reference/custom-fields#chained_list)
* [monetary](https://developers.kommo.com/reference/custom-fields#text-numeric-textarea-price-streetaddress-tracking_data-monetary)
* [file](https://developers.kommo.com/reference/custom-fields#file)

## 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 |

```json JSON
...
"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 `checkbox`type.

| Parameter | Data Type | Description |
| :-------- | :-------- | :---------- |
| value     | bool      | Field value |

```json
...
"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 |

```json
...
"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 |

```json
...
"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) |

```json
...
"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_id`or `enum_code`fields 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 |

```json
...
"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_id`or `enum_code`fields must be passed in the value.

<Table align={["left","left","left"]}>
  <thead>
    <tr>
      <th>
        Parameter
      </th>

      <th>
        Data type
      </th>

      <th>
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        value
      </td>

      <td>
        string
      </td>

      <td>
        Field value
      </td>
    </tr>

    <tr>
      <td>
        enum\_id
      </td>

      <td>
        int
      </td>

      <td>
        Field value ID
      </td>
    </tr>

    <tr>
      <td>
        enum\_code
      </td>

      <td>
        string
      </td>

      <td>
        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.
      </td>
    </tr>
  </tbody>
</Table>

```json
...
"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                                   |

```json
...
"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                                |

```json
...
"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 |

```json
...
"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                                    |

```json
...
"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,
        }
      }
    ]
  }
],
...
```