# Контакты лида

Привязывает контакты к лиду, заменяет их состав, читает список и отвязывает по одному или все сразу. Связь хранит порядок контакта в списке и признак основного контакта. Сами контакты при отвязке остаются в CRM.

У лида с контактами всегда один основной контакт. Его ID приходит в поле лида `contactId`, ID всех привязанных — в поле `contactIds`. Состав контактов меняйте методами ниже: `PATCH /v1/leads/:id` с этими полями заменяет состав целиком и может отвязать остальные контакты.

Битрикс24 API: `crm.lead.contact.items.get`, `crm.lead.contact.add`, `crm.lead.contact.items.set`, `crm.lead.contact.delete`, `crm.lead.contact.items.delete`
Скоуп: `crm`

## Операции

- [Список контактов лида](./contacts-list.md) — `GET /v1/leads/:id/contacts`
- [Заменить контакты лида](./contacts-set.md) — `PUT /v1/leads/:id/contacts`
- [Привязать контакт к лиду](./contacts-create.md) — `POST /v1/leads/:id/contacts`
- [Отвязать контакт от лида](./contacts-delete-delete.md) — `DELETE /v1/leads/:id/contacts/:relatedId`
- [Отвязать все контакты от лида](./contacts-delete.md) — `DELETE /v1/leads/:id/contacts`

## Ключевые поля

Поля одной связи лида с контактом. Они приходят в каждом элементе `data`. Поля `contactId`, `isPrimary` и `sort` принимают также привязка и замена.

| Поле | Описание |
|------|----------|
| `contactId` | ID контакта. Список: [`GET /v1/contacts`](/docs/entities/contacts/list) |
| `isPrimary` | Основной контакт лида. `true` ровно у одной связи |
| `sort` | Порядок контакта в списке. Список связей приходит отсортированным по этому полю |
| `roleId` | Роль контакта в лиде. Методы связей её не сохраняют: `roleId` из запроса игнорируется |

Полный список полей самого лида — [`GET /v1/leads/fields`](/docs/entities/leads/fields).

## Что нужно знать перед работой

1. **У лида с контактами всегда есть основной.** Первый привязанный контакт становится основным, даже если передан `isPrimary: false`. `isPrimary: true` в привязке или замене переносит признак на этот контакт. Если при замене ни у одного элемента нет `true`, основным становится первый элемент массива. Если `true` у нескольких элементов — первый из них. Если отвязать основной контакт, основным становится первый из оставшихся в порядке `sort`.
2. **Существование контакта не проверяется.** Привязка и замена принимают ID, которого нет среди контактов, отвечают `200` и сохраняют такую связь. Проверяйте ID через [`GET /v1/contacts/:id`](/docs/entities/contacts/get) до привязки.
3. **Список не проверяет лид.** Для ID лида, которого нет или который удалён, [`GET /v1/leads/:id/contacts`](./contacts-list.md) отвечает `200` с пустым `data`, как для лида без контактов. Существование лида проверяйте через [`GET /v1/leads/:id`](/docs/entities/leads/get). Привязка, замена и отвязки для несуществующего лида отвечают `404 ENTITY_NOT_FOUND`.
4. **Повторы ведут себя по-разному.** Повторная привязка того же контакта отвечает `409 RELATION_ALREADY_EXISTS`, повторная отвязка одного контакта — `404 ENTITY_NOT_FOUND`, повторная отвязка всех — снова `204`.
5. **Методы записи отвечают по-разному.** Привязка и замена возвращают весь список связей после изменения, обе отвязки — `204 No Content` с пустым телом.
6. **`PATCH` лида меняет состав целиком.** [`PATCH /v1/leads/:id`](/docs/entities/leads/update) с `contactIds` оставляет у лида только перечисленные контакты, `[]` отвязывает всех. С `contactId` ещё не привязанного контакта у лида остаётся только этот контакт. С `contactId` уже привязанного контакта метод отвечает `200` и ничего не меняет: основным контакт не становится.
7. **Сконвертированный лид принимает правки связей.** У лида на стадии `CONVERTED` работают все пять операций со связями.

## Типичный сценарий

1. Найти контакт: [`GET /v1/contacts`](/docs/entities/contacts/list) с фильтром по полям контакта.
2. Посмотреть, кто уже привязан к лиду: [`GET /v1/leads/:id/contacts`](./contacts-list.md).
3. Привязать контакт и при необходимости сделать его основным: [`POST /v1/leads/:id/contacts`](./contacts-create.md) с `isPrimary: true`.
4. Задать состав целиком, например при синхронизации с внешней системой: [`PUT /v1/leads/:id/contacts`](./contacts-set.md) со всеми нужными контактами в `items`.
5. Прочитать лид вместе с полными записями контактов: [`GET /v1/leads/:id?include=contactBinding`](/docs/entities/leads/get), контакты — в `data._included.contactBindings`. С `include=contact` в `data._included.contact` приходит один объект — основной контакт.

## Лимиты

| Лимит | Значение |
|-------|----------|
| Пагинация списка | Нет: [`GET /v1/leads/:id/contacts`](./contacts-list.md) возвращает все связи лида за один вызов |
| Частота чтения списка | Маршрутный лимит: 300 запросов в минуту на портал, все API-ключи портала делят один лимит. Действующее значение маршрутного лимита — в заголовке `x-ratelimit-limit` |
| Частота записи | Общие лимиты API — [Лимиты и оптимизация](/docs/optimization) |
| Контактов за одну привязку | Один. Несколько контактов сразу — [`PUT /v1/leads/:id/contacts`](./contacts-set.md), в его `items` передайте весь нужный состав: контакты, которых нет в `items`, отвяжутся |

## Смотрите также

- [Лиды](/docs/entities/leads)
- [Получить лид](/docs/entities/leads/get)
- [Обновить лид](/docs/entities/leads/update)
- [Поля лида](/docs/entities/leads/fields)
- [Контакты](/docs/entities/contacts)
- [Лимиты и оптимизация](/docs/optimization)
