amoCRM API v4: 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

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

Нюансы

• Создание и изменение — пакетное: тело запроса всегда массив, даже для одной сущности.
• Успешные ответы приходят с 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://www.amocrm.ru/developers/content/crm_platform/api-reference Вся интеграция одним документом: https://mcp-everything.ru/integrations/amocrm.md