---
title: Recipients API — контакты, атрибуты, фильтры
description: Recipients API «Мой диалог» — управление получателями, атрибутами, фильтрами и тегами через API
---

> **For AI agents:** the complete documentation index is at [llms.txt](/llms.txt). Append `.md` to any page URL for its markdown version.

# Recipients API — контакты, атрибуты, фильтры

> **Коротко:** Recipients API управляет получателями: контактами, атрибутами, фильтрами (таргетами) и тегами. Доступен только в сервисе «Мой диалог».

## Кому подходит

- Роль: Разработчик, Интегратор
- Уровень: Опытный

## Что это

Recipients API — интерфейс для работы с базой получателей. Позволяет создавать, читать, обновлять и удалять контакты, управлять их атрибутами, а также получать списки фильтров и тегов.

Все эндпоинты используют префикс `/api/v1/recipient/`.

## Эндпоинты

| Метод | Эндпоинт | Для чего |
|---|---|---|
| GET | `/recipient/recipients` | Список получателей |
| POST | `/recipient/recipients` | Создать получателя |
| PUT | `/recipient/recipients` | Обновить получателя |
| DELETE | `/recipient/recipients` | Удалить получателя |
| GET | `/recipient/attributes` | Список атрибутов |
| POST | `/recipient/attributes` | Создать атрибут |
| PUT | `/recipient/attributes/{id}` | Обновить атрибут |
| DELETE | `/recipient/attributes/{id}` | Удалить атрибут |
| GET | `/recipient/attributes/types` | Типы атрибутов |
| GET | `/recipient/filters` | Список фильтров (таргетов) |
| GET | `/recipient/tags` | Список тегов |

Полный URL: `https://web.mydialogi.ru/api/v1/recipient/...`.

## Контакты

### Список получателей

**Эндпоинт:** `GET /recipient/recipients`

**Query-параметры:**

| Параметр | Тип | Обязательно | Что указать |
|---|---|---|---|
| email | string | Нет | Email получателя |
| phoneNumber | string | Нет | Номер телефона с кодом страны, без «+» |
| tags | string | Нет | Список тегов через запятую. Логика — OR |
| limit | integer | Нет | Максимум записей. По умолчанию 10 |
| offset | integer | Нет | Смещение. По умолчанию 0 |

<Note>
Можно также указать внутренние имена атрибутов как параметры. Например, `Age=30` — вернёт получателей с атрибутом Age, равным 30.
</Note>

**Пример 1. Список по тегам:**

```bash
curl --location 'https://web.mydialogi.ru/api/v1/recipient/recipients?limit=5&tags=test,test1' \
  --header 'X-API-Key: <ваш-ключ>'
```

**Пример 2. Список по атрибуту:**

```bash
curl --location 'https://web.mydialogi.ru/api/v1/recipient/recipients?limit=5&Age=30' \
  --header 'X-API-Key: <ваш-ключ>'
```

**Формат ответа:**

```json
{
  "limit": 5,
  "offset": 0,
  "size": 2,
  "results": [
    {
      "id": 14045930,
      "name": "Anna",
      "phoneNumber": "48732231269",
      "surname": null,
      "city": null,
      "email": "Anna.test@gmail.com",
      "tags": ["test"],
      "attributes": {
        "Age": 30
      }
    }
  ]
}
```

### Создание получателей

**Эндпоинт:** `POST /recipient/recipients`

**Тело запроса:**

| Поле | Тип | Обязательно | Что указать |
|---|---|---|---|
| type | string | Да | `ENRICH`, `NOT_IMPORT` или `OVERWRITE` |
| tag | string | Нет | Тег для всех импортируемых получателей |
| recipients | array | Да | Массив объектов получателей |

**Объект получателя в массиве `recipients`:**

| Поле | Тип | Обязательно | Что указать |
|---|---|---|---|
| phoneNumber | string | Да | Номер телефона с кодом страны, без «+» |
| name | string | Нет | Имя |
| surname | string | Нет | Фамилия |
| city | string | Нет | Город |
| email | string | Нет | Email |
| attributes | object | Нет | Дополнительные атрибуты |
| tags | array | Нет | Список тегов |

**Пример:**

```bash
curl --location 'https://web.mydialogi.ru/api/v1/recipient/recipients' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <ваш-ключ>' \
  --data-raw '{
    "recipients": [
      {
        "email": "test.email@gmail.com",
        "tags": ["test1"]
      },
      {
        "name": "Alice",
        "phoneNumber": "48732231255",
        "tags": ["test2"]
      }
    ],
    "tag": "test-test",
    "type": "ENRICH"
  }'
```

**Формат ответа:**

| Поле | Что означает |
|---|---|
| imported | Сколько записей импортировано |
| overwritten | Сколько записей перезаписано |
| failed | Сколько записей не импортировано из-за ошибки |
| enriched | Сколько записей обогащено |

```json
{
  "imported": 1,
  "overwritten": 0,
  "failed": 1,
  "enriched": 0
}
```

<Note>
Поле `phoneNumber` обязательно. Если его нет — запись не создаётся.
</Note>

### Обновление получателя

**Эндпоинт:** `PUT /recipient/recipients`

**Тело запроса:**

| Поле | Тип | Обязательно | Что указать |
|---|---|---|---|
| phoneNumber | string | Да | Номер телефона получателя |
| name | string | Нет | Имя |
| surname | string | Нет | Фамилия |
| city | string | Нет | Город |
| email | string | Нет | Email |
| attributes | object | Нет | Дополнительные атрибуты |
| tags | array | Нет | Список тегов |

**Пример:**

```bash
curl --location --request PUT 'https://web.mydialogi.ru/api/v1/recipient/recipients' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <ваш-ключ>' \
  --data-raw '{
    "phoneNumber": "48732231255",
    "name": "Alice",
    "attributes": {
      "Age": 25
    },
    "tags": ["new tag"]
  }'
```

**Формат ответа** — обновлённый объект получателя.

### Удаление получателя

**Эндпоинт:** `DELETE /recipient/recipients`

**Тело запроса:**

| Поле | Тип | Обязательно | Что указать |
|---|---|---|---|
| phoneNumber | string | Да* | Номер телефона |
| email | string | Да* | Email |

> *- нужен либо `phoneNumber`, либо `email`.

**Пример:**

```bash
curl --location --request DELETE 'https://web.mydialogi.ru/api/v1/recipient/recipients' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <ваш-ключ>' \
  --data-raw '{
    "phoneNumber": "4915735987904"
  }'
```

<Note>
Если в базе несколько получателей с одинаковым email — API вернёт ошибку. Удаляйте по номеру телефона.
</Note>

## Атрибуты

Атрибуты — дополнительные поля контакта (например, возраст, город, hobby).

### Список атрибутов

**Эндпоинт:** `GET /recipient/attributes`

```bash
curl --location 'https://web.mydialogi.ru/api/v1/recipient/attributes' \
  --header 'X-API-Key: <ваш-ключ>'
```

**Формат ответа:**

```json
{
  "limit": 0,
  "offset": 0,
  "size": 8,
  "results": [
    {
      "id": 1,
      "name": "phoneNumber",
      "typeId": 5,
      "type": null,
      "title": "Phone number",
      "nullable": false
    },
    {
      "id": 3,
      "name": "name",
      "typeId": 7,
      "type": null,
      "title": "Name",
      "nullable": true
    }
  ]
}
```

**Поля атрибута:**

| Поле | Что означает |
|---|---|
| id | ID атрибута |
| name | Внутреннее имя (используется в API) |
| title | Отображаемое имя |
| typeId | ID типа атрибута |
| nullable | Может ли быть пустым |

### Создание атрибута

**Эндпоинт:** `POST /recipient/attributes`

**Тело запроса:**

| Поле | Тип | Обязательно | Что указать |
|---|---|---|---|
| name | string | Да | Внутреннее имя атрибута |
| title | string | Да | Отображаемое имя |
| typeId | integer | Да | ID типа атрибута |
| nullable | boolean | Нет | Может ли быть пустым |

### Обновление атрибута

**Эндпоинт:** `PUT /recipient/attributes/{id}`

**Тело запроса:**

| Поле | Тип | Что указать |
|---|---|---|
| name | string | Новое внутреннее имя |
| title | string | Новое отображаемое имя |
| isToCard | boolean | Показывать ли атрибут в карточке |

### Удаление атрибута

**Эндпоинт:** `DELETE /recipient/attributes/{id}`

Успешное удаление возвращает `204 No Content`.

## Типы атрибутов

**Эндпоинт:** `GET /recipient/attributes/types`

```bash
curl --location 'https://web.mydialogi.ru/api/v1/recipient/attributes/types' \
  --header 'X-API-Key: <ваш-ключ>'
```

**Базовые типы (`baseType`):**

| Тип | Что означает |
|---|---|
| BOOLEAN | Логическое значение |
| DATE | Дата |
| NUMBER | Число |
| TEXT | Текст |

## Фильтры (таргеты)

**Эндпоинт:** `GET /recipient/filters`

Возвращает список фильтров (таргетов) компании.

```bash
curl --location 'https://web.mydialogi.ru/api/v1/recipient/filters' \
  --header 'X-API-Key: <ваш-ключ>'
```

**Формат ответа:**

| Поле | Что означает |
|---|---|
| data | Список фильтров |
| totalCount | Общее количество фильтров |

**Поля фильтра:**

| Поле | Что означает |
|---|---|
| id | ID фильтра |
| name | Название |
| condition | Условие |
| expressions | Список выражений фильтра |
| recipients | Количество получателей в фильтре |
| launches | Количество запусков |
| createdAt | Дата создания |
| updatedAt | Дата обновления |
| visible | Видимость |

## Теги

**Эндпоинт:** `GET /recipient/tags`

Возвращает список всех тегов компании.

```bash
curl --location 'https://web.mydialogi.ru/api/v1/recipient/tags' \
  --header 'X-API-Key: <ваш-ключ>'
```

Ответ — массив строк с названиями тегов.

## Коды ответов

| Код | Что означает |
|---|---|
| 200 OK | Успешно |
| 204 No Content | Успешно, тело пустое (для удаления) |
| 400 | Ошибка параметров |
| 401 | Неверный или отсутствующий API-ключ |
| 403 | Нет прав |
| 404 | Ресурс не найден |
| 500 | Внутренняя ошибка сервера |

**Пример ответа с ошибкой:**

```json
{
  "execId": null,
  "key": "errors.recipient_service.phone_not_valid",
  "code": "ValidationError",
  "message": "Phone number can`t be null",
  "args": null
}
```

## Частые проблемы

<Accordion title="400 Bad Request: Phone number can't be null">
**Причина:** в запросе не указан обязательный `phoneNumber`.

**Решение:** укажите номер телефона с кодом страны, без «+».
</Accordion>

<Accordion title="400 Bad Request: Recipient type can't be null">
**Причина:** при создании получателей не указан `type`.

**Решение:** укажите один из вариантов: `ENRICH`, `NOT_IMPORT`, `OVERWRITE`.
</Accordion>

<Accordion title="400 Bad Request: Selected filter's attributes don't exist">
**Причина:** в запросе указан атрибут, которого нет в системе.

**Решение:** проверьте список атрибутов через `GET /recipient/attributes`.
</Accordion>

<Accordion title="400 Bad Request: More than one recipient found">
**Причина:** удаление по email, а в базе несколько получателей с таким email.

**Решение:** удаляйте по номеру телефона — он уникален.
</Accordion>

<Accordion title="401 Unauthorized">
**Причина:** неверный или отсутствующий API-ключ.

**Решение:** проверьте заголовок `X-API-Key`.
</Accordion>

<Accordion title="403 Forbidden">
**Причина:** у ключа нет scope `recipients`.

**Решение:** откройте ключ в разделе **API Подключения** и добавьте нужный scope.
</Accordion>

## См. также

<Columns cols={2}>
  <Card title="OMNI API — отправка сообщений" icon="paper-plane" href="/04-mydialogi/09-api/md-api-omni">
    Эндпоинты `/messages`, `/omnimessages`
  </Card>
  <Card title="Broadcasts API" icon="bullhorn" href="/04-mydialogi/09-api/md-api-broadcasts">
    Запуск рассылок, шаблоны
  </Card>
  <Card title="Подключение к API" icon="plug" href="/04-mydialogi/09-api/md-api-connection">
    Аутентификация и базовый URL
  </Card>
  <Card title="Обзор API «Мой диалог»" icon="book" href="/04-mydialogi/09-api/md-api-overview">
    OMNI, Broadcasts, Recipients — обзор
  </Card>
</Columns>

## Нужна помощь?

- Мой диалог: support@mydialogi.ru