Если у вас еще нет amoCRM
Создать прямо сейчасВ данном разделе описываются доступные методы для работы с сущностью контакта
GET /api/v4/contacts
Метод позволяет получить список контактов в аккаунте.
Метод доступен в соответствии с правами пользователя.
Параметр | Тип данных | Описание |
---|---|---|
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
Код ответа | Условие |
---|---|
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": []
}
}
]
}
}
Параметр | Описание |
---|---|
catalog_elements | Добавляет в ответ связанные с контактами элементы списков |
leads | Добавляет в ответ связанные с контактами сделки |
customers | Добавляет в ответ связанных с контактами покупателей |
GET /api/v4/contacts/{id}
Метод позволяет получить данные конкретного контакта по ID.
Метод доступен в соответствии с правами пользователя.
Параметр | Тип данных | Описание |
---|---|---|
with | string | Данный параметр принимает строку, в том числе из нескольких значений, указанных через запятую. Данный метод поддерживает следующие параметры. |
Content-Type: application/hal+json
Content-Type: application/problem+json
Код ответа | Условие |
---|---|
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"
}
}
}
]
}
}
Параметр | Описание |
---|---|
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
Код ответа | Условие |
---|---|
200 | Контакты были успешно созданы |
401 | Пользователь не авторизован |
400 | Переданы некорректные данные. Подробности доступны в теле ответа |
Метод возвращает коллекцию контактов, которые были созданы.
Параметр | Тип данных | Описание |
---|---|---|
id | int | ID контакта |
request_id | string | Строка переданная при запросе или порядковый указатель, если параметр не передан |
{
"_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
Код ответа | Условие |
---|---|
200 | Контакты были успешно изменены |
401 | Пользователь не авторизован |
400 | Переданы некорректные данные. Подробности доступны в теле ответа |
Метод возвращает коллекцию контактов, которые были изменены.
Параметр | Тип данных | Описание |
---|---|---|
id | int | ID контакта |
updated_at | int | Unix Timestamp изменения контакта |
request_id | string | Строка переданная при запросе или порядковый указатель, если параметр не передан |
{
"_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"
}
}
}
]
}
}
POST /api/v4/contacts/chats
Метод позволяет привязать чат к контакту. Чат может быть привязан только к 1 контакту, в тоже время контакт может быть
привязан к нескольким чатам.
Метод доступен с правами администратора аккаунта.
В настройках канала должен быть указан uuid интеграции, которая запрашивает метод.
Интеграция может менять привязку чатов только по каналам,к которым она имеет доступ.
Не должны передаваться никакие сессионые куки, иначе метод вернет ошибку.
Content-Type: application/json
Параметр | Тип данных | Описание |
---|---|---|
chat_id | string | Данный параметр принимает массив строк, uuid идентификаторов чатов |
contact_id | int | Данный параметр принимает массив чисел, id контактов |
request_id | string | Поле, которое вернется вам в ответе без изменений и не будет сохранено. Поле не является обязательным |
[
{
"contact_id": 3102959,
"chat_id":"6cbab3d5-c4c1-46ff-b710-ad59ad10805f"
}
]
Content-Type: application/hal+json
Content-Type: application/problem+json
Код ответа | Условие |
---|---|
200 | Запрос выполнен успешно |
401 | Пользователь не авторизован |
Метод возвращает коллекцию связей
Параметр | Тип данных | Описание |
---|---|---|
id | int | ID связи контакта и чата (может меняться при изменении привязки чата к контакту) |
contact_id | int | ID контакта |
chat_id | string | ID чата |
request_id | string | Строка переданная при запросе или порядковый указатель, если параметр не передан |
{
"_total_items": 1,
"_embedded": {
"chats": [
{
"chat_id": "6cbab3d5-c4c1-46ff-b710-ad59ad10805f",
"contact_id": 3102959,
"id": 26219,
"request_id": "0"
}
]
}
}
GET /api/v4/contacts/chats
Метод позволяет получить список чатов, которые относятся к контактам. Или список контактов к которым привязан чат.
Если чат относится к неразобранному, метод вернет id контакта в этом неразобранном.
Метод доступен с правами администратора аккаунта.
В настройках канала должен быть указан uuid интеграции, которая запрашивает метод.
Интеграция может запросить только чаты по каналам, которым она имеет доступ. Таким образом внутренние чаты между пользователями
акканта выводится не будут
Не должны передаваться никакие сессионые куки, иначе метод вернет ошибку.
Параметр | Тип данных | Описание |
---|---|---|
chat_id | string | Данный параметр принимает массив строк, uuid идентификаторов чатов |
contact_id | int | Данный параметр принимает массив чисел, id контактов |
Content-Type: application/hal+json
Content-Type: application/problem+json
Код ответа | Условие |
---|---|
200 | Запрос выполнен успешно |
401 | Пользователь не авторизован |
Метод возвращает коллекцию связей
Параметр | Тип данных | Описание |
---|---|---|
id | int | ID связи контакта и чата (может меняться при изменении привязки чата к контакту) |
contact_id | int | ID контакта |
chat_id | string | ID чата |
{
"_total_items": 1,
"_embedded": {
"chats": [
{
"chat_id": "6cbab3d5-c4c1-46ff-b710-ad59ad10805f",
"contact_id": 3102959,
"id": 26219
}
]
}
}