# 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.

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

## Базовые 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 /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"
                    }
                }
            }
        ]
    }
}
```

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

## Нюансы

- Создание и изменение — пакетное: тело запроса всегда массив, даже для одной сущности.
- Успешные ответы приходят с `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`.

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

- [Создать сделку с контактом из заявки на сайте](https://mcp-everything.ru/integrations/amocrm/scenarios/sozdat-sdelku-s-kontaktom-iz-zayavki.md)
- [Получить токены OAuth и не потерять доступ](https://mcp-everything.ru/integrations/amocrm/scenarios/poluchit-tokeny-oauth-i-ne-poteryat.md)
- [Выгрузить сделки воронки по этапу](https://mcp-everything.ru/integrations/amocrm/scenarios/vygruzit-sdelki-voronki-po-etapu.md)
- [Перевести сделку на этап или закрыть её](https://mcp-everything.ru/integrations/amocrm/scenarios/perevesti-sdelku-na-etap-ili-zakryt-ee.md)

---

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