Custom fields and their groups

In this section we will describe all available methods for Custom fields and their groups.

Common information
Custom fields list
Getting an entity field by its ID
Adding custom fields
Updating custom fields
Deleting a custom field
Custom field groups list
Getting the field group of an entity by the group ID
Adding field groups
Editing custom field group
Deleting a custom field group
Available field types
Examples of custom fields of different types fill-in via API

Common information

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

Custom fields list

Method

GET /api/v4/leads/custom_fields

GET /api/v4/contacts/custom_fields

GET /api/v4/companies/custom_fields

GET /api/v4/customers/custom_fields

GET /api/v4/customers/segments/custom_fields

GET /api/v4/catalogs/{catalog_id}/custom_fields

Description

This method allows to get a list of custom fields in the account.

Limitations

Method is available for all account users.

Data type header when the request is successful

Content-Type: application/hal+json

Data type header in case of an error

Content-Type: application/problem+json

HTTP response codes.

Response code	Case
200	Request successful
422	Request can not be processed. Details are available in the request response
401	User is not authorized
400	Invalid data given. Details are available in the request response

Response parameters

Method returns a collection of custom field models. The properties of the custom field model are listed below. Model properties differ depending on the entity.

Parameter	Data type	Description
id	int	Field ID
name	string	Field name
code	string	Field code that can be used to update the value of the field without passing the field ID in the request
sort	int	Field sorting
type	int	Field type. The list of the available types
entity_type	string	Entity type (leads, contacts, companies, segments, customers, catalogs)
is_predefined	bool	Defines whether the field is predefined. This parameter is returned only when getting a contact or company fields list
is_deletable	bool	Defines whether the field is deletable. This parameter is returned only when getting a contact or company fields list
is_visible	bool	Defines whether the field is displayed in the list interface. This parameter is returned only when getting a list of lists (catalogs) fields
is_deletable	bool	Defines whether the field is deletable from the list interface. This parameter is returned only when getting a list of lists (catalogs) fields
is_required	bool	Defines whether the field is mandatory when creating a list element. This parameter is returned only when getting a list of lists (catalogs) fields
settings	array\|null	Field settings. This parameter is returned only when getting a list of lists (catalog) fields.
remind	string\|null	Birthday reminders setting (never, day – day before the event, week – week before the event, month – month before the event). This value is available only for the birthday type field. This parameter is returned only when getting a list of lead, contact, or company fields, сделок и компаний
enums	array\|null	Available field values array. Only available for the fields with enum values
enums[0]	object	Available field value model
enums[0][id]	int	Value ID
enums[0][value]	string	Value
enums[0][sort]	int	Value sorting
nested	array\|null	Nested values array. This parameter is returned only when getting the list of catalog fields. The value is avalable only for the category type field
nested[0]	object	Nested value model. This parameter is returned only when getting the list of catalog fields. The value is avalable only for the category type field
nested[0][id]	int	Nested value ID. This parameter is returned only when getting the list of catalog fields. The value is avalable only for the category type field
nested[0][parent_id]	int	Nested value parent ID. This parameter is returned only when getting the list of catalog fields. The value is avalable only for the category type field
nested[0][value]	string	The value of the nested value. This parameter is returned only when getting the list of catalog fields. The value is avalable only for the category type field
nested[0][sort]	int	Nested value sorting. This parameter is returned only when getting the list of catalog fields. The value is avalable only for the category type field
is_api_only	bool	Defines whether the field is editable via API only. This parameter is returned only when getting a lead, contact, or company fields list
group_id	string\|null	Fields group ID for the current field. This parameter is returned only when getting a lead, contact, company, or customer fields list
required_statuses	array\|null	Array of the fields required to change a lead status. This parameter is returned only when getting a lead, contact, or company fields list
required_statuses[0]	object	Required field model. This parameter is returned only when getting a lead, contact, or company fields list
required_statuses[0][status_id]	int	ID of the stage which requires the current field to have a value before the lead can be moved. This parameter is returned only when getting a lead, contact, or company fields list
required_statuses[0][pipeline_id]	int	ID of the pipeline which requires the current field to have a value before the lead can be moved. This parameter is returned only when getting a lead, contact, or company fields list

Response example

        
{
    "_total_items": 2,
    "_page": 1,
    "_page_count": 10,
    "_links": {
        "self": {
            "href": "https://example.kommo.com/api/v4/leads/custom_fields?limit=2&page=1"
        },
        "next": {
            "href": "https://example.kommo.com/api/v4/leads/custom_fields?limit=2&page=2"
        },
        "last": {
            "href": "https://example.kommo.com/api/v4/leads/custom_fields?limit=2&page=10"
        }
    },
    "_embedded": {
        "custom_fields": [
            {
                "id": 4439091,
                "name": "Text field example",
                "sort": 504,
                "type": "text",
                "is_predefined": false,
                "settings": null,
                "remind": null,
                "is_api_only": false,
                "group_id": null,
                "enums": null,
                "required_statuses": [
                    {
                        "status_id": 41221,
                        "pipeline_id": 3142
                    }
                ],
                "_links": {
                    "self": {
                        "href": "https://example.kommo.com/api/v4/custom_fields/4439091/"
                    }
                }
            },
            {
                "id": 4440043,
                "name": "Example 'date' type field",
                "sort": 505,
                "type": "date",
                "is_predefined": false,
                "settings": null,
                "remind": null,
                "is_api_only": false,
                "group_id": null,
                "enums": null,
                "required_statuses": null,
                "_links": {
                    "self": {
                        "href": "https://example.kommo.com/api/v4/custom_fields/4440043/"
                    }
                }
            }
        ]
    }
}

Getting an entity field by its ID

Method

GET /api/v4/leads/custom_fields/{id}

GET /api/v4/contacts/custom_fields/{id}

GET /api/v4/companies/custom_fields/{id}

GET /api/v4/customers/custom_fields/{id}

GET /api/v4/customers/segments/custom_fields/{id}

GET /api/v4/catalogs/{catalog_id}/custom_fields/{id}

Description

This method allows to get a particular custom field data by its ID.

Limitations

Method is available for all account users.

Data type header when the request is successful

Content-Type: application/hal+json

Data type header in case of an error

Content-Type: application/problem+json

HTTP response codes.

Response code	Case
200	Request successful
422	Request can not be processed. Details are available in the request response
401	User is not authorized

Response parameters

Method returns a custom field model. The properties of the custom field model are listed below. Model properties differ depending on the entity.

Parameter	Data type	Description
id	int	Field ID
name	string	Field name
code	string	Field code that can be used to update the value of the field without passing the field ID in the request
sort	int	Field sorting
type	int	Field type. The list of the available types
entity_type	string	Entity type (leads, contacts, companies, segments, customers, catalogs)
is_predefined	bool	Defines whether the field is predefined. This parameter is returned only when getting a contact or company field
is_deletable	bool	Defines whether the field is deletable. This parameter is returned only when getting a contact or company field
is_visible	bool	Defines whether the field is displayed in the list interface. This parameter is returned only when getting a list of lists (catalogs) fields
is_deletable	bool	Defines whether the field is deletable from the list interface. This parameter is returned only when getting a list of lists (catalogs) fields
is_required	bool	Defines whether the field is mandatory when creating a list element. This parameter is returned only when getting a list of lists (catalogs) fields
settings	array\|null	Field settings. This parameter is returned only when getting a list (catalog) field.
remind	string\|int	Birthday reminders setting (never, day – day before the event, week – week before the event, month – month before the event). This value is available only for the birthday type field. This parameter is returned only when getting a lead, contact, or company field
enums	array\|null	Available field values array. Only available for the fields with enum values
enums[0]	object	Available field value model
enums[0][id]	int	Value ID
enums[0][value]	string	Value
enums[0][sort]	int	Value sorting
is_api_only	bool	Defines whether the field is editable via API only. This parameter is returned only when getting a lead, contact, or company field
group_id	string\|null	Fields group ID for the current field. This parameter is returned only when getting a lead, contact, company, or customer field
required_statuses	array\|null	Array of the fields required to change a lead status. This parameter is returned only when getting a lead, contact, or company field
required_statuses[0]	object	Required field model. This parameter is returned only when getting a lead, contact, or company field
required_statuses[0][status_id]	int	ID of the stage which requires the current field to have a value before the lead can be moved. This parameter is returned only when getting a lead, contact, or company field
required_statuses[0][pipeline_id]	int	ID of the pipeline which requires the current field to have a value before the lead can be moved. This parameter is returned only when getting a lead, contact, or company field
nested	array\|null	Nested values array. This parameter is returned only when getting the list of catalog fields. The value is avalable only for the category type field
nested[0]	object	Nested value model. This parameter is returned only when getting the list of catalog fields. The value is avalable only for the category type field
nested[0][id]	int	Nested value ID. This parameter is returned only when getting the list of catalog fields. The value is avalable only for the category type field
nested[0][parent_id]	int	Nested value parent ID. This parameter is returned only when getting the list of catalog fields. The value is avalable only for the category type field
nested[0][value]	string	The value of the nested value. This parameter is returned only when getting the list of catalog fields. The value is avalable only for the category type field
nested[0][sort]	int	Nested value sorting. This parameter is returned only when getting the list of catalog fields. The value is avalable only for the category type field

Response example

        
{
    "id": 3,
    "name": "Phone",
    "type": "multitext",
    "account_id": 28805383,
    "code": "PHONE",
    "sort": 4,
    "is_api_only": false,
    "enums": [
        {
            "id": 1,
            "value": "WORK",
            "sort": 2
        },
        {
            "id": 3,
            "value": "WORKDD",
            "sort": 4
        },
        {
            "id": 5,
            "value": "MOB",
            "sort": 6
        },
        {
            "id": 7,
            "value": "FAX",
            "sort": 8
        },
        {
            "id": 9,
            "value": "HOME",
            "sort": 10
        },
        {
            "id": 11,
            "value": "OTHER",
            "sort": 12
        }
    ],
    "group_id": null,
    "required_statuses": [],
    "is_deletable": false,
    "is_predefined": true,
    "entity_type": "contacts",
    "remind": null,
    "_links": {
        "self": {
            "href": "https://example.kommo.com/api/v4/contacts/custom_fields/3"
        }
    }
}

Adding custom fields

Method

POST /api/v4/leads/custom_fields

POST /api/v4/contacts/custom_fields

POST /api/v4/companies/custom_fields

POST /api/v4/customers/custom_fields

POST /api/v4/customers/segments/custom_fields

POST /api/v4/catalogs/{catalog_id}/custom_fields

Description

This method allows to add singular or multiple custom fields to an entity.

Limitations

Method is available for administrator users only.

Request header

Content-Type: application/json

Request parameters

To add a custom field, the field model should be passed.

Parameter	Data type	Description	Is the field mandatory	Supported field types
type	string	Field type. The list of the available types	✅	Available for all field types
name	string	Field name	✅	Available for all field types
code	string	Field code that can be used to update the value of the field without passing the field ID in the request	❌	Available for all field types
sort	int	Field sorting in the field group	❌	Available for all field types
group_id	string	Field group ID	❌	Available for all lead, contact, company, and customer fields
is_api_only	bool	Defines whether the field is editable via API only	❌	Available for all lead, contact, and company fields
required_statuses	array\|null	Array of the fields required to change a lead status	❌	Available for all lead, contact, company, and customer fields
required_statuses[0]	object	Required field model	❌	Available for all lead, contact, company, and customer fields
required_statuses[0][status_id]	int	ID of the stage which requires the current field to have a value before the lead can be moved	❌	Available for all lead, contact, company, and customer fields
required_statuses[0][pipeline_id]	int	ID of the pipeline which requires the current field to have a value before the lead can be moved	❌	Available for all lead, contact, company, and customer fields
settings	object	Field settings	❌	Available for all lists (catalogs) fields
is_visible	bool	Defines whether the field is displayed in the list interface	❌	Available for all lists (catalogs) fields
is_required	bool	Defines whether the field is mandatory when creating a list element	❌	Available for all lists (catalogs) fields
remind	string\|null	Birthday reminders setting (never, day – day before the event, week – week before the event, month – month before the event)	❌	Available only for the birthday type fields
enums	array	Available field values array	✅	Available for the following field types: multiselect radiobutton select
enums[0]	object	Available field value model	✅	Available for the following field types: multiselect radiobutton select
enums[0][value]	string	Value	✅	Available for the following field types: multiselect radiobutton select
enums[0][sort]	string	Value sorting	✅	Available for the following field types: multiselect radiobutton select
nested	array	Nested values array	❌	Available for the following field types: category
nested[0]	object	Nested value model	❌	Available for the following field types: category
nested[0][id]	int	Nested value ID	❌	Available for the following field types: category
nested[0][parent_id]	int	Nested value parent ID	❌	Available for the following field types: category
nested[0][value]	string	The value of the nested value	❌	Available for the following field types: category
nested[0][sort]	int	Nested value sorting	❌	Available for the following field types: category
nested[0][request_id]	string	Temporary identifier of a nested value. Identifier should be unique for the request, isn’t saved anywhere, and is used to create more than one nesting level within one request	❌	Available for the following field types: category
nested[0][parent_request_id]	string	Temporary identifier of a nested value parent. Identifier is used only at the time of the request, isn’t saved anywhere, and defines the nesting level of the added element if the parent element hasn’t been created yet	❌	Available for the following field types: category

An example of the request

        
[
    {
        "name": "multi select",
        "type": "multiselect",
        "sort": 510,
        "required_statuses": [
            {
                "pipeline_id": 16056,
                "status_id": 20540473
            }
        ],
        "enums": [
            {
                "value": "Value 1",
                "sort": 1
            },
            {
                "value": "Value 2",
                "sort": 2
            }
        ]
    }
]

Data type header when the request is successful

Content-Type: application/hal+json

Data type header in case of an error

Content-Type: application/problem+json

HTTP response codes.

Response code	Case
201	Request successful
422	Request can not be processed. Details are available in the request response
401	User is not authorized
400	Invalid data given. Details are available in the request response

Response parameters

Method returns a collection of created fields’ models. The parameters are similar to the custom fields list request parameters

Response example

        
{
    "_total_items": 1,
    "_embedded": {
        "custom_fields": [
            {
                "name": "multi select",
                "type": "multiselect",
                "sort": 510,
                "settings": null,
                "is_predefined": false,
                "id": 4457223,
                "remind": null,
                "is_api_only": false,
                "enums": [
                    {
                        "value": "Value 1",
                        "sort": 1,
                        "id": 3778801
                    },
                    {
                        "value": "Value 2",
                        "sort": 2,
                        "id": 3778803
                    }
                ],
                "group_id": null,
                "required_statuses": [
                    {
                        "status_id": 20540473,
                        "pipeline_id": 16056
                    },
                ],
                "_links": {
                    "self": {
                        "href": "https://example.kommo.com/api/v4/custom_fields/4457223/"
                    }
                }
            }
        ]
    }
}

Updating custom fields

Method

PATCH /api/v4/leads/custom_fields

PATCH /api/v4/contacts/custom_fields

PATCH /api/v4/companies/custom_fields

PATCH /api/v4/customers/custom_fields

PATCH /api/v4/customers/segments/custom_fields

PATCH /api/v4/catalogs/{catalog_id}/custom_fields

Description

This method allows to update singular or multiple custom fields of an entity.
To update a singular custom field, you can add the field ID into the method URL (/api/v4/leads/custom_fields/{id}).
When updating multiple custom fields, an array of field objects is passed. In the case with a singular custom field, the field model is passed.

Limitations

Method is available for administrator users only.

Request header

Content-Type: application/json

Request parameters

To update a custom field, the field model should be passed.

Parameter	Data type	Description	Is the field mandatory	Supported field types
name	string	Field name	✅	Available for all field types
code	string	Field code that can be used to update the value of the field without passing the field ID in the request	❌	Available for all field types
sort	int	Field sorting in the field group	❌	Available for all field types
group_id	string	Field group ID	❌	Available for all lead, contact, company, and customer fields
is_api_only	bool	Defines whether the field is editable via API only	❌	Available for all lead, contact, and company fields
required_statuses	array\|null	Array of the fields required to change a lead status	❌	Available for all lead, contact, company, and customer fields
required_statuses[0]	object	Required field model	❌	Available for all lead, contact, company, and customer fields
required_statuses[0][status_id]	int	ID of the stage which requires the current field to have a value before the lead can be moved	❌	Available for all lead, contact, company, and customer fields
required_statuses[0][pipeline_id]	int	ID of the pipeline which requires the current field to have a value before the lead can be moved	❌	Available for all lead, contact, company, and customer fields
settings	object	Field settings	❌	Available for all lists (catalogs) fields
is_visible	bool	Defines whether the field is displayed in the list interface	❌	Available for all lists (catalogs) fields
is_required	bool	Defines whether the field is mandatory when creating a list element	❌	Available for all lists (catalogs) fields
remind	string\|null	Birthday reminders setting (never, day – day before the event, week – week before the event, month – month before the event)	❌	Available only for the birthday type fields
enums	array	Available field values array	✅	Available for the following field types: multiselect radiobutton select
enums[0]	object	Available field value model	✅	Available for the following field types: multiselect radiobutton select
enums[0][value]	string	Value	✅	Available for the following field types: multiselect radiobutton select
enums[0][sort]	string	Value sorting	✅	Available for the following field types: multiselect radiobutton select
nested	array	Nested values array	❌	Available for the following field types: category
nested[0]	object	Nested value model	❌	Available for the following field types: category
nested[0][id]	int	Nested value ID. Shouldn’t be passed when creating a new value	❌	Available for the following field types: category
nested[0][parent_id]	int	Nested value parent ID	❌	Available for the following field types: category
nested[0][value]	string	The value of the nested value	❌	Available for the following field types: category
nested[0][sort]	int	Nested value sorting	❌	Available for the following field types: category
nested[0][request_id]	string	Temporary identifier of a nested value. Identifier should be unique for the request, isn’t saved anywhere, and is used to create more than one nesting level within one request	❌	Available for the following field types: category
nested[0][parent_request_id]	string	Temporary identifier of a nested value parent. Identifier is used only at the time of the request, isn’t saved anywhere, and defines the nesting level of the added element if the parent element hasn’t been created yet	❌	Available for the following field types: category

An example of the request

In the following example we’ll update 2 catalog fields using the method /api/v4/catalogs/{catalog_id}/custom_fields.

        
[
    {
        "id": 1278898087,
        "name": "New custom field name",
        "sort": 560,
        "is_visible": false,
        "is_required": true
    },
    {
        "id": 1278898091,
        "name": "New Category field name",
        "nested": [
            {
                "id": 197,
                "parent_id": null,
                "value": "category 1",
                "sort": 0
            },
            {
                "parent_id": null,
                "value": "new category 2",
                "sort": 1
            },
            {
                "parent_id": 197,
                "value": "new subcategory 1",
                "sort": 1
            }
        ]
    }
]

Data type header when the request is successful

Content-Type: application/hal+json

Data type header in case of an error

Content-Type: application/problem+json

HTTP response codes.

Response code	Case
201	Request successful
422	Request can not be processed. Details are available in the request response
401	User is not authorized
400	Invalid data given. Details are available in the request response

Response parameters

Method returns a collection of updated fields’ models. The parameters are similar to the custom fields list request parameters.

Response example

        
{
    "_total_items": 2,
    "_embedded": {
        "custom_fields": [
            {
                "id": 1278898087,
                "name": "New custom field name",
                "type": "textarea",
                "account_id": 17079858,
                "code": "DESCRIPTION",
                "sort": 560,
                "is_api_only": false,
                "enums": null,
                "request_id": "0",
                "catalog_id": 1095,
                "is_visible": false,
                "is_deletable": true,
                "is_required": false,
                "nested": null,
                "entity_type": "catalogs",
                "_links": {
                    "self": {
                        "href": "https://example.kommo.com/api/v4/catalogs/1095/custom_fields/1278898087"
                    }
                }
            },
            {
                "id": 1278898091,
                "name": "New Category field name",
                "type": "category",
                "account_id": 17079858,
                "code": "GROUP",
                "sort": 500,
                "is_api_only": false,
                "enums": null,
                "request_id": "1",
                "catalog_id": 1095,
                "is_visible": true,
                "is_deletable": false,
                "is_required": false,
                "nested": [
                    {
                        "id": 197,
                        "parent_id": null,
                        "value": "category 1",
                        "sort": 0
                    },
                    {
                        "id": 215,
                        "parent_id": 197,
                        "value": "new subcategory 1",
                        "sort": 0
                    },
                    {
                        "id": 217,
                        "parent_id": 197,
                        "value": "new category 2",
                        "sort": 1
                    }
                ],
                "entity_type": "catalogs",
                "_links": {
                    "self": {
                        "href": "https://example.kommo.com/api/v4/catalogs/1095/custom_fields/1278898091"
                    }
                }
            }
        ]
    }
}

Deleting a custom field

Method

DELETE /api/v4/leads/custom_fields/{id}

DELETE /api/v4/contacts/custom_fields/{id}

DELETE /api/v4/companies/custom_fields/{id}

DELETE /api/v4/customers/custom_fields/{id}

DELETE /api/v4/customers/segments/custom_fields/{id}

DELETE /api/v4/catalogs/{catalog_id}/custom_fields/{id}

Description

This method allows to delete a custom field of an entity on the account.

Limitations

Method is available for administrator users only.
Custom field values will be deleted.

Request header

Content-Type: application/json

HTTP response codes.

Response code	Case
204	The field has been successfully deleted
403	Insufficient rights to call this method
401	User is not authorized
400	Invalid data given. Details are available in the request response

Response parameters

Method does not return a body.

Custom field groups list

Method

GET /api/v4/leads/custom_fields/groups

GET /api/v4/contacts/custom_fields/groups

GET /api/v4/companies/custom_fields/groups

GET /api/v4/customers/custom_fields/groups

Description

This method allows to get a list of custom field groups in the account.

Limitations

Method is available for all account users.

Data type header when the request is successful

Content-Type: application/hal+json

Data type header in case of an error

Content-Type: application/problem+json

HTTP response codes.

Response code	Case
200	Request successful
401	User is not authorized
400	Invalid data given. Details are available in the request response

Response parameters

Method returns a collection of custom field group models. The properties of the custom field group model are listed below.

Parameter	Data type	Description
id	string	Field group ID
name	string	Field group name
sort	int	Field group sorting within the entity card
entity_type	string	Entity type (leads, contacts, companies, customers)
is_predefined	bool	Defines whether the field group is predefined. Such groups can’t be deleted
type	string	Field group type (linked_group – product groups, custom_field_group – field groups)

Response example

        
{
    "id": "leads_29741591099841",
    "name": "Field group",
    "is_predefined": false,
    "type": "custom_field_group",
    "entity_type": "leads",
    "sort": 3,
    "_links": {
        "self": {
            "href": "https://example.kommo.com/api/v4/leads/custom_fields/groups/leads_29741591099841"
        }
    }
}

Getting the field group of an entity by the group ID

Method

GET /api/v4/leads/custom_fields/groups/{id}

GET /api/v4/contacts/custom_fields/groups/{id}

GET /api/v4/companies/custom_fields/groups/{id}

GET /api/v4/customers/custom_fields/groups/{id}

Description

This method allows to get the field group of an entity on the account.

Limitations

Method is available for all account users.

Data type header when the request is successful

Content-Type: application/hal+json

Data type header in case of an error

Content-Type: application/problem+json

HTTP response codes.

Response code	Case
200	Request successful
404	The field group wasn’t found
401	User is not authorized

Response parameters

Method returns a custom field group model. The properties of the custom field group model are listed below.

Parameter	Data type	Description
id	string	Field group ID
name	string	Field group name
sort	int	Field group sorting within the entity card
entity_type	string	Entity type (leads, contacts, companies, customers)
is_predefined	bool	Defines whether the field group is predefined. Such groups can’t be deleted
type	string	Field group type (linked_group – product groups, custom_field_group – field groups)

Response example

        
{
    "_total_items": 4,
    "_embedded": {
        "custom_field_groups": [
            {
                "id": "default",
                "name": "Default",
                "is_predefined": true,
                "type": "custom_field_group",
                "entity_type": "leads",
                "sort": 0,
                "_links": {
                    "self": {
                        "href": "https://example.kommo.com/api/v4/leads/custom_fields/groups/default"
                    }
                }
            },
            {
                "id": "4521",
                "name": "Products",
                "is_predefined": true,
                "type": "linked_group",
                "entity_type": "leads",
                "sort": 1,
                "_links": {
                    "self": {
                        "href": "https://example.kommo.com/api/v4/leads/custom_fields/groups/4521"
                    }
                }
            },
            {
                "id": "statistic",
                "name": "Stats",
                "is_predefined": true,
                "type": "linked_group",
                "entity_type": "leads",
                "sort": 2,
                "_links": {
                    "self": {
                        "href": "https://example.kommo.com/api/v4/leads/custom_fields/groups/statistic"
                    }
                }
            },
            {
                "id": "leads_29741591099841",
                "name": "Field group",
                "is_predefined": false,
                "type": "custom_field_group",
                "entity_type": "leads",
                "sort": 3,
                "_links": {
                    "self": {
                        "href": "https://example.kommo.com/api/v4/leads/custom_fields/groups/leads_29741591099841"
                    }
                }
            }
        ]
    }
}

Adding field groups

Method

POST /api/v4/leads/custom_fields/groups

POST /api/v4/contacts/custom_fields/groups

POST /api/v4/companies/custom_fields/groups

POST /api/v4/customers/custom_fields/groups

Description

This method allows to add multiple or singular field groups into the account.

Limitations

Method is available for administrator users only.

Request header

Content-Type: application/json

Request parameters

Parameter	Data type	Description
name	string	Field group name. This parameter is mandatory
sort	int	Field group sorting. This parameter is mandatory
request_id	string	Field that will be returned unchanged in the response and will not be saved. This parameter is not mandatory

An example of the request

        
[
    {
        "name": "group 1",
        "sort": 4
    },
    {
        "name": "group 2",
        "sort": 5
    }
]

Data type header when the request is successful

Content-Type: application/hal+json

Data type header in case of an error

Content-Type: application/problem+json

HTTP response codes.

Response code	Case
201	The field groups have been successfully added
403	Insufficient rights to call this method
401	User is not authorized
400	Invalid data given. Details are available in the request response

Response parameters

Method returns a collection of created field group models. The parameters are similar to the custom field groups list request parameters.

Response example

        
{
    "_total_items": 2,
    "_embedded": {
        "custom_field_groups": [
            {
                "id": "leads_2745158",
                "name": "group 1",
                "is_predefined": false,
                "type": "custom_field_group",
                "entity_type": "leads",
                "sort": 4,
                "_links": {
                    "self": {
                        "href": "https://example.kommo.com/api/v4/leads/custom_fields/groups/leads_2745158/"
                    }
                }
            },
            {
                "id": "leads_609315",
                "name": "group 2",
                "is_predefined": false,
                "type": "custom_field_group",
                "entity_type": "leads",
                "sort": 5,
                "_links": {
                    "self": {
                        "href": "https://example.kommo.com/api/v4/leads/custom_fields/groups/leads_609315/"
                    }
                }
            }
        ]
    }
}

Editing custom field group

Method

PATCH /api/v4/leads/custom_fields/groups/{id}

PATCH /api/v4/contacts/custom_fields/groups/{id}

PATCH /api/v4/companies/custom_fields/groups/{id}

PATCH /api/v4/customers/custom_fields/groups/{id}

Description

This method allows to edit a particular custom field group by the group ID.

Limitations

Method is available for administrator users only.

Request header

Content-Type: application/json

Request parameters

To edit a field group, at least one parameter should be passed

Parameter	Data type	Description
name	string	Group name
sort	int	Group sorting

An example of the request

        
{
    "sort": 6
}

Data type header when the request is successful

Content-Type: application/hal+json

Data type header in case of an error

Content-Type: application/problem+json

HTTP response codes.

Response code	Case
200	The field group has been successfully edited
403	Insufficient rights to call this method
401	User is not authorized
400	Invalid data given. Details are available in the request response

Response parameters

Method returns the edited field group model. The parameters are similar to the custom field groups list request parameters.

Response example

        
{
    "id": "leads_2745",
    "name": "group 1",
    "is_predefined": false,
    "type": "custom_field_group",
    "entity_type": "leads",
    "sort": 6,
    "_links": {
        "self": {
            "href": "https://example.kommo.com/api/v4/leads/custom_fields/groups/leads_2745/"
        }
    }
}

Deleting a custom field group

Method

DELETE /api/v4/leads/custom_fields/groups/{id}

DELETE /api/v4/contacts/custom_fields/groups/{id}

DELETE /api/v4/companies/custom_fields/groups/{id}

DELETE /api/v4/customers/custom_fields/groups/{id}

Description

This method allows to delete a custom field group of an entity on the account.

Limitations

Method is available for administrator users only.
Predefined groups can\’t be deleted.

Request header

Content-Type: application/json

HTTP response codes.

Response code	Case
204	The field group has been successfully deleted
404	The field group wasn’t found
403	Insufficient rights to call this method
401	User is not authorized
400	Invalid data given. Details are available in the request response

Response parameters

Method does not return a body.

Available field types

Available custom 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
items	Products

Custom field types availability table for different entities

Field type	Contact	Lead	Company	Customer	Catalog	Segment
Text	✅	✅	✅	✅	✅	✅
Number	✅	✅	✅	✅	✅	✅
Checkbox	✅	✅	✅	✅	✅	✅
List	✅	✅	✅	✅	✅	✅
Multiselect list	✅	✅	✅	✅	✅	✅
Multitext	✅	❌	❌	❌	❌	❌
Date	✅	✅	✅	✅	✅	✅
URL	✅	✅	✅	✅	✅	✅
Date and time	✅	✅	✅	✅	✅	✅
Text area	✅	✅	✅	✅	✅	✅
Switch	✅	✅	✅	✅	✅	✅
Short address	✅	✅	✅	✅	✅	✅
Address	✅	✅	✅	❌	❌	❌
Birthday	✅	✅	✅	❌	❌	❌
Tax ID	✅	✅	✅	❌	❌	❌
Price	❌	❌	❌	❌	✅	❌
Category	❌	❌	❌	❌	✅	❌
Products	❌	❌	❌	❌	✅	❌

Examples of custom fields of different types fill-in via API

Below, we’ll review examples of adding values to custom fields of different types.

All values are passed within objects of the custom_fields_values array, regardless of the field type. To fill a custom field, the field ID or field code as well as values shoud be passed.

Parameter	Data type	Description
custom_fields_values	array	An array that contains information about custom field values we want to set for an entity
custom_fields_values[0]	object	An object that contains information about the custom field value we want to set for an entity
custom_fields_values[0][field_id]	int	The ID of the field we want to fill in
custom_fields_values[0][field_code]	string	The code of the field we want to fill in
custom_fields_values[0][values]	array	An array of values we add
custom_fields_values[0][values][0]	object	Field value object. The object’s structure depends on the field type

Field types:

text
numeric
checkbox
select
multiselect
date
url
textarea
radiobutton
streetaddress
smart_address
legal_entity
birthday
date_time
price
category
items
multitext

text, numeric, textarea, price, streetaddress

In the following example we’ll review the request to fill in text, numeric, textarea, price, and streetaddress type fields.

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": "222 Columbus Ave Ste 407, San Francisco, CA, 94133-5809"
                }
            ]
        }
    ],
    ...

checkbox

In the following example we’ll review the request to fill in a checkbox type field.

Parameter	Data type	Description
value	bool	Field value

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

url

In the following example we’ll review the request to fill in a url type field.

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 the following example we’ll review the request to fill in date, date_time, and birthday type fields.

Parameter	Data type	Description
value	int	Field value – Unix Timestamp

        
    ...
    "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 the following example we’ll review the request to fill in select, multiselect, radiobutton, and category type fields. The value itself or value ID can be passed.

Parameter	Data type	Description
value	string	Field value
enum_id	int	Field value ID (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 the following example we’ll review the request to fill in a smart_address type field. This field takes multiple values. Parameters value and enum_id or enum_code should be passed.

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

        
    ...
    "custom_fields_values": [
        {
            "field_id": 13,
            "values": [
                {
                    "value": "222 Columbus Ave Ste 407",
                    "enum_id": 1
                },
                {
                    "value": "San Francisco",
                    "enum_code": "city"
                },
                {
                    "value": "CA",
                    "enum_code": "state"
                },
                {
                    "value": "94133-5809",
                    "enum_id": 5
                },
                {
                    "value": "USA",
                    "enum_code": "country"
                }
            ]
        }
    ],
    ...

multitext

In the following example we’ll review the request to fill in a multitext (Phone, Email) type field. This field takes multiple values. Parameters value and enum_id or enum_code should be passed.

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: WORK – work phone number, WORKDD – direct work phone number, MOB – mobile, FAX – fax, HOME – home phone number, OTHER. Available values for the Email fieeld: WORK – work email address, PRIV – private email address, OTHER.

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

legal_entity

In the following example we’ll review the request to fill in a legal_entity type field. Parameters name, vat_id, and kpp should be passed.

Parameter	Data type	Description
value	object	Field value
value[name]	string	Organization name
value[entity_type]	int	Legal entity type. 1 – Private, 2 – Legal.
value[vat_id]	string	Organization’s EIN
value[tax_registration_reason_code]	string	Primary State Registration Number
value[address]	string	Organization’s address
value[kpp]	string	Tax Registration Reason Code
value[external_uid]	string	External system identifier

        
    ...
    "custom_fields_values": [
        {
            "field_id": 25,
            "values": [
                {
                    "value": {
                        "name": "Acme Co.",
                        "entity_type": 1,
                        "vat_id": "123123123",
                        "tax_registration_reason_code": 213,
                        "address": "San Francisco",
                        "kpp": "23123123",
                        "external_uid": "uuid"
                    }
                }
            ]
        }
    ],
    ...

items

In the following example we’ll review the request to fill in an items type field. Field is available in the invoice list.

Parameter	Data type	Description
value	object	Field value
value[sku]	string	Product SKU
value[description]	string	Product description
value[unit_price]	int\|float	Product unit price
value[quantity]	int\|float	Product quantity in the invoice
value[unit_type]	string	Product unit type
value[discount]	object	Product discount
value[discount][type]	string	Discount type (percentage, amount)
value[discount][value]	int\|float	Discount value
value[vat_rate_id]	int	Tax rate ID (0 – without VAT, 1 – 10%, 2 – 10/110, 3 – 18%, 4 – 18/118, 5 – 0)
value[external_uid]	string	External system identifier

        
    ...
    "custom_fields_values": [
        {
            "field_id": 25,
            "values": [
                {
                    "value": {
                        "sku": "34N4124",
                        "description": "Product description",
                        "unit_price": 10,
                        "quantity": 2,
                        "unit_type": "pc.",
                        "discount": {
                            "type": "amount",
                            "value": 25
                        },
                        "vat_rate_id": 18,
                        "external_uid": "uid"
                    }
                }
            ]
        }
    ],
    ...

Custom fields and their groups

Table of Contents

Common information

Custom fields list

Method

Description

Limitations

Data type header when the request is successful

Data type header in case of an error

HTTP response codes.

Response parameters

Response example

Getting an entity field by its ID

Method

Description

Limitations

Data type header when the request is successful

Data type header in case of an error

HTTP response codes.

Response parameters

Response example

Adding custom fields

Method

Description

Limitations

Request header

Request parameters

An example of the request

Data type header when the request is successful

Data type header in case of an error

HTTP response codes.

Response parameters

Response example

Updating custom fields

Method

Description

Limitations

Request header

Request parameters

An example of the request

Data type header when the request is successful

Data type header in case of an error

HTTP response codes.

Response parameters

Response example

Deleting a custom field

Method

Description

Limitations

Request header

HTTP response codes.

Response parameters

Custom field groups list

Method

Description

Limitations

Data type header when the request is successful

Data type header in case of an error

HTTP response codes.

Response parameters

Response example

Getting the field group of an entity by the group ID

Method

Description

Limitations

Data type header when the request is successful

Data type header in case of an error

HTTP response codes.

Response parameters

Response example

Adding field groups

Method

Description

Limitations

Request header

Request parameters

An example of the request

Data type header when the request is successful

Data type header in case of an error

HTTP response codes.