amoCRM API v4: Найти контакт по телефону, чтобы не создавать дубли

Сценарий из mcp-everything. Актуально на 2026-10-24.

Перед созданием сделки проверить, есть ли клиент в базе, и привязать сделку к нему.

  1. Поищи контакт: GET /api/v4/contacts с query = номер телефона или email. Поиск идёт по заполненным полям.
  2. Если ответ 204 без тела — контакта нет. Создай его: POST /api/v4/contacts (тело — массив) и возьми id из _embedded.contacts.
  3. Создай сделку с привязкой к найденному или новому контакту: POST /api/v4/leads с _embedded.contacts = [{id}].
  4. Учитывай лимит: не больше 7 запросов в секунду на интеграцию. При 429 сделай паузу — повторные превышения блокируют аккаунт с ответом 403.
# Поиск по телефону
curl -G "https://<поддомен>.amocrm.ru/api/v4/contacts" \
  -H "Authorization: Bearer $AMO_TOKEN" \
  --data-urlencode 'query=+79990001122'

# Сделка с привязкой к контакту
curl -X POST "https://<поддомен>.amocrm.ru/api/v4/leads" \
  -H "Authorization: Bearer $AMO_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '[{"name": "Повторный заказ", "price": 9900, "_embedded": {"contacts": [{"id": 19663157}]}}]'

Базовые URL

Авторизация

Тип: OAuth 2.0

Два способа:

Токен передаётся в заголовке Authorization: Bearer {access token}.

Пример запроса токена:

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

{
  "client_id": "xxxx",
  "client_secret": "xxxx",
  "grant_type": "authorization_code",
  "code": "xxxxxxx",
  "redirect_uri": "https://test.test"
}

Методы сценария

POST /api/v4/leads — Добавление сделок

Тело — массив сделок; обязательных полей нет.

Параметр Где Тип Обяз. Описание
name body string нет Название сделки
price body int нет Бюджет
status_id body int нет Этап; по умолчанию первый этап главной воронки
pipeline_id body int нет Воронка
created_by body int нет Создатель; 0 — робот
updated_by body int нет Изменивший; 0 — робот
closed_at body int нет Дата закрытия (Unix Timestamp)
created_at body int нет Дата создания (Unix Timestamp)
updated_at body int нет Дата изменения (Unix Timestamp)
loss_reason_id body int нет Причина отказа
responsible_user_id body int нет Ответственный
custom_fields_values body array нет Значения дополнительных полей
tags_to_add body array нет Теги для добавления: id или name
_embedded[tags] body array нет Привязываемые теги
_embedded[contacts][0][id] body int нет Привязываемый контакт
_embedded[contacts][0][is_main] body string нет Главный контакт
_embedded[companies][0][id] body int нет Привязываемая компания
_embedded[source][external_id] body string нет Внешний ID источника
_embedded[source][type] body string нет Тип источника; для интеграций — widget

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

[
    {
        "name": "Сделка для примера 1",
        "created_by": 0,
        "price": 20000,
        "custom_fields_values": [
            {
                "field_id": 294471,
                "values": [
                    {
                        "value": "Наш первый клиент"
                    }
                ]
            }
        ],
        "tags_to_add": [
            {
                "name": "Первый тег"
            }
        ]
    }
]

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

{
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/leads"
        }
    },
    "_embedded": {
        "leads": [
            {
                "id": 10185151,
                "request_id": "0",
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/leads/10185151"
                    }
                }
            }
        ]
    }
}

GET /api/v4/contacts — Список контактов

Параметр Где Тип Обяз. Описание
with query string нет Доп. связанные сущности через запятую
page query int нет Страница
limit query int нет Записей на страницу, максимум 250
query query string нет Поиск по заполненным полям
filter query object нет Фильтр
order query object нет Сортировка по updated_at или id: asc/desc

POST /api/v4/contacts — Добавление контактов

Тело — массив контактов.

Параметр Где Тип Обяз. Описание
name body string нет Название контакта
first_name body string нет Имя
last_name body string нет Фамилия
responsible_user_id body int нет Ответственный
created_by body int нет Создатель
custom_fields_values body array нет Доп. поля (телефон, email и др.)
tags_to_add body array нет Теги для добавления
_embedded[tags] body array нет Привязанные теги
request_id body string нет Возвращается в ответе без изменений

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

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

Нюансы

Другие сценарии

Если этого недостаточно — официальная документация: https://www.amocrm.ru/developers/content/crm_platform/api-reference Вся интеграция одним документом: https://mcp-everything.ru/integrations/amocrm.md