Контакты

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

Оглавление

Список контактов

Метод

GET /api/v4/contacts

Описание

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

Ограничения

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

GET параметры

Параметр Тип данных Описание
with string Данный параметр принимает строку, в том числе из нескольких значений, указанных через запятую. Данный метод поддерживает следующие параметры.
page int Страница выборки
limit int Количество возвращаемых сущностей за один запрос (Максимум – 250)
query string|int Поисковый запрос (Осуществляет поиск по заполненным полям сущности)
filter object Фильтр. Подробней про фильтры читайте в отдельной статье
order object Сортировка результатов списка.
Доступные поля для сортировки: updated_at, id.
Доступные значения для сортировки: asc, desc.
Пример: /api/v4/contacts?order[updated_at]=asc

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

Content-Type: application/hal+json

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

Content-Type: application/problem+json

HTTP коды ответа

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

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

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

Параметр Тип данных Описание
id int ID контакта
name string Название контакта
first_name string Имя контакта
last_name string Фамилия контакта
responsible_user_id int ID пользователя, ответственного за контакт
group_id int ID группы, в которой состоит ответственны пользователь за контакт
created_by int ID пользователя, создавший контакт
updated_by int ID пользователя, изменивший контакт
created_at int Дата создания контакта, передается в Unix Timestamp
updated_at int Дата изменения контакта, передается в Unix Timestamp
closest_task_at int Дата ближайшей задачи к выполнению, передается в Unix Timestamp
custom_fields_values array|null Массив, содержащий информацию по значениям дополнительных полей, заданных для данного контакта
account_id int ID аккаунта, в котором находится контакт
_embedded object Данные вложенных сущностей
_embedded[tags] array Данные тегов, привязанных к контакту
_embedded[tags][0] object Модель тега, привязанного к контакту
_embedded[tags][0][id] int ID тега
_embedded[tags][0][name] string Название тега
_embedded[companies] array Данные компании, привязанной к контакту. В массиве всегда 1 объект
_embedded[companies][0] object Данные компании
_embedded[companies][0][id] int ID компании, привязанной к контакту
_embedded[customers] array Требуется GET параметр with. Данные покупателей, привязанных к контакту
_embedded[customers][0] object Данные покупателя
_embedded[customers][0][id] int ID покупателя
_embedded[leads] array Требуется GET параметр with. Данные сделок, привязанных к контакту
_embedded[leads][0] object Данные сделки
_embedded[leads][0][id] int ID сделки
_embedded[catalog_elements] array Требуется GET параметр with. Данные элементов списков, привязанных к контакту
_embedded[catalog_elements][0] object Данные элемента списка, привязанного к контакту
_embedded[catalog_elements][0][id] int ID элемента, привязанного к контакту
_embedded[catalog_elements][0][metadata] object Мета-данные элемента
_embedded[catalog_elements][0][quantity] int Количество элементов у контакта
_embedded[catalog_elements][0][catalog_id] int ID списка, в котором находится элемент

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

        
{
    "_page": 1,
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/contacts?limit=2&page=1"
        },
        "next": {
            "href": "https://example.amocrm.ru/api/v4/contacts?limit=2&page=2"
        }
    },
    "_embedded": {
        "contacts": [
            {
                "id": 7143599,
                "name": "1",
                "first_name": "",
                "last_name": "",
                "responsible_user_id": 504141,
                "group_id": 0,
                "created_by": 504141,
                "updated_by": 504141,
                "created_at": 1585758065,
                "updated_at": 1585758065,
                "closest_task_at": null,
                "custom_fields_values": null,
                "account_id": 28805383,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/contacts/7143599"
                    }
                },
                "_embedded": {
                    "tags": [],
                    "companies": []
                }
            },
            {
                "id": 7767065,
                "name": "dsgdsg",
                "first_name": "",
                "last_name": "",
                "responsible_user_id": 504141,
                "group_id": 0,
                "created_by": 504141,
                "updated_by": 504141,
                "created_at": 1586359590,
                "updated_at": 1586359590,
                "closest_task_at": null,
                "custom_fields_values": null,
                "account_id": 28805383,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/contacts/7767065"
                    }
                },
                "_embedded": {
                    "tags": [],
                    "companies": []
                }
            }
        ]
    }
}

Параметры для GET-параметры with

Параметр Описание
catalog_elements Добавляет в ответ связанные с контактами элементы списков
leads Добавляет в ответ связанные с контактами сделки
customers Добавляет в ответ связанных с контактами покупателей

Получение контакта по ID

Метод

GET /api/v4/contacts/{id}

Описание

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

Ограничения

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

GET параметры

Параметр Тип данных Описание
with string Данный параметр принимает строку, в том числе из нескольких значений, указанных через запятую. Данный метод поддерживает следующие параметры.

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

Content-Type: application/hal+json

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

Content-Type: application/problem+json

HTTP коды ответа

Код ответа Условие
200 Запрос выполнен успешно
204 Контакт с указанным ID не существует
401 Пользователь не авторизован

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

Метод возвращает модель контакта, рассмотрим ниже её свойства.

Параметр Тип данных Описание
id int ID контакта
name string Название контакта
first_name string Имя контакта
last_name string Фамилия контакта
responsible_user_id int ID пользователя, ответственного за контакт
group_id int ID группы, в которой состоит ответственны пользователь за контакт
created_by int ID пользователя, создавший контакт
updated_by int ID пользователя, изменивший контакт
created_at int Дата создания контакта, передается в Unix Timestamp
updated_at int Дата изменения контакта, передается в Unix Timestamp
closest_task_at int Дата ближайшей задачи к выполнению, передается в Unix Timestamp
custom_fields_values array|null Массив, содержащий информацию по значениям дополнительных полей, заданных для данного контакта
account_id int ID аккаунта, в котором находится контакт
_embedded object Данные вложенных сущностей
_embedded[tags] array Данные тегов, привязанных к контакту
_embedded[tags][0] object Модель тега, привязанного к контакту
_embedded[tags][0][id] int ID тега
_embedded[tags][0][name] string Название тега
_embedded[companies] array Данные компании, привязанной к контакту. В массиве всегда 1 объект
_embedded[companies][0] object Данные компании
_embedded[companies][0][id] int ID компании, привязанной к контакту
_embedded[customers] array Требуется GET параметр with. Данные покупателей, привязанных к контакту
_embedded[customers][0] object Данные покупателя
_embedded[customers][0][id] int ID покупателя
_embedded[leads] array Требуется GET параметр with. Данные сделок, привязанных к контакту
_embedded[leads][0] object Данные сделки
_embedded[leads][0][id] int ID сделки
_embedded[catalog_elements] array Требуется GET параметр with. Данные элементов списков, привязанных к контакту
_embedded[catalog_elements][0] object Данные элемента списка, привязанного к контакту
_embedded[catalog_elements][0][id] int ID элемента, привязанного к контакту
_embedded[catalog_elements][0][metadata] object Мета-данные элемента
_embedded[catalog_elements][0][quantity] int Количество элементов у контакта
_embedded[catalog_elements][0][catalog_id] int ID списка, в котором находится элемент

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

        
{
    "id": 3,
    "name": "Иван Иванов",
    "first_name": "Иван",
    "last_name": "Иванов",
    "responsible_user_id": 504141,
    "group_id": 0,
    "created_by": 504141,
    "updated_by": 504141,
    "created_at": 1582117331,
    "updated_at": 1590943929,
    "closest_task_at": null,
    "custom_fields_values": [
        {
            "field_id": 3,
            "field_name": "Телефон",
            "field_code": "PHONE",
            "field_type": "multitext",
            "values": [
                {
                    "value": "+79123",
                    "enum_id": 1,
                    "enum": "WORK"
                }
            ]
        }
    ],
    "account_id": 28805383,
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/contacts/3"
        }
    },
    "_embedded": {
        "tags": [],
        "leads": [
            {
                "id": 1,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/leads/1"
                    }
                }
            },
            {
                "id": 3916883,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/leads/3916883"
                    }
                }
            }
        ],
        "customers": [
            {
                "id": 134923,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/customers/134923"
                    }
                }
            }
        ],
        "catalog_elements": [],
        "companies": [
            {
                "id": 1,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/companies/1"
                    }
                }
            }
        ]
    }
}

Параметры для GET-параметры with

Параметр Описание
catalog_elements Добавляет в ответ связанные с контактами элементы списков
leads Добавляет в ответ связанные с контактами сделки
customers Добавляет в ответ связанных с контактами покупателей

Добавление контактов

Метод

POST /api/v4/contacts

Описание

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

Ограничения

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

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

Content-Type: application/json

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

Обязательные поля отсутствуют

Параметр Тип данных Описание
name string Название контакта
first_name string Имя контакта
last_name string Фамилия контакта
responsible_user_id int ID пользователя, ответственного за контакт
created_by int ID пользователя, создавший контакт
updated_by int ID пользователя, изменивший контакт
created_at int Дата создания контакта, передается в Unix Timestamp
updated_at int Дата изменения контакта, передается в Unix Timestamp
custom_fields_values array Массив, содержащий информацию по значениям дополнительных полей, заданных для данного контакта. Примеры заполнения полей
_embedded object Данные вложенных сущностей
_embedded[tags] array Данные тегов, привязанных к контакту
_embedded[tags][0] object Модель тега, привязанного к контакту
_embedded[tags][0][id] int ID тега
_embedded[tags][0][name] string Название тега
request_id string Поле, которое вернется вам в ответе без изменений и не будет сохранено. Поле не является обязательным

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

        
[
    {
        "first_name": "Петр",
        "last_name": "Смирнов",
        "custom_fields_values": [
            {
                "field_id": 271316,
                "values": [
                    {
                        "value": "Директор"
                    }
                ]
            }
        ]
    },
    {
        "name": "Владимир Смирнов",
        "created_by": 47272
    }
]

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

Content-Type: application/hal+json

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

Content-Type: application/problem+json

HTTP коды ответа

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

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

Метод возвращает коллекцию контактов, которые были созданы.

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

        
{
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/contacts"
        }
    },
    "_embedded": {
        "contacts": [
            {
                "id": 40401635,
                "request_id": "0",
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/contacts/40401635"
                    }
                },
                {
                    "id": 40401636,
                    "request_id": "1",
                    "_links": {
                        "self": {
                           "href": "https://example.amocrm.ru/api/v4/contacts/40401636"
                   }
                }
            }
        ]
    }
}

Редактирование контактов

Метод

PATCH /api/v4/contacts

Описание

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

Ограничения

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

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

Content-Type: application/json

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

Обязательные поля отсутствуют

Параметр Тип данных Описание
name string Название контакта
first_name string Имя контакта
last_name string Фамилия контакта
responsible_user_id int ID пользователя, ответственного за контакт
created_by int ID пользователя, создавший контакт
updated_by int ID пользователя, изменивший контакт
created_at int Дата создания контакта, передается в Unix Timestamp
updated_at int Дата изменения контакта, передается в Unix Timestamp
custom_fields_values array Массив, содержащий информацию по значениям дополнительных полей, заданных для данного контакта. Примеры заполнения полей
_embedded object Данные вложенных сущностей
_embedded[tags] array Данные тегов, привязанных к контакту
_embedded[tags][0] object Модель тега, привязанного к контакту
_embedded[tags][0][id] int ID тега
_embedded[tags][0][name] string Название тега
request_id string Поле, которое вернется вам в ответе без изменений и не будет сохранено. Поле не является обязательным

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

        
[
    {
        "id": 3,
        "first_name": "Иван",
        "last_name": "Иванов",
        "custom_fields_values": [
            {
                "field_id": 66192,
                "field_name": "Телефон",
                "values": [
                    {
                        "value": "79999999999",
                        "enum_code": "WORK"
                    }
                ]
            }
       ]
    }
]

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

Content-Type: application/hal+json

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

Content-Type: application/problem+json

HTTP коды ответа

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

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

Метод возвращает коллекцию контактов, которые были изменены.

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

        
{
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/contacts"
        }
    },
    "_embedded": {
        "contacts": [
            {
                "id": 3,
                "name": "Иван Иванов",
                "updated_at": 1590945248,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/contacts/3"
                    }
                }
            }
        ]
    }
}