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

В данном разделе описывается работа с дополнительными полями и группами полей через API

Оглавление

Общая информация

  • Пользовательские поля могут быть созданы для сделок, контактов, компаний, списков, сегментов и покупателей
  • Адреса методов зависят от сущности

Список полей сущности

Метод

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

Описание

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

Ограничения

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

Заголовок типа данных при успешном результате

Content-Type: application/hal+json

Заголовок типа данных при ошибке

Content-Type: application/problem+json

HTTP коды ответа

Код ответа Условие
200 Запрос выполнен успешно
422 Запрос не может быть обработан, подробности в теле ответа
401 Пользователь не авторизован
400 Переданы некорректные данные. Подробности доступны в теле ответа

Параметры ответа

Метод возвращает коллекцию моделей полей, рассмотрим ниже свойства поля. Состав полей модели может отличаться в зависимости от сущности.

Параметр Тип данных Описание
id int ID поля
name string Название поля
code string Код поля, по-которому можно обновлять значение в сущности, без передачи ID поля
sort int Сортировка поля
type int Тип поля. Список доступных полей
entity_type string Тип сущности (leads, contacts, companies, segments, customers, catalogs)
is_predefined bool Является ли поле предустановленным. Данный ключ возвращается только при получении списка полей контактов и компаний
is_deletable bool Доступно ли поле для удаления. Данный ключ возвращается только при получении списка полей контактов и компаний
is_visible bool Отображается ли поле в интерфейсе списка. Данный ключ возвращается только при получении списка полей списков (каталогов)
is_deletable bool Можно ли удалить поле из интерфейса. Данный ключ возвращается только при получении списка полей списков (каталогов)
is_required bool Обязательно ли поле для заполнения при создании элемента списка. Данный ключ возвращается только при получении списка полей списков (каталогов)
settings array|null Настройки поля. Данный ключ возвращается только при получении списка полей списков (каталогов)
remind string|null Когда напоминать о дне рождения (never – никогда, day – за день, week – за неделю, month – за месяц). Значение данного поля доступно только для поля типа birthday. Данный ключ возвращается только при получении списка полей контактов, сделок и компаний
enums array|null Доступные значения для поля. Значение данного поля доступно только для полей с поддержкой enum
enums[0] object Доступное значение для поля
enums[0][id] int ID значения
enums[0][value] string Значение
enums[0][sort] int Сортировка значения
nested array|null Вложенные значения. Данные ключ возвращается только при получении списка полей каталогов и значение доступно только для поля category
nested[0] object Модель вложенного значения. Данные ключ возвращается только при получении списка полей каталогов и значение доступно только для поля category
nested[0][id] int ID вложенного значения. Данные ключ возвращается только при получении списка полей каталогов и значение доступно только для поля category
nested[0][parent_id] int ID родительского вложенного значения. Данные ключ возвращается только при получении списка полей каталогов и значение доступно только для поля category
nested[0][value] string Значение вложенного значения. Данные ключ возвращается только при получении списка полей каталогов и значение доступно только для поля category
nested[0][sort] int Сортировка вложенного значения. Данные ключ возвращается только при получении списка полей каталогов и значение доступно только для поля category
is_api_only bool Доступно ли поле для редактирования только через API. Данный ключ возвращается только при получении списка полей контактов, сделок и компаний
group_id string|null ID группы полей, в которой состоит данное поле. Данный ключ возвращается только при получении списка полей контактов, сделок, покупателей и компаний
required_statuses array|null Обязательные поля для смены этапов. Данный ключ возвращается только при получении списка полей контактов, сделок и компаний
required_statuses[0] object Модель обязательного поля для смены этапов. Данный ключ возвращается только при получении списка полей контактов, сделок и компаний
required_statuses[0][status_id] int ID статуса, для перехода в который данное поле обязательно к заполнению. Данный ключ возвращается только при получении списка полей контактов, сделок и компаний
required_statuses[0][pipeline_id] int ID воронки, для перехода в который данное поле обязательно к заполнению. Данный ключ возвращается только при получении списка полей контактов, сделок и компаний

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

        
{
    "_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/"
                    }
                }
            }
        ]
    }
}
        
    

Получение поля сущности по его ID

Метод

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}

Описание

Метод позволяет получить поле сущности по его ID.

Ограничения

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

Заголовок типа данных при успешном результате

Content-Type: application/hal+json

Заголовок типа данных при ошибке

Content-Type: application/problem+json

HTTP коды ответа

Код ответа Условие
200 Запрос выполнен успешно
422 Запрос не может быть обработан, подробности в теле ответа
401 Пользователь не авторизован

Параметры ответа

Метод возвращает модель поля, рассмотрим ниже свойства поля. Состав полей модели может отличаться в зависимости от сущности.

Параметр Тип данных Описание
id int ID поля
name string Название поля
code string Код поля, по-которому можно обновлять значение в сущности, без передачи ID поля
sort int Сортировка поля
type int Тип поля. Список доступных полей
entity_type string Тип сущности (leads, contacts, companies, segments, customers, catalogs)
is_predefined bool Является ли поле предустановленным. Данный ключ возвращается только при получении поля контакта и компании
is_deletable bool Доступно ли поле для удаления. Данный ключ возвращается только при получении поля контакта и компании
is_visible bool Отображается ли поле в интерфейсе списка. Данный ключ возвращается только при получении списка полей списков (каталогов)
is_deletable bool Можно ли удалить поле из интерфейса. Данный ключ возвращается только при получении списка полей списков (каталогов)
is_required bool Обязательно ли поле для заполнения при создании элемента списка. Данный ключ возвращается только при получении списка полей списков (каталогов)
settings array|null Настройки поля. Данный ключ возвращается только при получении поля списка (каталога)
remind string|int Когда напоминать о дне рождения (never – никогда, day – за день, week – за неделю, month – за месяц). Значение данного поля доступно только для поля типа birthday. Данный ключ возвращается только при получении поля контакта, сделки и компании
enums array|null Доступные значения для поля. Значение данного поля доступно только для полей с поддержкой enum
enums[0] object Доступное значение для поля
enums[0][id] int ID значения
enums[0][value] string Значение
enums[0][sort] int Сортировка значения
is_api_only bool Доступно ли поле для редактирования только через API. Данный ключ возвращается только при получении поля контакта, сделки и компании
group_id string|null ID группы полей, в которой состоит данное поле. Данный ключ возвращается только при получении поля контакта, покупателя, сделки и компании
required_statuses array|null Обязательные поля для смены этапов. Данный ключ возвращается только при получении поля контакта, сделки и компании
required_statuses[0] object Модель обязательного поля для смены этапов. Данный ключ возвращается только при получении поля контакта, сделки и компании
required_statuses[0][status_id] int ID статуса, для перехода в который данное поле обязательно к заполнению. Данный ключ возвращается только при получении поля контакта, сделки и компании
required_statuses[0][pipeline_id] int ID воронки, для перехода в который данное поле обязательно к заполнению. Данный ключ возвращается только при получении поля контакта, сделки и компании
nested array|null Вложенные значения. Данные ключ возвращается только при получении списка полей каталогов и значение доступно только для поля category
nested[0] object Модель вложенного значения. Данные ключ возвращается только при получении списка полей каталогов и значение доступно только для поля category
nested[0][id] int ID вложенного значения. Данные ключ возвращается только при получении списка полей каталогов и значение доступно только для поля category
nested[0][parent_id] int ID родительского вложенного значения. Данные ключ возвращается только при получении списка полей каталогов и значение доступно только для поля category
nested[0][value] string Значение вложенного значения. Данные ключ возвращается только при получении списка полей каталогов и значение доступно только для поля category
nested[0][sort] int Сортировка вложенного значения. Данные ключ возвращается только при получении списка полей каталогов и значение доступно только для поля category

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

        
{
    "id": 3,
    "name": "Телефон",
    "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.amocrm.ru/api/v4/contacts/custom_fields/3"
        }
    }
}
        
    

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

Метод

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

Описание

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

Ограничения

Метод доступен только администраторам аккаунта.

Заголовок запроса

Content-Type: application/json

Параметры запроса

Для создания поля необходимо передать модель поля.

Параметр Тип данных Описание Обязательное Поддерживаемы типы полей
type string Тип поля. Доступные типы полей Доступно для всех полей
name string Название поля Доступно для всех полей
code string Код поля, по-которому можно обновлять значение в сущности, без передачи ID поля Доступно для всех полей
sort int Сортировка поля в группе полей Доступно для всех полей
group_id string ID группы полей Доступно для всех полей контактов, компаний, сделок и покупателей
is_api_only bool Доступно ли поле для редактирования только через API Доступно для всех полей контактов, компаний и сделок
required_statuses array|null Обязательные поля для смены этапа сделки Доступно для всех полей контактов, компаний, сделок и покупателей
required_statuses[0] object Модель обязательного поля для смены этапа сделки Доступно для всех полей контактов, компаний, сделок и покупателей
required_statuses[0][status_id] int ID статуса, для перехода в который данное поле обязательно к заполнению Доступно для всех полей контактов, компаний, сделок и покупателей
required_statuses[0][pipeline_id] int ID воронки, для перехода в который данное поле обязательно к заполнению Доступно для всех полей контактов, компаний, сделок и покупателей
settings object Настройки поля Доступно для всех полей списков (каталогов)
is_visible bool Отображается ли поле в интерфейсе списка Доступно для всех полей списков (каталогов)
is_required bool Обязательно ли поле для заполнения при создании элемента списка Доступно для всех полей списков (каталогов)
remind string|null Когда напоминать о дне рождения (never – никогда, day – за день, week – за неделю, month – за месяц) Доступно для типа поля birthday
enums array Доступные значения поля Доступно для полей:

  • multiselect
  • radiobutton
  • select
enums[0] object Модель доступного значения поля Доступно для полей:

  • multiselect
  • radiobutton
  • select
enums[0][value] string Значение одного из доступных значения поля Доступно для полей:

  • multiselect
  • radiobutton
  • select
enums[0][sort] string Сортировка среди других доступных значений поля Доступно для полей:

  • multiselect
  • radiobutton
  • select
nested array Вложенные значения Доступно для полей:

  • category
nested[0] object Модель вложенного значения Доступно для полей:

  • category
nested[0][id] int ID вложенного значения Доступно для полей:

  • category
nested[0][parent_id] int ID родительского вложенного значения Доступно для полей:

  • category
nested[0][value] string Значение вложенного значения Доступно для полей:

  • category
nested[0][sort] int Сортировка вложенного значения Доступно для полей:

  • category
nested[0][request_id] string Временный идентификатор вложенного значения, должен быть уникальным в пределах запроса, нигде не сохраняется, используется для создания больше одного уровня вложенности за запрос Доступно для полей:

  • category
nested[0][parent_request_id] string Временный идентификатор родителя вложенного значения, используется только на момент запроса, нигде не сохраняется, определяет на какой уровень вложенности добавлять элемент, если родительский элемент еще не был создан Доступно для полей:

  • category

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

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

Заголовок типа данных при успешном результате

Content-Type: application/hal+json

Заголовок типа данных при ошибке

Content-Type: application/problem+json

HTTP коды ответа

Код ответа Условие
201 Запрос выполнен успешно
422 Запрос не может быть обработан, подробности в теле ответа
401 Пользователь не авторизован
400 Переданы некорректные данные. Подробности доступны в теле ответа

Параметры ответа

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

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

        
{
    "_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/"
                    }
                }
            }
        ]
    }
}
        
    

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

Метод

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

Описание

Метод позволяет редактировать сущности пакетно.
Также вы можете добавить ID поля в метод для редактирования конкретной сущности (например /api/v4/leads/custom_fields/{id}).
При редактировании пакетно передается массив из объектов, при редактировании одного поля, передается просто модель.

Ограничения

Метод доступен только администраторам аккаунта.

Заголовок запроса

Content-Type: application/json

Параметры запроса

Для редактирования поля необходимо передать модель поля.

Параметр Тип данных Описание Обязательное Поддерживаемы типы полей
name string Название поля Доступно для всех полей
code string Код поля, по-которому можно обновлять значение в сущности, без передачи ID поля Доступно для всех полей
sort int Сортировка поля в группе полей Доступно для всех полей
group_id string ID группы полей Доступно для всех полей контактов, компаний, сделок и покупателей
is_api_only bool Доступно ли поле для редактирования только через API Доступно для всех полей контактов, компаний и сделок
required_statuses array|null Обязательные поля для смены этапа сделки Доступно для всех полей контактов, компаний, сделок и покупателей
required_statuses[0] object Модель обязательного поля для смены этапа сделки Доступно для всех полей контактов, компаний, сделок и покупателей
required_statuses[0][status_id] int ID статуса, для перехода в который данное поле обязательно к заполнению Доступно для всех полей контактов, компаний, сделок и покупателей
required_statuses[0][pipeline_id] int ID воронки, для перехода в который данное поле обязательно к заполнению Доступно для всех полей контактов, компаний, сделок и покупателей
settings object Настройки поля Доступно для всех полей списков (каталогов)
is_visible bool Отображается ли поле в интерфейсе списка Доступно для всех полей списков (каталогов)
is_required bool Обязательно ли поле для заполнения при создании элемента списка Доступно для всех полей списков (каталогов)
remind string|null Когда напоминать о дне рождения (never – никогда, day – за день, week – за неделю, month – за месяц) Доступно для типа поля birthday
enums array Доступные значения поля Доступно для полей:

  • multiselect
  • radiobutton
  • select
enums[0] object Модель доступного значения поля Доступно для полей:

  • multiselect
  • radiobutton
  • select
enums[0][value] string Значение одного из доступных значения поля Доступно для полей:

  • multiselect
  • radiobutton
  • select
enums[0][sort] string Сортировка среди других доступных значений поля Доступно для полей:

  • multiselect
  • radiobutton
  • select
nested array Вложенные значения Доступно для полей:

  • category
nested[0] object Модель вложенного значения Доступно для полей:

  • category
nested[0][id] int ID вложенного значения. Для создания нового значение не нужно передавать Доступно для полей:

  • category
nested[0][parent_id] int ID родительского вложенного значения Доступно для полей:

  • category
nested[0][value] string Значение вложенного значения Доступно для полей:

  • category
nested[0][sort] int Сортировка вложенного значения Доступно для полей:

  • category
nested[0][request_id] string Временный идентификатор вложенного значения, должен быть уникальным в пределах запроса, нигде не сохраняется, используется для создания больше одного уровня вложенности за запрос Доступно для полей:

  • category
nested[0][parent_request_id] string Временный идентификатор родителя вложенного значения, используется только на момент запроса, нигде не сохраняется, определяет на какой уровень вложенности добавлять элемент, если родительский элемент еще не был создан Доступно для полей:

  • category

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

В примере ниже обновим 2 поля у каталога, сделав запрос к методу /api/v4/catalogs/{catalog_id}/custom_fields.

        
[
    {
        "id": 1278898087,
        "name": "Новое имя для дополнительного поля",
        "sort": 560,
        "is_visible": false,
        "is_required": true
    },
    {
        "id": 1278898091,
        "name": "Новое имя для поля Категория",
        "nested": [
            {
                "id": 197,
                "parent_id": null,
                "value": "категория 1",
                "sort": 0
            },
            {
                "parent_id": null,
                "value": "новая категория 2",
                "sort": 1
            },
            {
                "parent_id": 197,
                "value": "новая подкатегория 1",
                "sort": 1
            }
        ]
    }
]
        
    

Заголовок типа данных при успешном результате

Content-Type: application/hal+json

Заголовок типа данных при ошибке

Content-Type: application/problem+json

HTTP коды ответа

Код ответа Условие
201 Запрос выполнен успешно
422 Запрос не может быть обработан, подробности в теле ответа
401 Пользователь не авторизован
400 Переданы некорректные данные. Подробности доступны в теле ответа

Параметры ответа

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

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

        
{
    "_total_items": 2,
    "_embedded": {
        "custom_fields": [
            {
                "id": 1278898087,
                "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.amocrm.ru/api/v4/catalogs/1095/custom_fields/1278898087"
                    }
                }
            },
            {
                "id": 1278898091,
                "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": "категория 1",
                        "sort": 0
                    },
                    {
                        "id": 215,
                        "parent_id": 197,
                        "value": "новая подкатегория 1",
                        "sort": 0
                    },
                    {
                        "id": 217,
                        "parent_id": 197,
                        "value": "новая категория 2",
                        "sort": 1
                    }
                ],
                "entity_type": "catalogs",
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/catalogs/1095/custom_fields/1278898091"
                    }
                }
            }
        ]
    }
}
        
    

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

Метод

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}

Описание

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

Ограничения

  • Метод доступен только с правами администратора аккаунта
  • Значения поля будут удалены

Заголовок запроса

Content-Type: application/json

HTTP коды ответа

Код ответа Условие
204 Поле было успешно удалено
403 Не хватает прав для вызова данного метода
401 Пользователь не авторизован
400 Переданы некорректные данные. Подробности доступны в теле ответа

Параметры ответа

Метод не возвращает тело

Список групп полей сущности

Метод

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

Описание

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

Ограничения

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

Заголовок типа данных при успешном результате

Content-Type: application/hal+json

Заголовок типа данных при ошибке

Content-Type: application/problem+json

HTTP коды ответа

Код ответа Условие
200 Запрос выполнен успешно
401 Пользователь не авторизован
400 Переданы некорректные данные. Подробности доступны в теле ответа

Параметры ответа

Метод возвращает коллекцию моделей групп полей, рассмотрим ниже свойства группы полей.

Параметр Тип данных Описание
id string ID группы полей
name string Название группы полей
sort int Сортировка группы полей в карточке сущности
entity_type string Тип сущности (leads, contacts, companies, customers)
is_predefined bool Является ли группа предустановленной. Такие группы нельзя удалить
type string Тип группы (linked_group – группы товаров, custom_field_group – группы полей)

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

        
{
    "id": "leads_29741591099841",
    "name": "Группа полей",
    "is_predefined": false,
    "type": "custom_field_group",
    "entity_type": "leads",
    "sort": 3,
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/leads/custom_fields/groups/leads_29741591099841"
        }
    }
}
        
    

Получение группы полей сущности по ID группы

Метод

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}

Описание

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

Ограничения

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

Заголовок типа данных при успешном результате

Content-Type: application/hal+json

Заголовок типа данных при ошибке

Content-Type: application/problem+json

HTTP коды ответа

Код ответа Условие
200 Запрос выполнен успешно
404 Группа полей не найдена
401 Пользователь не авторизован

Параметры ответа

Метод возвращает коллекцию модель группы полей, рассмотрим ниже свойства группы полей.

Параметр Тип данных Описание
id string ID группы полей
name string Название группы полей
sort int Сортировка группы полей в карточке сущности
entity_type string Тип сущности (leads, contacts, companies, customers)
is_predefined bool Является ли группа предустановленной. Такие группы нельзя удалить
type string Тип группы (linked_group – группы товаров, custom_field_group – группы полей)

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

        
{
    "_total_items": 4,
    "_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": "4521",
                "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/4521"
                    }
                }
            },
            {
                "id": "statistic",
                "name": "Статистика",
                "is_predefined": true,
                "type": "linked_group",
                "entity_type": "leads",
                "sort": 2,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/leads/custom_fields/groups/statistic"
                    }
                }
            },
            {
                "id": "leads_29741591099841",
                "name": "Группа полей",
                "is_predefined": false,
                "type": "custom_field_group",
                "entity_type": "leads",
                "sort": 3,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/leads/custom_fields/groups/leads_29741591099841"
                    }
                }
            }
        ]
    }
}
        
    

Создание групп полей

Метод

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

Описание

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

Ограничения

Метод доступен только с правами администратора аккаунта.

Заголовок запроса

Content-Type: application/json

Параметры запроса

Параметр Тип данных Описание
name string Название группы. Обязательный параметр
sort int Сортировка группы. Обязательный параметр
request_id string Поле, которое вернется вам в ответе без изменений и не будет сохранено. Необязательный параметр

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

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

Заголовок типа данных при успешном результате

Content-Type: application/hal+json

Заголовок типа данных при ошибке

Content-Type: application/problem+json

HTTP коды ответа

Код ответа Условие
201 Группы полей были успешно созданы
403 Не хватает прав для вызова данного метода
401 Пользователь не авторизован
400 Переданы некорректные данные. Подробности доступны в теле ответа

Параметры ответа

Метод возвращает коллекцию групп полей, которые были созданы. Параметры аналогичны тем, что возвращаются при запросе списка групп.

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

        
{
    "_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/"
                    }
                }
            }
        ]
    }
}
        
    

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

Метод

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}

Описание

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

Ограничения

Метод доступен только с правами администратора аккаунта.

Заголовок запроса

Content-Type: application/json

Параметры запроса

Для изменения группы необходимо передать хотя бы один параметр

Параметр Тип данных Описание
name string Название группы
sort int Сортировка группы

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

        
{
    "sort": 6
}
        
    

Заголовок типа данных при успешном результате

Content-Type: application/hal+json

Заголовок типа данных при ошибке

Content-Type: application/problem+json

HTTP коды ответа

Код ответа Условие
200 Группа полей была успешно изменена
403 Не хватает прав для вызова данного метода
401 Пользователь не авторизован
400 Переданы некорректные данные. Подробности доступны в теле ответа

Параметры ответа

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

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

        
{
    "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/"
        }
    }
}
        
    

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

Метод

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}

Описание

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

Ограничения

  • Метод доступен только с правами администратора аккаунта
  • Предустановленные группы недоступны для удаления

Заголовок запроса

Content-Type: application/json

HTTP коды ответа

Код ответа Условие
204 Группа полей была успешно удалена
404 Группа полей не найдена
403 Не хватает прав для вызова данного метода
401 Пользователь не авторизован
400 Переданы некорректные данные. Подробности доступны в теле ответа

Параметры ответа

Метод не возвращает тело

Доступные типы полей

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

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

Таблица доступности разных типов полей для разных сущностей

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

Примеры заполнения разных типов полей через API

Ниже рассмотрим примеры запросов на заполнение значений разных типов полей

Не зависимо от типа полей все значения находятся передаются в объектах массива custom_fields_values. Для заполнения поля нужно передать его ID или символьный код, а также сами значения.

Параметр Тип данных Описание
custom_fields_values array Массив, содержащий информацию по значениям дополнительных полей, задаваемых для сущности
custom_fields_values[0] object Объект, содержащий информацию по значению дополнительного поля, задаваемых для сущности
custom_fields_values[0][field_id] int ID поля, значение которого вы заполняете
custom_fields_values[0][field_code] string Символьный код поля, значение которого вы заполняете
custom_fields_values[0][values] array Массив заполняемых значений
custom_fields_values[0][values][0] object Объект значения поля. Структура объекта зависит от типа поля

Типы полей:

text, numeric, textarea, price, streetaddress

В данном примере рассмотрим запрос на заполнения полей типа text, numeric, textarea, price, streetaddress.

Параметр Тип данных Описание
value string Значение поля
        
    ...
    "custom_fields_values": [
        {
            "field_id": 3,
            "values": [
                {
                    "value": "Значение поля"
                }
            ]
        },
        {
            "field_id": 103,
            "values": [
                {
                    "value": "1.5"
                }
            ]
        },
        {
            "field_id": 203,
            "values": [
                {
                    "value": "Строка1\nСтрока2"
                }
            ]
        },
        {
            "field_id": 303,
            "values": [
                {
                    "value": "100"
                }
            ]
        },
        {
            "field_id": 403,
            "values": [
                {
                    "value": "г. Москва, Николоямская улица 28/60 стр. 1"
                }
            ]
        }
    ],
    ...
        
    

checkbox

В данном примере рассмотрим запрос на заполнения полей типа checkbox.

Параметр Тип данных Описание
value bool Значение поля
        
    ...
    "custom_fields_values": [
        {
            "field_id": 5,
            "values": [
                {
                    "value": true
                }
            ]
        }
    ],
    ...
        
    

url

В данном примере рассмотрим запрос на заполнения полей типа url.

Параметр Тип данных Описание
value string Значение поля. Делегированный URL
        
    ...
    "custom_fields_values": [
        {
            "field_id": 7,
            "values": [
                {
                    "value": "https://www.amocrm.ru/"
                }
            ]
        }
    ],
    ...
        
    

date, date_time, birthday

В данном примере рассмотрим запрос на заполнения полей типа date, date_time, birthday.

Параметр Тип данных Описание
value int Значение поля – 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

В данном примере рассмотрим запрос на заполнения полей типа select, multiselect, radiobutton, category. В качестве значения может быть передано как значение, так и ID значения.

Параметр Тип данных Описание
value string Значение поля
enum_id int ID значения поля (enum).
        
    ...
    "custom_fields_values": [
        {
            "field_id": 11,
            "values": [
                {
                    "value": "Значение 1"
                }
            ]
        },
        {
            "field_id": 111,
            "values": [
                {
                    "enum_id": 17
                },
                {
                    "enum_id": 19
                }
            ]
        },
        {
            "field_id": 211,
            "values": [
                {
                    "value": "Значение 4"
                }
            ]
        }
    ],
    ...
        
    

smart_address

В данном примере рассмотрим запрос на заполнения полей типа smart_address. Поле принимает множественные значения. В значении необходимо передать поля value и enum_id или enum_code.

Параметр Тип данных Описание
value string Значение поля
enum_id int ID значения поля. Доступные значения: 1 – Первая строка адреса, 2 – Вторая строка адреса, 3 – Город, 4 – Регион, 5 – Почтовый индекс, 6 – Страна
enum_code string Код значения поля. Доступные значения: address_line_1 – Первая строка адреса, address_line_2 – Вторая строка адреса, city – Город, state – Регион, zip – Почтовый индекс, country – Страна
        
    ...
    "custom_fields_values": [
        {
            "field_id": 13,
            "values": [
                {
                    "value": "Николоямская улица 28/60",
                    "enum_id": 1
                },
                {
                    "value": "Москва",
                    "enum_code": "city"
                },
                {
                    "value": "Москва",
                    "enum_code": "state"
                },
                {
                    "value": "109004",
                    "enum_id": 5
                },
                {
                    "value": "RU",
                    "enum_code": "country"
                }
            ]
        }
    ],
    ...
        
    

multitext

В данном примере рассмотрим запрос на заполнения полей типа multitext (Телефон, Email). Поле принимает множественные значения. В значении необходимо передать поля value и enum_id или enum_code.

Параметр Тип данных Описание
value string Значение поля
enum_id int ID значения поля.
enum_code string Код значения поля.
Доступные значения для поля Телефон: WORK – рабочий, WORKDD – рабочий прямой, MOB – мобильный, FAX – факс, HOME – домашний, OTHER – другой.
Доступные значение для поля Email: WORK – рабочий, PRIV – личный, OTHER – другой.
        
    ...
    "custom_fields_values": [
        {
            "field_id": 31,
            "values": [
                {
                    "value": "+79121234567",
                    "enum_id": 48224
                },
                {
                    "value": "+74991234567",
                    "enum_code": "HOME"
                }
            ]
        }
    ],
    ...
        
    

legal_entity

В данном примере рассмотрим запрос на заполнения полей типа legal_entity. В значении необходимо обязательно передать поля name, vat_id, kpp.

Параметр Тип данных Описание
value object Значение поля
value[name] string Название организации
value[entity_type] int Тип юридического лица. 1 – Частное, 2 – Юридической.
value[vat_id] string ИНН организации
value[tax_registration_reason_code] string ОГРНИП
value[address] string Адрес организации
value[kpp] string КПП организации
value[external_uid] string Идентификатор внешней системы
        
    ...
    "custom_fields_values": [
        {
            "field_id": 25,
            "values": [
                {
                    "value": {
                        "name": "ООО Рога и копыта",
                        "entity_type": 1,
                        "vat_id": "123123123",
                        "tax_registration_reason_code": 213,
                        "address": "Moscow",
                        "kpp": "23123123",
                        "external_uid": "uuid"
                    }
                }
            ]
        }
    ],
    ...
        
    

items

В данном примере рассмотрим запрос на заполнения полей типа items. Поле доступно в списке счетов для хранения состава товара.

Параметр Тип данных Описание
value object Значение поля
value[sku] string SKU товара
value[description] string Описание товара
value[unit_price] int|float Цена за единицу товара
value[quantity] int|float Количество товара в счете
value[unit_type] string Единица измерения
value[discount] object Объект скидки на товар
value[discount][type] string Тип скидки (percentage – процентная или amount количественная)
value[discount][value] int|float Размер скидки
value[vat_rate_id] int Идентификатор налога (0 – Без НДС, 1 – 10%, 2 – 10/110, 3 – 18%, 4 – 18/118, 5 – 0)
value[external_uid] string Идентификатор внешней системы
        
    ...
    "custom_fields_values": [
        {
            "field_id": 25,
            "values": [
                {
                    "value": {
                        "sku": "34N4124",
                        "description": "Описание товара",
                        "unit_price": 10,
                        "quantity": 2,
                        "unit_type": "шт.",
                        "discount": {
                            "type": "amount",
                            "value": 25
                        },
                        "vat_rate_id": 18,
                        "external_uid": "uid"
                    }
                }
            ]
        }
    ],
    ...