Поля и группы полей

Дополнительное поле – это пользовательское поле, которое можно задать для контакта, сделки, компании, покупателя, сегмента и каталога. Оно будет отображаться в карточке одной из перечисленных сущностей.

Возможные типы дополнительных полей:

Тип Название
text Текст
numeric Число
checkbox Флаг
select Список
multiselect Мультисписок
date Дата
url Ссылка
textarea Текстовая область
radiobutton Переключатель
streetaddress Короткий адрес
smart_address Адрес
birthday День рождения
legal_entity Юр. лицо
date_time Дата и время
org_legal_name Организация
price Цена
category Категория
items Предметы

Поддерживаемые сущностями типы полей:

Контакт Сделка Компания Покупатель Каталог
Текст + + + + +
Число + + + + +
Флаг + + + + +
Список + + + + +
Мультисписок + + + + +
Дата + + + + +
Ссылка + + + + +
Текстовая область + + + + +
Переключатель + + + + +
Короткий адрес + + +
Адрес + + +
День рождения + + +
Юр. лицо + + +
Дата и время + + + +
Организация + + +
Цена +
Категория +
Предметы +

Список дополнительных полей

Метод позволяет получить список дополнительных полей для указанной сущности

URL метода:

GET /api/v4/{entity_type:leads|contacts|customers|companies}/custom_fields

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

GET /api/v4/customers/segments/custom_fields

Пример запроса:


GET http://example.amocrm.ru/api/v4/leads/custom_fields

Пример ответа:


{
    "_total_items": 2,
    "_page": 1,
    "_page_count": 10,
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/leads/custom_fields?limit=2&page=1"
        },
        "next": {
            "href": "https://example.amocrm.ru/api/v4/leads/custom_fields?limit=2&page=2"
        },
        "last": {
            "href": "https://example.amocrm.ru/api/v4/leads/custom_fields?limit=2&page=10"
        }
    },
    "_embedded": {
        "custom_fields": [
            {
                "id": 4439091,
                "name": "Пример текстового поля",
                "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.amocrm.ru/api/v4/custom_fields/4439091/"
                    }
                }
            },
            {
                "id": 4440043,
                "name": "Пример поля с типом 'data'",
                "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.amocrm.ru/api/v4/custom_fields/4440043/"
                    }
                }
            }
        ]
    }
}

Создание дополнительного поля

Метод позволяет создавать дополнительное поле для указанной сущности.

URL метода:

POST /api/v4/{entity_type:leads|contacts|customers|companies}/custom_fields

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

При создании дополнительного поля основным параметром, от которого будут формироваться данные для запроса, является ключ type.

Например, если мы пытаемся создать дополнительное поле с типом “multiselect” (Мультисписок), то мы должны передать вместе с запросом список возможных параметров для этого мультисписка (enums).

Список параметров, которые доступны для каждого типа дополнительного поля, описаны ниже.

Тип поля “text” (Текст):

Параметр Тип Обязательность Описание
name string Обязательное Название
sort integer Не обязательное Положение в группе
group_id string Не обязательное ID группы полей
is_api_only bool Не обязательное Изменение значения поля только по api
required_statuses array Не обязательное Обязательно в статусах
settings(только для каталогов) object Не обязательное Доп. настройки для полей каталогов

Тип поля “numeric” (Число):

Параметр Тип Обязательность Описание
name string Обязательное Название
sort integer Не обязательное Положение в группе
group_id string Не обязательное ID группы полей
is_api_only bool Не обязательное Изменение значения поля только по api
required_statuses array Не обязательное Обязательно в статусах
settings(только для каталогов) object Не обязательное Доп. настройки для полей каталогов

Тип поля “checkbox” (Флаг):

Параметр Тип Обязательность Описание
name string Обязательное Название
sort integer Не обязательное Положение в группе
group_id string Не обязательное ID группы полей
is_api_only bool Не обязательное Изменение значения поля только по api
required_statuses array Не обязательное Обязательно в статусах
settings(только для каталогов) object Не обязательное Доп. настройки для полей каталогов

Тип поля “select” (Список):

Параметр Тип Обязательность Описание
name string Обязательное Название
sort integer Не обязательное Положение в группе
group_id string Не обязательное ID группы полей
is_api_only bool Не обязательное Изменение значения поля только по api
required_statuses array Не обязательное Обязательно в статусах
settings(только для каталогов) object Не обязательное Доп. настройки для полей каталогов

Тип поля “multiselect” (Мультисписок):

Параметр Тип Обязательность Описание
name string Обязательное Название
enums array Обязательное Возможные значения
sort integer Не обязательное Положение в группе
group_id string Не обязательное ID группы полей
is_api_only bool Не обязательное Изменение значения поля только по api
required_statuses array Не обязательное Обязательно в статусах
settings(только для каталогов) object Не обязательное Доп. настройки для полей каталогов

Тип поля “date” (Дата):

Параметр Тип Обязательность Описание
name string Обязательное Название
sort integer Не обязательное Положение в группе
group_id string Не обязательное ID группы полей
is_api_only bool Не обязательное Изменение значения поля только по api
required_statuses array Не обязательное Обязательно в статусах
settings(только для каталогов) object Не обязательное Доп. настройки для полей каталогов

Тип поля “url” (Ссылка):

Параметр Тип Обязательность Описание
name string Обязательное Название
sort integer Не обязательное Положение в группе
group_id string Не обязательное ID группы полей
is_api_only bool Не обязательное Изменение значения поля только по api
required_statuses array Не обязательное Обязательно в статусах
settings(только для каталогов) object Не обязательное Доп. настройки для полей каталогов

Тип поля “textarea” (Текстовая область):

Параметр Тип Обязательность Описание
name string Обязательное Название
sort integer Не обязательное Положение в группе
group_id string Не обязательное ID группы полей
is_api_only bool Не обязательное Изменение значения поля только по api
required_statuses array Не обязательное Обязательно в статусах
settings(только для каталогов) object Не обязательное Доп. настройки для полей каталогов

Тип поля “radiobutton” (Переключатель):

Параметр Тип Обязательность Описание
name string Обязательное Название
enums array Обязательное Возможные значения
sort integer Не обязательное Положение в группе
group_id string Не обязательное ID группы полей
is_api_only bool Не обязательное Изменение значения поля только по api
required_statuses array Не обязательное Обязательно в статусах
settings(только для каталогов) object Не обязательное Доп. настройки для полей каталогов

Тип поля “streetaddress” (Короткий адрес):

Параметр Тип Обязательность Описание
name string Обязательное Название
sort integer Не обязательное Положение в группе
group_id string Не обязательное ID группы полей
is_api_only bool Не обязательное Изменение значения поля только по api
required_statuses array Не обязательное Обязательно в статусах

Тип поля “smart_address” (Адрес):

Параметр Тип Обязательность Описание
name string Обязательное Название
sort integer Не обязательное Положение в группе
group_id string Не обязательное ID группы полей
is_api_only bool Не обязательное Изменение значения поля только по api
required_statuses array Не обязательное Обязательно в статусах

Тип поля “День рождения” (birthday):

Параметр Тип Обязательность Описание
name string Обязательное Название
remind integer Обязательное Когда напомнить о дне рождении
sort integer Не обязательное Положение в группе
group_id string Не обязательное ID группы полей
is_api_only bool Не обязательное Изменение значения поля только по api
required_statuses array Не обязательное Обязательно в статусах

Тип поля “legal_entity” (Юр. лицо):

Параметр Тип Обязательность Описание
name string Обязательное Название
sort integer Не обязательное Положение в группе
group_id string Не обязательное ID группы полей
is_api_only bool Не обязательное Изменение значения поля только по api
required_statuses array Не обязательное Обязательно в статусах

Тип поля “date_time” (Дата и время):

Параметр Тип Обязательность Описание
name string Обязательное Название
sort integer Не обязательное Положение в группе
group_id string Не обязательное ID группы полей
is_api_only bool Не обязательное Изменение значения поля только по api
required_statuses array Не обязательное Обязательно в статусах

Также можно передать необязательный ключ request_id, чтобы более точно определять, какой элемент мог вызвать ошибки. Поля с типом День рождение и Адрес – могут быть созданы только один раз на каждый тип сущности.

Поле remind для поля День рождения должен соответствовать следующим требованиям:

Ключ Тип Описание Ограничения
remind integer Когда напомнить о дне рождении [0 – не напоминать, 1 – в день события, 2 – за неделю, 3 – за месяц]

Если параметр group_id = null, то поле будет добавлено в группу Основное

Если параметр sort не передан, то будет установлена сортировка по умолчанию 500

Каждый объект из массива enums должен соответствовать следующим требованиям:

Ключ Тип Описание Ограничения
id integer Идентификатор возможного значения Если не передан, то создать
value string Название возможного значения Не пустое
sort integer Порядок среди других возможных значений Натуральное число

Каталоги и покупатели не поддерживают поле required_statuses

Каждый объект из массива required_statuses должен соответствовать следующим требованиям:

Ключ Тип Описание Обязательность
pipeline_id integer Идентификатор воронки сделок Обязательное
status_id integer Идентификатор наименьшего статуса сделки, где поле будет обязательно Обязательное

Поле status_id должно содержать в себе идентификатор наименьшего статуса воронки, после которого поле будет обязательно в дальнейших статусах
Например, если у нас есть воронка со статусами:
status1 -> status2 -> status3 -> status4 -> status_win

При status_id = status3 поле станет обязательным и в последующих статусах [status4, status_win]
Нельзя одновременно выставить поле required_statuses и флаг is_api_only
Объект settings должен соответствовать следующим требованиям:

Ключ Тип Описание Ограничения
is_visible boolean Видимость поля default: true
is_deletable boolean Возможность удаления из интерфейса default: true
is_required boolean Обязательность заполнения поля при создании элемента каталога default: false

Пример создания дополнительного поля:


POST https://example.amocrm.ru/api/v4/leads/custom_fields
Content-Type: application/json

[
    {
        "name": "multi select",
        "type": "multiselect",
        "sort": 510,
        "required_statuses": [
            {
                "pipeline_id": 16056,
                "status_id": 20540473
            }
        ],
        "enums": [
            {
                "value": “Значение 1",
                "sort": 1
            },
            {
                "value": "Значение 2",
                "sort": 2
            }
        ]
    }
]

Пример ответа:


{
    "_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": "Значение 1",
                        "sort": 1,
                        "id": 3778801
                    },
                    {
                        "value": "Значение 2",
                        "sort": 2,
                        "id": 3778803
                    }
                ],
                "group_id": null,
                "required_statuses": [
                    {
                        "status_id": 20540473,
                        "pipeline_id": 16056
                    },
                ],
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/custom_fields/4457223/"
                    }
                }
            }
        ]
    }
}

Редактирование дополнительного поля

Метод позволяет редактировать следующие параметры у дополнительного поля:

– Название
– Возможность изменения только по API
– Группу
– Обязательные статусы (только для сделок)
– Положение поля в группе
– Возможные значения (для 4, 5, 10 типов полей)
– Дополнительные настройки поля (для 14 типов полей и для полей каталогов)

URL метода

PATCH /api/v4/{entity_type}/custom_fields/{id}

Параметры GET

Параметр Тип Описание
entity_type string Тип сущности, для которой редактируется дополнительное поле
id int Идентификатор дополнительного поля

Пример редактирования дополнительного поля:


PATCH https://example.amocrm.ru/api/v4/leads/custom_fields/23418
Content-Type: application/json

{
    "name": "Новое имя для дополнительного поля",
    "sort": 560,
    "is_api_only": true,
    "group_id": "new_group"
}

Удаление дополнительного поля

Метод позволяет удалить дополнительного поле по его идентификатору

URL метода

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

Параметры GET

Параметр Тип Описание
entity_type string Тип сущности, для которой редактируется дополнительное поле
id int Идентификатор дополнительного поля

Пример редактирования дополнительного поля:


DELETE https://example.amocrm.ru/api/v4/leads/custom_fields/23418

При успешном удалении сервер вернет HTTP-code – 202 Accepted

Список групп дополнительных полей

Метод позволяет получить имеющиеся списки групп дополнительных полей для указанной сущности

URL метода

GET /api/v4/{entity_type}/custom_fields/groups

Параметры GET

Параметр Тип Описание
entity_type string Тип сущности, для которой редактируется дополнительное поле

Пример ответа:


{
    "_total_items": 3,
    "_embedded": {
        "custom_field_groups": [
            {
                "id": "default",
                "name": "Основное",
                "is_predefined": true,
                "type": "custom_field_group",
                "entity_type": "leads",
                "sort": 0,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/leads/custom_fields/groups/default/"
                    }
                }
            },
            {
                "id": "statistic",
                "name": "Статистика",
                "is_predefined": true,
                "type": "linked_group",
                "entity_type": "leads",
                "sort": 1,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/leads/custom_fields/groups/statistic/"
                    }
                }
            },
            {
                "id": "1027",
                "name": "Example",
                "is_predefined": true,
                "type": "linked_group",
                "entity_type": "leads",
                "sort": 2,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/leads/custom_fields/groups/1027/"
                    }
                }
            }
        ]
    }
}

Создание группы дополнительных полей

Метод позволяет создавать новую группу дополнительных полей для переданного типа сущности

URL метода

POST /api/v4/{entity_type}/custom_fields/groups

Параметры GET

Параметр Тип Описание
entity_type string Тип сущности, для которой редактируется дополнительное поле

Параметры POST

Параметр Тип Описание Обязательность
name string Название группы Обязательно
sort integer Положение группы относительно других групп Не обязательно

Пример создания группы дополнительных полей:


POST https://example.amocrm.ru/api/v4/leads/custom_fields/groups
Content-Type: application/json

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

Пример ответа:


{
    "_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.amocrm.ru/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.amocrm.ru/api/v4/leads/custom_fields/groups/leads_609315/"
                    }
                }
            }
        ]
    }
}

Редактирование группы дополнительных полей

Метод позволяет редактировать группу дополнительных полей.

URL метода

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

Параметры GET

Параметр Тип Описание
entity_type string Тип сущности, для которой редактируется дополнительное поле
id int Идентификатор группы дополнительных полей

Параметры доступные для редактирования:
– name
– sort

Пример редактирования группы дополнительных полей


PATCH /api/v4/leads/custom_fields/groups/leads_2745
Content-Type: application/json

{
    "sort": 6
}

Пример ответа:


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

Удаление группы дополнительных полей

Метод позволяет удалить группу дополнительных полей по идентификатору для переданной сущности

URL метода

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

Параметры GET

Параметр Тип Описание
entity_type string Тип сущности, для которой редактируется дополнительное поле
id int Идентификатор группы дополнительных полей

Пример удаления группы дополнительных полей


DELETE https://example.amocrm.ru/api/v4/leads/custom_fields/groups/leads_2731

При успешном удалении группы дополнительных полей сервер в ответ вернет пустое тело и HTTP-code – 200 (OK)

Смотрите также

КОДЫ ОШИБОК API