> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Управление контактами

> Создавайте и ведите профили клиентов, используемые во всех рабочих процессах YCloud.

## Что это такое

В контактах хранятся идентификационные данные и сведения профиля клиента, такие как номер телефона, адрес электронной почты, теги, пользовательские атрибуты и ответственный. Другие функции YCloud могут использовать контакты для сегментации, событий, рассылок и сервисных рабочих процессов.

## Перед началом работы

* Приведите номера телефонов к формату E.164.
* Определите, какая система является источником для каждого поля профиля.
* Создайте пользовательские атрибуты перед записью зависящих от них значений.
* Установите правила получения согласий и хранения клиентских данных.

## Как это работает

1. Создайте контакт с уникальным номером телефона.
2. Сохраните возвращенный ID контакта.
3. Получайте или выводите списком контакты по идентификаторам и фильтрам.
4. Обновляйте профиль, теги, пользовательские атрибуты или ответственного.
5. Удаляйте контакт в соответствии с политикой хранения данных.

Используйте события webhook для синхронизации создания, удаления и изменения атрибутов контактов со сторонними системами.

## Запрос

`POST /contact/contacts`

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request POST https://api.ycloud.com/v2/contact/contacts \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "nickname": "Avery",
    "phoneNumber": "+16315551111",
    "countryCode": "US",
    "email": "avery@example.com",
    "tags": ["customer", "vip"],
    "customAttributes": [
      {
        "name": "plan",
        "value": "premium"
      }
    ],
    "ownerEmail": "sales@example.com"
  }'
```

Для создания контакта обязательно только поле `phoneNumber`. Правила уникальности электронной почты и номера телефона продолжают действовать, если эти поля переданы.

## Ответ

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "1693364594105000000",
  "nickname": "Avery",
  "phoneNumber": "+16315551111",
  "countryCode": "US",
  "email": "avery@example.com",
  "tags": ["customer", "vip"],
  "sourceType": "API",
  "createTime": "2026-07-16T12:00:00.000Z"
}
```

Сохраните `id` в качестве постоянного идентификатора контакта в YCloud. Используйте его при отправке кастомных событий или сопоставлении изменений из webhook.

## Поиск и пагинация

Получайте списки контактов с фильтрами по тегу, коду страны, номеру телефона или электронной почте. Используйте явную пагинацию и сохраняйте параметры фильтрации между страницами.

## Согласованность данных

* Выберите единую мастер-систему (system of record) для каждого поля.
* Относитесь к обновлениям из webhook как к событиям, а не гарантированно полным заменяющим записям.
* Обеспечьте идемпотентность операций импорта и обработчиков webhook.
* Не допускайте перезаписи более актуальных данных клиента запоздавшими событиями.

## Ограничения и устранение неполадок

* Номера телефонов должны быть в формате E.164.
* Адреса электронной почты при их указании должны быть валидными и уникальными.
* Контакт поддерживает до 50 тегов с ограничениями по длине для конкретных полей.
* Используйте эндпоинт атрибутов контактов для получения списка доступных пользовательских атрибутов.
* Удаляйте персональные данные из общих логов и материалов для службы поддержки.

<CardGroup cols={2}>
  <Card title="API создания контакта" icon="user-plus" href="/api-reference/contacts/create-a-contact">
    Изучите форматы полей, ограничения и полный ответ.
  </Card>

  <Card title="Webhook контактов" icon="webhook" href="/ru/api-reference/guides/examples/webhook-examples/contact-created-webhook-examples">
    Обрабатывайте создание, удаление, изменение атрибутов и отписку.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.