---
slug: "amocrm"
name: "amoCRM API v4"
vendor: "amoCRM"
industry: "crm"
docsUrl: "https://www.amocrm.ru/developers/content/crm_platform/api-reference"
version: 2
updatedAt: "2026-10-24"
---

# amoCRM API v4

Отрасль: 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.

```bash
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=<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 месяца — обновляй токены по расписанию, даже если запросов к аккаунту нет.

```bash
# Обмен кода на токены
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.

```bash
# Поиск по телефону
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.

```bash
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: по нему видно, какое поле не прошло.

```bash
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

- Боевой: `https://{subdomain}.amocrm.ru/api/v4/`
- Авторизация OAuth: `https://www.amocrm.ru/oauth`

## Авторизация

Тип: OAuth 2.0

Два способа:

- **OAuth 2.0** (authorization code). Пользователь открывает `https://www.amocrm.ru/oauth?client_id={Integration ID}&state={state}&mode={popup или post_message}`, интеграция получает код (живёт 20 минут) и обменивает его на токены запросом `POST /oauth2/access_token` к поддомену аккаунта. Refresh token можно использовать только один раз; без использования он истекает через 3 месяца.
- **Долгосрочный токен** — создаётся на вкладке «Ключи» для внешних и приватных интеграций, срок от 1 дня до 5 лет, без refresh token. Повторно посмотреть его нельзя.

Токен передаётся в заголовке `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": "Первый тег"
            }
        ]
    }
]
```

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

```json
{
    "_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"
   }
]
```

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

```json
[
   {
      "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`.

## Нюансы

- Создание и изменение — пакетное: тело запроса всегда массив, даже для одной сущности.
- Успешные ответы приходят с `Content-Type: application/hal+json`, ошибки — `application/problem+json`; в запросах с телом указывайте `Content-Type: application/json`.
- Запрос несуществующей сущности по ID возвращает `204` без тела, а не `404`.
- Refresh token одноразовый: после обновления сохраняйте новый, иначе доступ придётся получать заново.
- Ошибки валидации возвращаются массивом `validation-errors` с `request_id` и списком `errors` (`code`, `path`, `detail`).
- После окончания подписки запросы на добавление и изменение сразу отклоняются с `402`, доступ к данным закрывается через 30 дней.
- Повторные превышения лимита приводят к блокировке аккаунта: все запросы получают `403`.

## Ошибки

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

## Ограничения

- Не больше 7 запросов в секунду на интеграцию и до 50 запросов в секунду на аккаунт.
- Списки отдают до 250 записей на страницу (максимум выдачи для части сущностей — 500).
- За один запрос создаётся или изменяется не больше 250 сущностей; рекомендуется не больше 50.
- `POST /api/v4/leads/complex` — до 50 сделок в запросе.

## Источники

- [Сделки](https://www.amocrm.ru/developers/content/crm_platform/leads-api)
- [Контакты](https://www.amocrm.ru/developers/content/crm_platform/contacts-api)
- [OAuth 2.0 — пошагово](https://www.amocrm.ru/developers/content/oauth/step-by-step)
- [Ограничения и рекомендации](https://www.amocrm.ru/developers/content/api/recommendations)
- [Коды ошибок](https://www.amocrm.ru/developers/content/crm_platform/error-codes)
- [Справочник API](https://www.amocrm.ru/developers/content/crm_platform/api-reference)

---

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