Основы

Формат данных

Запросы

Тело запроса - JSON в UTF-8 с заголовком Content-Type: application/json.
Параметры списков и фильтры передаются в строке запроса: ?limit=50&project_id=….
Незнакомые поля в теле API пропускает без ошибки. Опечатка в имени поля не даст ошибки - поле просто не сохранится. Сверяйте имена полей со справочником.

Объекты

В каждом объекте есть поле object - тип объекта: contact, list и другие.

Один объект приходит как есть, без обёртки:

{
  "object": "contact",
  "id": "01a0d7f0-b6c0-7a1a-82e4-2cab98a901c7",
  "name": "Анна Смирнова"
}

Список - объект list с полями data и has_more, см. Пагинация.

id

id - это UUID версии 7, строкой и без префиксов: 01a0d7f0-b6c0-7a1a-82e4-2cab98a901c7. Чем позже создан объект, тем больше его id - на этом держится порядок в списках. Храните id как строку.

Время

В ответах время - ISO 8601 в UTC, с буквой Z на конце:

2026-09-25T09:41:12Z

В запросах всегда указывайте часовой пояс: 2026-10-01T14:00:00+03:00 или 2026-10-01T11:00:00Z. Время без пояса API либо отклонит с ошибкой 422, либо прочитает как UTC.

Телефоны

Телефоны в ответах - в формате E.164: + и цифры с кодом страны, без пробелов и скобок.

+79101234567

Лучше сразу передавать номер в E.164. Номер в другой записи API приведёт к E.164 сам: 8 910 123-45-67 и +7 (910) 123-45-67 станут +79101234567. Десять цифр без кода страны считаются номером с кодом +7. Если строку не удалось разобрать как номер, в контакте она сохранится как есть.

metadata

metadata - ваши данные на объекте: номер заказа в 1С, id клиента в вашей CRM. API их хранит и возвращает, но никак не использует.

{
  "metadata": {
    "crm_id": "A-10042",
    "order_total": 12500,
    "vip": true
  }
}

Плоский объект: до 50 ключей.
Ключ - строка до 40 символов. Ключ из одних цифр, в том числе с минусом впереди, не принимается: id_10042 можно, 10042 и -5 - нельзя.
Значение - строка, число, true/false или null. Строка - до 500 символов. Вложенные объекты и массивы не принимаются.
Пробелы по краям строки API убирает, пустая строка сохраняется как null.

Нарушение этих правил - ошибка 422 validation.

Версии

Версия API - в адресе: /v1. Внутри v1 изменения только добавляются: новые поля в ответах, новые необязательные параметры, новые ресурсы. Переименовать, удалить поле или изменить его тип можно только в новой версии с другим адресом, /v2.

Чтобы новые поля ничего не сломали, пропускайте в ответах поля, которых не знаете.

Все изменения - на странице Изменения API.