amoCRM API v4 API

Отрасль: CRM и продажи. Актуально на 2026-10-24.

REST API CRM-системы amoCRM: сделки, контакты, компании, задачи, воронки, примечания, списки, пользователи, вебхуки и другие сущности аккаунта. Запросы выполняются к поддомену конкретного аккаунта. Сделки и контакты создаются и изменяются пакетами — тело запроса всегда массив объектов.

Сценарии

Создать сделку с контактом из заявки на сайте

Одним запросом создать сделку, контакт и компанию из формы на сайте. Если в аккаунте включён контроль дублей, amoCRM сам склеит повторную заявку.

  1. Получи токен: для одной своей CRM проще всего долгосрочный токен из настроек приватной интеграции (вкладка «Ключи»), для тиражной интеграции — OAuth, см. сценарий про токены.
  2. Отправь заявку: POST /api/v4/leads/complex. Тело — массив (даже из одной сделки): name, price, pipeline_id и status_id, а в _embedded — новый контакт с телефоном и email. Телефон и email передаются в custom_fields_values с field_code PHONE и EMAIL.
  3. В ответе для каждой сделки придут id, contact_id и company_id, а merged = true — если сработал контроль дублей.
  4. В одном запросе — до 50 сделок, на сделку — 1 контакт и 1 компания. Чтобы заявка попала в «Неразобранное», передай _embedded.metadata с category = forms.
curl -X POST "https://<поддомен>.amocrm.ru/api/v4/leads/complex" \
  -H "Authorization: Bearer $AMO_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '[{
        "name": "Заявка с сайта: кухня на заказ",
        "price": 150000,
        "_embedded": {
          "contacts": [{
            "first_name": "Екатерина",
            "custom_fields_values": [
              {"field_code": "PHONE", "values": [{"value": "+79990001122", "enum_code": "WORK"}]},
              {"field_code": "EMAIL", "values": [{"value": "kate@example.ru", "enum_code": "WORK"}]}
            ]
          }]
        },
        "request_id": "form-1042"
      }]'

Получить токены OAuth и не потерять доступ

Для интеграции, которую ставят другие аккаунты: обменять код на токены и вовремя их обновлять.

  1. Отправь пользователя на https://www.amocrm.ru/oauth?client_id=<ID интеграции>&state=&mode=post_message. После согласия amoCRM вернёт code и поддомен аккаунта на redirect_uri. Код живёт 20 минут.
  2. Обменяй код: POST /oauth2/access_token к поддомену аккаунта с client_id, client_secret, grant_type = authorization_code, code и redirect_uri. Сохрани access_token, refresh_token и expires_in.
  3. До истечения access_token обнови пару тем же методом POST /oauth2/access_token с grant_type = refresh_token. Refresh token одноразовый: сразу сохрани новый, иначе пользователю придётся подключать интеграцию заново.
  4. Не обновлённый refresh token истекает через 3 месяца — обновляй токены по расписанию, даже если запросов к аккаунту нет.
# Обмен кода на токены
curl -X POST "https://<поддомен>.amocrm.ru/oauth2/access_token" \
  -H 'Content-Type: application/json' \
  -d '{
        "client_id": "<ID интеграции>",
        "client_secret": "<секрет>",
        "grant_type": "authorization_code",
        "code": "<код из redirect>",
        "redirect_uri": "https://example.ru/amo/callback"
      }'

# Обновление (refresh_token после этого недействителен — сохрани новый)
curl -X POST "https://<поддомен>.amocrm.ru/oauth2/access_token" \
  -H 'Content-Type: application/json' \
  -d '{"client_id": "<ID интеграции>", "client_secret": "<секрет>", "grant_type": "refresh_token", "refresh_token": "<refresh_token>", "redirect_uri": "https://example.ru/amo/callback"}'

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

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

  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}]}}]'

Выгрузить сделки воронки по этапу

Забрать сделки в отчёт или учётную систему с контактами.

  1. Узнай id воронки и этапов (в настройках воронки или в данных существующих сделок: pipeline_id, status_id). У всех воронок общие системные этапы: 142 — «Успешно реализовано», 143 — «Закрыто и не реализовано».
  2. Запроси список: GET /api/v4/leads с filter[statuses][0][pipeline_id] и filter[statuses][0][status_id], limit = 250 и with = contacts, чтобы сразу получить привязанные контакты.
  3. Листай страницы через page, пока в _links есть next.
  4. Для выгрузки изменений с прошлого раза добавь filter[updated_at][from] с Unix-временем последней выгрузки и сортировку order[updated_at] = asc.
curl -G "https://<поддомен>.amocrm.ru/api/v4/leads" \
  -H "Authorization: Bearer $AMO_TOKEN" \
  -d 'filter[statuses][0][pipeline_id]=3383152' \
  -d 'filter[statuses][0][status_id]=142' \
  -d 'with=contacts' \
  -d 'limit=250' \
  -d 'page=1'

Перевести сделку на этап или закрыть её

Обновить сделку из своей системы: оплата прошла — «Успешно реализовано», клиент отказался — «Закрыто» с причиной.

  1. Измени сделку: PATCH /api/v4/leads — тело массив объектов, в каждом обязателен id. Для перевода на этап передай status_id (и pipeline_id, если воронка другая).
  2. Чтобы закрыть успешно, передай status_id = 142; неуспешно — 143 и loss_reason_id. Дату закрытия задаёт closed_at в Unix-времени.
  3. Заодно можно поправить бюджет price, ответственного responsible_user_id, добавить или снять теги через tags_to_add и tags_to_delete.
  4. Ошибки валидации приходят в validation-errors с request_id и списком errors: по нему видно, какое поле не прошло.
curl -X PATCH "https://<поддомен>.amocrm.ru/api/v4/leads" \
  -H "Authorization: Bearer $AMO_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '[
        {"id": 54886, "status_id": 142, "price": 46333, "tags_to_add": [{"name": "Оплачено"}]},
        {"id": 54887, "status_id": 143, "loss_reason_id": 7323}
      ]'

Базовые 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 /oauth2/access_token — Получение и обновление токенов

Параметр Где Тип Обяз. Описание
client_id body string да ID интеграции
client_secret body string да Секрет интеграции (для refresh_token — необязателен)
grant_type body string да authorization_code или refresh_token
code body string нет Код авторизации (для authorization_code)
refresh_token body string нет Refresh token (для refresh_token)
redirect_uri body string да Redirect URI интеграции

GET /api/v4/leads — Список сделок

Пример ответа (сокращён):

Параметр Где Тип Обяз. Описание
with query string нет Доп. данные через запятую: catalog_elements, is_price_modified_by_robot, loss_reason, contacts, only_deleted, source_id, source
page query int нет Номер страницы
limit query int нет Записей на страницу, максимум 250
query query string нет Поиск по заполненным полям сделки
filter query object нет Фильтр
order query object нет Сортировка по created_at, updated_at или id: asc/desc, например order[updated_at]=asc

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

{
    "_page": 2,
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/leads?limit=2&page=2"
        },
        "next": {
            "href": "https://example.amocrm.ru/api/v4/leads?limit=2&page=3"
        }
    },
    "_embedded": {
        "leads": [
            {
                "id": 19619,
                "name": "Сделка для примера",
                "price": 46333,
                "status_id": 142,
                "pipeline_id": 1300,
                "is_deleted": false,
                "account_id": 5135160
            }
        ]
    }
}

GET /api/v4/leads/{id} — Сделка по ID

Параметр Где Тип Обяз. Описание
id path int да ID сделки
with query string нет Те же значения, что у списка

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"
                    }
                }
            }
        ]
    }
}

POST /api/v4/leads/complex — Комплексное добавление сделок с контактом и компанией

Создаёт сделки сразу с контактом и компанией; при включённом контроле дублей применяет его. На сделку — 1 контакт и 1 компания, до 40 доп. полей на сущность, до 50 сделок в запросе.

Параметр Где Тип Обяз. Описание
name body string нет Название сделки
price body int нет Бюджет
status_id body int нет Этап
pipeline_id body int нет Воронка
request_id body string нет Идентификатор запроса, возвращается в ответе
_embedded[contacts][0] body object нет Существующий контакт (id) или модель нового
_embedded[companies][0] body object нет Существующая компания (id) или модель новой
_embedded[metadata] body array нет Метаданные для создания неразобранного; статус тогда игнорируется
_embedded[metadata][category] body string нет Категория неразобранного: sip или forms

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

[
   {
      "name": "Название сделки",
      "price": 3422,
      "_embedded": {
         "contacts": [
            {
               "first_name": "Екатерина",
               "responsible_user_id": 2004184
            }
         ],
         "companies": [
            {
               "name": "ООО Рога и Копыта"
            }
         ]
      },
      "status_id": 33929752,
      "pipeline_id": 3383152,
      "request_id": "qweasd"
   }
]

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

[
   {
      "id": 15198335,
      "contact_id": 19663157,
      "company_id": 19663155,
      "request_id": [
         "qweasd"
      ],
      "merged": false
   }
]

PATCH /api/v4/leads — Редактирование сделок

Пакетное изменение; для одной сделки можно отправить модель на /api/v4/leads/{id}.

Параметр Где Тип Обяз. Описание
id body int да ID изменяемой сделки
name body string нет Название
price body int нет Бюджет
status_id body int нет Этап
pipeline_id body int нет Воронка
closed_at body int нет Дата закрытия
loss_reason_id body int нет Причина отказа
responsible_user_id body int нет Ответственный
custom_fields_values body array нет Доп. поля
tags_to_add body array нет Добавить теги
tags_to_delete body array нет Удалить теги

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

[
    {
        "id": 54886,
        "pipeline_id": 47521,
        "status_id": 143,
        "closed_at": 1589297221,
        "loss_reason_id": 7323,
        "updated_by": 0,
        "tags_to_add": [
            {
                "name": "Второй тег"
            }
        ],
        "tags_to_delete": [
            {
                "name": "Первый тег"
            }
        ]
    }
]

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

GET /api/v4/contacts/{id} — Контакт по ID

Параметр Где Тип Обяз. Описание
id path int да ID контакта

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": "Тег контакта"
            }
        ]
    }
]

PATCH /api/v4/contacts — Редактирование контактов

Пакетное изменение контактов; в каждом объекте обязателен id.

Нюансы

Ошибки

Код Описание
204 Ничего не найдено (внутренний код 2002)
400 Неверная структура данных или неверные ID доп. полей
401 Не авторизован; коды 110 (неверный логин/пароль), 111 (нужна капча), 112 (пользователь отключён), 101 (аккаунт не существует)
402 Подписка закончилась
403 Аккаунт заблокирован за частые запросы; код 113 — доступ с IP запрещён белым списком
405 HTTP-метод не поддерживается
422 Входящие данные не удалось обработать
429 Превышен лимит запросов в секунду
504 Таймаут — уменьшите количество сущностей в запросе

Ограничения

Источники

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