Dialogi
Начать бесплатно

Справочник · Платформа

Клиенты

Контакты - карточки клиентов в CRM. Через API контакты можно искать по email и телефону, создавать и менять. Контакт принадлежит проекту: ключ видит контакты только своих проектов.

Объект клиента

Контакт - карточка клиента в CRM проекта.

objectстрокаобязателен

Тип объекта, всегда contact.

Значения: contact

iduuidобязателен

id контакта.

project_iduuidобязателен

id проекта, в котором контакт.

typeстрокаобязателен

person - человек, b2b_company - компания.

Значения: personb2b_company

nameстрокаобязателен

Имя, как его показывает личный кабинет.

first_nameстрокаобязателенможет быть null

Имя.

last_nameстрокаобязателенможет быть null

Фамилия.

emailстрокаобязателенможет быть null

Основной email.

phoneстрокаобязателенможет быть null

Основной телефон, обычно в E.164: +79101234567. Строка, которую не удалось разобрать как номер, хранится как есть.

positionстрокаобязателенможет быть null

Должность.

lifecycleстрокаобязателен

Этап клиента: lead - лид, mql и sql - квалифицированный лид маркетингом и продажами, customer - клиент, churned - ушёл. Этап может быть и другой строкой, если его загрузили из файла в личном кабинете.

statusстрокаобязателен

active - рабочий контакт, archived - в архиве, blocked - заблокирован в личном кабинете.

Значения: activearchivedblocked

sourceстрокаобязателен

Откуда пришёл контакт, например api - создан через API, manual - вручную в личном кабинете. Список значений может пополняться.

metadataобъектобязателенможет быть null

Ваши данные, переданные при создании через API. У контактов из других источников - null. См. Формат данных.

created_atдата и время с зонойобязателенможет быть null

Когда контакт создан, UTC.

updated_atдата и время с зонойобязателенможет быть null

Когда контакт последний раз менялся, UTC.

Объект клиента 
{
  "object": "contact",
  "id": "01a0d7f0-b6c0-7a1a-82e4-2cab98a901c7",
  "project_id": "01a0c4e2-3f10-7b4d-9c2e-5d8a1f6b3e20",
  "type": "person",
  "name": "Анна Смирнова",
  "first_name": "Анна",
  "last_name": "Смирнова",
  "email": "anna@example.com",
  "phone": "+79101234567",
  "position": null,
  "lifecycle": "lead",
  "status": "active",
  "source": "api",
  "metadata": {
    "crm_id": "A-10042"
  },
  "created_at": "2026-09-25T09:41:12Z",
  "updated_at": "2026-09-25T09:41:12Z"
}
GET/v1/contacts

Список контактов

Право: contacts:read

Контакты проектов ключа, от новых к старым, по страницам. Фильтры можно сочетать: email и phone находят контакт по основному email и телефону.

Параметры запроса

limitцелое числоможет быть null

Сколько контактов на странице, от 1 до 100.

По умолчанию: 20

starting_afteruuidможет быть null

id последнего контакта предыдущей страницы: страница начнётся после него. См. Пагинация.

project_iduuidможет быть null

Только контакты этого проекта. Проекта нет в ключе - ошибка 403.

emailстрокаможет быть null

Контакты с таким основным email, точное совпадение.

phoneстрокаможет быть null

Контакты с таким основным телефоном. Номер в другой записи API приведёт к E.164.

lifecycleстрокаможет быть null

Контакты на этом этапе.

Значения: leadmqlsqlcustomerchurned

Ответы

  • 200Страница списка контактов.
  • 401Нет ключа, ключ неверный, истёк или отозван (unauthenticated).
  • 402У компании не подключено дополнение «Публичный API» (api-addon-required).
  • 403У ключа нет нужного права или доступа к проекту (forbidden).
  • 422Данные запроса не прошли проверку (validation). Какие поля и почему - в errors.
  • 429Превышен лимит запросов (rate-limited). Повторите через столько секунд, сколько указано в Retry-After.
  • 503Сервис временно недоступен (unavailable). Повторите позже.
Запрос 
curl https://api.ru.dialogi.io/v1/contacts \
  -H "Authorization: Bearer dk_live_…"
Ответ 200
{
  "object": "list",
  "data": [
    {
      "object": "contact",
      "id": "01a0d7f0-b6c0-7a1a-82e4-2cab98a901c7",
      "project_id": "01a0c4e2-3f10-7b4d-9c2e-5d8a1f6b3e20",
      "type": "person",
      "name": "Анна Смирнова",
      "first_name": "Анна",
      "last_name": "Смирнова",
      "email": "anna@example.com",
      "phone": "+79101234567",
      "position": null,
      "lifecycle": "lead",
      "status": "active",
      "source": "api",
      "metadata": {
        "crm_id": "A-10042"
      },
      "created_at": "2026-09-25T09:41:12Z",
      "updated_at": "2026-09-25T09:41:12Z"
    }
  ],
  "has_more": true
}
POST/v1/contacts

Создать контакт

Право: contacts:write Idempotency-Key обязателен

Создаёт контакт в проекте. Ключ с одним проектом подставит его сам, с несколькими - передайте project_id.

Ответственного назначат правила распределения CRM, как у контакта из других источников. Если ни одно правило не сработало, контакт остаётся без ответственного. Правило может поменять и этап, если lifecycle не передан или равен lead: в ответе - этап, который сохранился.

Каждый запрос создаёт новый контакт, даже с тем же телефоном или email. Чтобы не завести дубль, сначала поищите контакт в списке по phone или email.

Параметры тела

project_iduuidможет быть null

Проект контакта. Обязателен, если в ключе несколько проектов.

typeстрокаможет быть null

person - человек, b2b_company - компания.

Значения: personb2b_company

По умолчанию: "person"

nameстрокаобязателен

Имя, как его показывать в личном кабинете.

first_nameстрокаможет быть null

Имя.

last_nameстрокаможет быть null

Фамилия.

emailemailможет быть null

Основной email.

phoneстрокаможет быть null

Основной телефон, лучше в E.164. Номер в другой записи API приведёт к E.164.

positionстрокаможет быть null

Должность.

lifecycleстрокаможет быть null

Этап клиента. Если этап не передан или равен lead, его может поменять правило распределения CRM.

Значения: leadmqlsqlcustomerchurned

По умолчанию: "lead"

metadataобъектможет быть null

Ваши данные: плоский объект до 50 ключей, ключ - до 40 символов и не число (10042 или -5 не подойдут), значение - строка до 500 символов, число, true/false или null. Пробелы по краям строки API убирает, пустая строка сохраняется как null. См. Формат данных.

Ответы

  • 201Созданный контакт.
  • 400Нет заголовка Idempotency-Key (idempotency-key-required) или ключ в неверном формате (idempotency-key-invalid).
  • 401Нет ключа, ключ неверный, истёк или отозван (unauthenticated).
  • 402У компании не подключено дополнение «Публичный API» (api-addon-required).
  • 403У ключа нет нужного права или доступа к проекту (forbidden).
  • 409Idempotency-Key уже использован с другим запросом (idempotency-conflict) или первый запрос с ним ещё выполняется (idempotency-in-progress).
  • 422Данные запроса не прошли проверку (validation). Какие поля и почему - в errors.
  • 429Превышен лимит запросов (rate-limited). Повторите через столько секунд, сколько указано в Retry-After.
  • 503Сервис временно недоступен (unavailable). Повторите позже.
Запрос 
curl https://api.ru.dialogi.io/v1/contacts \
  -H "Authorization: Bearer dk_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-20195208" \
  -d '{
    "type": "person",
    "name": "Анна Смирнова",
    "phone": "+79101234567",
    "lifecycle": "lead"
  }'
Ответ 201
{
  "object": "contact",
  "id": "01a0d7f0-b6c0-7a1a-82e4-2cab98a901c7",
  "project_id": "01a0c4e2-3f10-7b4d-9c2e-5d8a1f6b3e20",
  "type": "person",
  "name": "Анна Смирнова",
  "first_name": "Анна",
  "last_name": "Смирнова",
  "email": "anna@example.com",
  "phone": "+79101234567",
  "position": null,
  "lifecycle": "lead",
  "status": "active",
  "source": "api",
  "metadata": {
    "crm_id": "A-10042"
  },
  "created_at": "2026-09-25T09:41:12Z",
  "updated_at": "2026-09-25T09:41:12Z"
}
GET/v1/contacts/{contact}

Получить контакт

Право: contacts:read

Контакт по id. Контакт из проекта, которого нет в ключе, для ключа не существует - ответ 404.

Параметры пути

contactuuidобязателен

id контакта.

Ответы

  • 200Контакт.
  • 401Нет ключа, ключ неверный, истёк или отозван (unauthenticated).
  • 402У компании не подключено дополнение «Публичный API» (api-addon-required).
  • 403У ключа нет нужного права или доступа к проекту (forbidden).
  • 404Объекта с таким id нет или он в проекте, которого нет в ключе (not-found).
  • 429Превышен лимит запросов (rate-limited). Повторите через столько секунд, сколько указано в Retry-After.
  • 503Сервис временно недоступен (unavailable). Повторите позже.
Запрос 
curl https://api.ru.dialogi.io/v1/contacts/0192d3a1-7b2c-7c3e-9a51-2f6b8e4d1c90 \
  -H "Authorization: Bearer dk_live_…"
Ответ 200
{
  "object": "contact",
  "id": "01a0d7f0-b6c0-7a1a-82e4-2cab98a901c7",
  "project_id": "01a0c4e2-3f10-7b4d-9c2e-5d8a1f6b3e20",
  "type": "person",
  "name": "Анна Смирнова",
  "first_name": "Анна",
  "last_name": "Смирнова",
  "email": "anna@example.com",
  "phone": "+79101234567",
  "position": null,
  "lifecycle": "lead",
  "status": "active",
  "source": "api",
  "metadata": {
    "crm_id": "A-10042"
  },
  "created_at": "2026-09-25T09:41:12Z",
  "updated_at": "2026-09-25T09:41:12Z"
}
PATCH/v1/contacts/{contact}

Изменить контакт

Право: contacts:write

Меняет только переданные поля. null очищает необязательное поле.

Параметры пути

contactuuidобязателен

id контакта.

Параметры тела

nameстрока

Имя, как его показывать в личном кабинете.

first_nameстрокаможет быть null

Имя.

last_nameстрокаможет быть null

Фамилия.

emailemailможет быть null

Основной email.

phoneстрокаможет быть null

Основной телефон, лучше в E.164. Номер в другой записи API приведёт к E.164.

positionстрокаможет быть null

Должность.

lifecycleстрока

Этап клиента.

Значения: leadmqlsqlcustomerchurned

statusстрока

active - рабочий контакт, archived - в архиве.

Значения: activearchived

Ответы

  • 200Контакт после изменения.
  • 401Нет ключа, ключ неверный, истёк или отозван (unauthenticated).
  • 402У компании не подключено дополнение «Публичный API» (api-addon-required).
  • 403У ключа нет нужного права или доступа к проекту (forbidden).
  • 404Объекта с таким id нет или он в проекте, которого нет в ключе (not-found).
  • 422Данные запроса не прошли проверку (validation). Какие поля и почему - в errors.
  • 429Превышен лимит запросов (rate-limited). Повторите через столько секунд, сколько указано в Retry-After.
  • 503Сервис временно недоступен (unavailable). Повторите позже.
Запрос 
curl -X PATCH https://api.ru.dialogi.io/v1/contacts/0192d3a1-7b2c-7c3e-9a51-2f6b8e4d1c90 \
  -H "Authorization: Bearer dk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "lifecycle": "lead",
    "status": "active"
  }'
Ответ 200
{
  "object": "contact",
  "id": "01a0d7f0-b6c0-7a1a-82e4-2cab98a901c7",
  "project_id": "01a0c4e2-3f10-7b4d-9c2e-5d8a1f6b3e20",
  "type": "person",
  "name": "Анна Смирнова",
  "first_name": "Анна",
  "last_name": "Смирнова",
  "email": "anna@example.com",
  "phone": "+79101234567",
  "position": null,
  "lifecycle": "lead",
  "status": "active",
  "source": "api",
  "metadata": {
    "crm_id": "A-10042"
  },
  "created_at": "2026-09-25T09:41:12Z",
  "updated_at": "2026-09-25T09:41:12Z"
}