Теги

Теги – инструмент, который позволяет классифицировать и сортировать сделки и другие сущности в клиентской базе. Пользователь сможет фильтровать по ним и просматривать.
Создание и удаление тега также возможно из интерфейса.

Получения списка тегов по типу сущности

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

URL метода

GET /api/v4/{entity_type}/tags

Параметры GET

Параметр Тип Описание
entity_type string Тип сущности: leads, contacts, companies, customers

Возможные query параметры запроса:

Параметр Описание
page Страница выборки
limit Кол-во выбираемых строк (системное ограничение 250)
search Позволяет осуществить полнотекстовый поиск поиск по названию тега
filter[id] Фильтр по идентификатору тега, можно передать список идентификаторов в виде массива
filter[name] Позволяет осуществить поиск по названию тега

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

В следующем примере мы получим теги, отфильтрованные по id


GET https://example.amocrm.ru/api/v4/leads/tags?filter[id][]=2707&filter[id][]=2709

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


{
    "_page": 1,
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/leads/tags?filter[id][]=2707&filter[id][]=2709#&page=1&limit=50&offset=0"
        },
        "next": {
            "href": "https://example.amocrm.ru/api/v4/leads/tags?filter[id][]=2707&filter[id][]=2709#&page=2&limit=50&offset=0"
        }
    },
    "_embedded": {
        "tags": [
            {
                "id": 2707,
                "name": "Заявка с сайта"
            },
            {
                "id": 2709,
                "name": "Техническая поддержка"
            }
        ]
    }
}

Создание тега

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

URL метода

POST /api/v4/{entity_type}/tags

Параметры GET

Параметр Тип Описание
entity_type string Тип сущности: leads, contacts, companies, customers

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

Для создания тега/тегов необходимо передать массив с JSON, содержащий одно обязательное поле name, например:


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

[
    {
        "name": "Tag 1"
    },
    {
        "name": "Tag 2"
    },
    {
        "name": "Tag 3"
    }
]

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


{
    "_total_items": 3,
    "_embedded": {
        "tags": [
            {
                "id": 263807,
                "name": "Tag 1"
            },
            {
                "id": 263809,
                "name": "Tag 2"
            },
            {
                "id": 263811,
                "name": "Tag 3"
            }
        ]
    }
}

Прикрепление тега к сущности

Метод позволяет закрепить теги за сделкой, контактом, компанией или покупателем.
Важно: При прикреплении новых тегов, все старые теги будут удалены.

URL метода

PATCH /api/v4/{entity_type}/{id} – прикрепление тегов по id сущности

PATCH /api/v4/{entity_type} – прикрепления тегов по типу сущности

Параметры GET

Параметр Тип Описание
entity_id int ID сущности
entity_type string Тип сущности: leads, contacts, companies, customers

Для прикрепления тегов по идентификатору сущности необходимо передать JSON, содержащий обязательный массив _embedded[tags] с идентификаторами тэгов.

Пример прикрепления тегов по идентификатору сущности:


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

{
    "_embedded": {
        "tags": [
            {
                "id": 263807
            },
            {
                "id": 263809
            }
        ]
    }
}

Для прикрепления тегов по типу сущности необходимо передать массив из JSON, содержащий обязательный ключ – id (идентификатор сущности) и массив _embedded[tags] с идентификаторами тэгов.

Пример прикрепления тегов по типу сущности:


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

[
    {
        "id": 167353,
        "_embedded": {
            "tags": [
                {
                    "id": 263807
                }
            ]
        }
    },
    {
        "id": 167355,
        "_embedded": {
            "tags": [
                {
                    "id": 263809
                }
            ]
        }
    }
]

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


{
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/leads"
        }
    },
    "_embedded": {
        "leads": [
            {
                "id": 167353,
                "updated_at": 1588928155,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/leads/167353"
                    }
                }
            },
            {
                "id": 167355,
                "updated_at": 1588928155,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/leads/167355"
                    }
                }
            }
        ]
    }
}

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

КОДЫ ОШИБОК API