#Минимизация и выбор полей

Статус: Доступно. Параметр fields= работает на чтении диалогов, сообщений и лидов во всех ячейках.

Назначение: как получить только нужные поля и почему персональные данные (ПДн) не приходят, пока вы не назовёте их явно.

#Содержание

Правило в одну строку
Где работает
Синтаксис
Какие поля относятся к ПДн
Примеры
Ошибки
Журнал выдач и формат JWE
Рекомендации

#Правило в одну строку

Без fields= приходят все поля объекта, кроме персональных.
Персональное поле приходит только если вы назвали его в fields=.
Поле id приходит всегда.

Так интеграция, которой нужны статусы и идентификаторы, не получает имён, почты, телефонов и текстов переписки, а значит, не хранит и не пересылает их дальше. Это минимизация данных: вы запрашиваете ровно то, что нужно для задачи.

#Где работает

Метод	Область	Объект
`GET /conversations`	`conversations:read`	диалог
`GET /conversations/{id}`	`conversations:read`	диалог
`GET /conversations/{id}/messages`	`conversations:read`	сообщение
`GET /leads`	`leads:read`	лид
`GET /leads/{id}`	`leads:read`	лид

Параметр одинаков у всех пяти методов и у всех ячеек (RU, EN, ID).

#Синтаксис

fields — одна строка, имена через запятую, до 2000 знаков и до 64 имён. Пробелы вокруг имён отбрасываются.

Что назвали	Что придёт
ничего (параметра нет или он пуст)	все поля, кроме ПДн
обычное поле, например `status`	`id` и это поле
ПДн-поле верхнего уровня, например `content`	`id` и это поле
вложенный путь, например `contact.email`	`id` и объект `contact` только с этим полем ПДн (остальные поля `contact`, не относящиеся к ПДн, остаются)
объект целиком, например `contact`	объект без своих ПДн-полей; ПДн внутри называют отдельно: `contact,contact.email`

Если вы назвали хотя бы одно поле, остальные поля не приходят: ответ ограничен названным и id. Чтобы получить «всё обычное плюс почту», перечислите обычные поля и добавьте contact.email.

#Какие поля относятся к ПДн

Объект	Поля ПДн
Диалог	`external_customer_id`
Сообщение	`content`, `attachments`
Лид	`contact.first_name`, `contact.last_name`, `contact.email`, `contact.phone`, `contact.geo_country`, `contact.geo_city`, `title`, `intent`, `ai_summary`, `score.reason`, `next_action`, `lost_reason`

Что не относится к ПДн: идентификаторы, статусы, режимы, даты, contact.id, contact.tags, источник и метки атрибуции, числовая оценка score.score и score.grade, сумма, cards сообщения (карточки товаров не содержат данных клиента).

Свободный текст лида (title, intent, ai_summary, next_action, lost_reason, score.reason) тоже в списке: его пишут люди и модель, и в нём встречаются имена, телефоны и почта. Внутренние заметки персонала наружу не отдаются вовсе.

#Примеры

Только статусы и время изменения диалогов, без ПДн:

curl -sS "$API_BASE_URL/conversations?limit=50&fields=status,mode,updated_at" \
  -H "Authorization: Bearer $API_KEY"

{
  "data": [
    { "id": "6f1c2c0e-0000-4000-8000-000000000001", "status": "open", "mode": "ai", "updated_at": "2026-10-12T09:15:00.000Z" }
  ],
  "next_cursor": null
}

Лид с почтой, но без остальных ПДн:

curl -sS "$API_BASE_URL/leads/$LEAD_ID?fields=status,value,contact,contact.email" \
  -H "Authorization: Bearer $API_KEY"

{
  "id": "9a7d4e10-0000-4000-8000-000000000002",
  "status": "qualified",
  "value": { "amount": 4900, "currency": "RUB" },
  "contact": { "id": "3b9e1f22-0000-4000-8000-000000000003", "tags": [], "email": "[email protected]" }
}

Сообщения с текстом (ПДн названы явно):

curl -sS "$API_BASE_URL/conversations/$CONVERSATION_ID/messages?fields=sender,created_at,content" \
  -H "Authorization: Bearer $API_KEY"

Те же сообщения без fields= придут без content и attachments: останутся отправитель, тип, карточки и время.

#Ошибки

Неизвестное имя не пропускается молча, а возвращает 422 validation_failed с указанием поля /fields и кодом unknown_field:

{
  "type": "https://formula-cream.pro/developers/errors#validation_failed",
  "title": "Запрос не прошёл проверку",
  "status": 422,
  "code": "validation_failed",
  "request_id": "req_EXAMPLE0004",
  "errors": [
    { "field": "/fields", "code": "unknown_field", "message": "Unknown field \"emial\"." }
  ]
}

Слишком длинный список (более 64 имён) даёт ту же 422, код причины too_many. Повтор без изменений бессмыслен: исправьте запрос.

#Журнал выдач и формат JWE

В журнал выдач ПДн (ячейки и данные) попадают только те поля, которые действительно были выданы. Запрос без ПДн-полей в журнал ничего не добавляет.
На ячейке RU области conversations:* и leads:* действуют только при узком списке разрешённых IP у ключа и стране получателя RU; иначе 403 pii_transfer_not_allowed приходит до чтения, и fields= этого не меняет (Передача ПДн). Минимизация уменьшает, сколько ПДн вы получаете, но не снимает условий допуска.
На ячейках EN и ID названные ПДн-поля могут прийти в формате JWE (Формат JWE для полей ПДн).

#Рекомендации

Всегда передавайте fields= в фоновых синхронизациях: им редко нужны тексты переписки.
Запрашивайте ПДн-поле только в тот момент, когда оно нужно, и не складывайте его в журналы своей системы.
Для обхода больших списков берите id и updated_at, а ПДн запрашивайте по одному объекту.
Не строите логику на отсутствии поля: поле, которого нет в ответе, не равно null. null значит «значения нет», а отсутствие значит «вы его не запрашивали».

Начало

Чаты и ИИ-продажник

Аналитика и дашборды

CRM и лиды

Статьи

Стратег

Дополнительно

Шаблоны и примеры

Справочник API