---
updatedAt: 2026-06-25T15:47:45.000Z
agentTools:
  projectIndex: https://developers.kommo.com/llms.txt
---

# Add custom fields

This method allows to add singular or multiple custom fields to an entity(leads, companies, contacts)

**Limitations**\
The method is available for administrator users only.

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

## Response parameters

| 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          | <Anchor label="Field type" target="_blank" href="https://developers.kommo.com/reference/custom-fields#available-field-types">Field type</Anchor>                                                                                                                                 |
| entity\_type                             | string       | Entity type (leads, contacts, companies).                                                                                                                                                                                                                                        |
| 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.                                                                                                                                                           |
| currency                                 | string\|null | Field currency code. Applicable only to the `monetary` field type. null for other field types.                                                                                                                                                                                   |
| 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 values model                                                                                                                                                                                                                                                     |
| enums\[id]                               | int          | Enum ID                                                                                                                                                                                                                                                                          |
| enums\[value]                            | string       | Enum value                                                                                                                                                                                                                                                                       |
| enums\[sort]                             | int          | Enum 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 fields list.                                                                                                                                        |
| group\_id                                | string\|null | Fields group ID for the current field. This parameter is returned only when getting a lead, contact or company 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\[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\[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.                                                                                          |
| hidden\_statuses                         | array        | Field hiding configuration. Fields are hidden in the UI based on their pipeline stage. This key is returned only when retrieving the list of lead fields.                                                                                                                        |
| hidden\_statuses\[0]                     | object       | Field hiding configuration model.                                                                                                                                                                                                                                                |
| hidden\_statuses\[0]\[status\_id]        | int          | ID of the stage in which the field is hidden.                                                                                                                                                                                                                                    |
| hidden\_statuses\[0]\[pipeline\_id]      | int          | ID of the pipeline in which the field is hidden.                                                                                                                                                                                                                                 |
| chained\_lists                           | array\|null  | Configuration of a `chained_list` type field. The key is returned only when retrieving the list of lead fields.                                                                                                                                                                  |
| chained\_lists\[0]                       | obj          | Chained list configuration model.                                                                                                                                                                                                                                                |
| chained\_lists\[0]\[title]               | string\|null | The name of the chained list displayed in the lead card.                                                                                                                                                                                                                         |
| chained\_lists\[0]\[catalog\_id]         | int          | ID of the catalog                                                                                                                                                                                                                                                                |
| chained\_lists\[0]\[parent\_catalog\_id] | int          | ID of the parent catalog                                                                                                                                                                                                                                                         |
| tracking\_callback                       | string       | A JavaScript callback function that executes on the page containing a Website Chat Button and a Kommo webform when data is submitted. This value is returned for fields of the `tracking_data` type.                                                                             |
| search\_in                               | string\|null | ID of the catalog or symbolic code (contacts, companies, contacts\_and\_companies) for a field of the `linked_entity` type.                                                                                                                                                      |

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "kommo-api-references",
    "version": "1.0"
  },
  "servers": [
    {
      "url": "https://{subdomain}.kommo.com",
      "variables": {
        "subdomain": {
          "default": "subdomain"
        }
      }
    }
  ],
  "components": {
    "securitySchemes": {
      "sec0": {
        "type": "oauth2",
        "flows": {}
      }
    }
  },
  "security": [
    {
      "sec0": []
    }
  ],
  "paths": {
    "/api/v4/{entity_type}/custom_fields": {
      "post": {
        "summary": "Add custom fields",
        "description": "This method allows to add singular or multiple custom fields to an entity(leads, companies, contacts)",
        "operationId": "add-custom-fields",
        "parameters": [
          {
            "name": "entity_type",
            "in": "path",
            "description": "Entity type",
            "schema": {
              "type": "string",
              "enum": [
                "leads",
                "companies",
                "contacts"
              ]
            },
            "required": true
          },
          {
            "name": "Content-Type",
            "in": "header",
            "schema": {
              "type": "string",
              "default": "application/json"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "RAW_BODY": {
                    "type": "array",
                    "items": {
                      "properties": {
                        "type": {
                          "type": "string",
                          "description": "Field type. Available field types: https://developers.kommo.com/reference/custom-fields#available-field-types"
                        },
                        "name": {
                          "type": "string",
                          "description": "Field name"
                        },
                        "code": {
                          "type": "string",
                          "description": "The field code used to update a value within an entity without passing the field ID"
                        },
                        "sort": {
                          "type": "integer",
                          "description": "Field sorting"
                        },
                        "group_id": {
                          "type": "string",
                          "description": "Field group ID"
                        },
                        "is_api_only": {
                          "type": "boolean",
                          "description": "Defines if the field is editable only via the API"
                        },
                        "required_statuses": {
                          "type": "array",
                          "items": {
                            "properties": {
                              "status_id": {
                                "type": "integer",
                                "description": "The ID of the stage at which the field becomes mandatory"
                              },
                              "pipeline_id": {
                                "type": "integer",
                                "description": "The ID of the pipeline at which the field becomes mandatory"
                              }
                            },
                            "type": "object"
                          },
                          "description": "Mandatory fields for changing the lead stage"
                        },
                        "remind": {
                          "type": "string",
                          "description": "When to send birthday reminders (`never` — never, `day` — one day before, `week` — one week before, `month` — one month before). Available for the field type `birthday`",
                          "enum": [
                            "never",
                            "day",
                            "week",
                            "month"
                          ]
                        },
                        "enums": {
                          "type": "array",
                          "items": {
                            "properties": {
                              "value": {
                                "type": "string",
                                "description": "Enum value"
                              },
                              "sort": {
                                "type": "integer",
                                "description": "Enum sort "
                              },
                              "code": {
                                "type": "string",
                                "description": "Enum value code"
                              }
                            },
                            "type": "object"
                          },
                          "description": "Possible values of the field. Available for the types `select`/`multiselect`/`radiobutton`"
                        },
                        "tracking_callback": {
                          "type": "string",
                          "description": "JavaScript callback function that will be executed on the page containing the Website Chat Button and Kommo webform when the data is submitted. Available for the field type `tracking_data`"
                        },
                        "hidden_statuses": {
                          "type": "array",
                          "items": {
                            "properties": {
                              "status_id": {
                                "type": "integer",
                                "description": "The ID of the stage in which the field is hidden"
                              },
                              "pipeline_id": {
                                "type": "integer",
                                "description": "The ID of the pipeline in which the field is hidden"
                              }
                            },
                            "type": "object"
                          },
                          "description": "Field visibility settings. Fields are hidden in the interface depending on the lead stage"
                        },
                        "chained_lists": {
                          "type": "array",
                          "items": {
                            "properties": {
                              "title": {
                                "type": "string",
                                "description": "The name of the linked list displayed in the lead card."
                              },
                              "catalog_id": {
                                "type": "integer",
                                "description": "ID of the catalog"
                              },
                              "parent_catalog_id": {
                                "type": "integer",
                                "description": "ID of the parent catalog"
                              }
                            },
                            "type": "object"
                          },
                          "description": "Configuration for a `chained_list` field. This property is returned only when retrieving the list of lead fields. Available for the field type `chained_list`"
                        },
                        "search_in": {
                          "type": "string",
                          "description": "The ID of the linked list or its symbolic code (`contacts`, `companies`, `contacts_and_companies`). Available for the field type `linked_entity`"
                        },
                        "currency": {
                          "type": "string",
                          "description": "The currency code for the field. Available for the field type `monetary`"
                        }
                      },
                      "type": "object",
                      "required": [
                        "type",
                        "name"
                      ]
                    }
                  }
                }
              },
              "examples": {
                "Request example": {
                  "value": [
                    {
                      "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
                        }
                      ]
                    }
                  ]
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "201",
            "content": {
              "application/json": {
                "examples": {
                  "Request successful": {
                    "value": "{\n    \"_total_items\": 1,\n    \"_embedded\": {\n        \"custom_fields\": [\n            {\n                \"name\": \"multi select\",\n                \"type\": \"multiselect\",\n                \"sort\": 510,\n                \"settings\": null,\n                \"is_predefined\": false,\n                \"id\": 4457223,\n                \"remind\": null,\n                \"is_api_only\": false,\n                \"enums\": [\n                    {\n                        \"value\": \"Value 1\",\n                        \"sort\": 1,\n                        \"id\": 3778801\n                    },\n                    {\n                        \"value\": \"Value 2\",\n                        \"sort\": 2,\n                        \"id\": 3778803\n                    }\n                ],\n                \"group_id\": null,\n                \"required_statuses\": [\n                    {\n                        \"status_id\": 20540473,\n                        \"pipeline_id\": 16056\n                    },\n                ],\n                \"_links\": {\n                    \"self\": {\n                        \"href\": \"https://example.kommo.com/api/v4/custom_fields/4457223/\"\n                    }\n                }\n            }\n        ]\n    }\n}"
                  }
                }
              }
            }
          },
          "400": {
            "description": "400",
            "content": {
              "application/json": {
                "examples": {
                  "Invalid data given. Details are available in the request response": {
                    "value": "{}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "401": {
            "description": "401",
            "content": {
              "text/plain": {
                "examples": {
                  "User is not authorized": {
                    "value": ""
                  }
                }
              }
            }
          },
          "422": {
            "description": "422",
            "content": {
              "text/plain": {
                "examples": {
                  "Request can not be processed. Details are available in the request response": {
                    "value": ""
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "x-readme": {
    "headers": [],
    "explorer-enabled": true,
    "proxy-enabled": true
  },
  "x-readme-fauxas": true
}
```