Для AI-агентов: markdown этой страницы — /docs-content/entities/leads/fields.md индекс документации — /llms.txt

Поля лида

GET /v1/leads/fields

Возвращает полный список доступных полей, включая пользовательские (ufCrm_*).

Примеры

curl — личный ключ

Terminal 
curl "https://vibecode.bitrix24.tech/v1/leads/fields" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth-приложение

Terminal 
curl "https://vibecode.bitrix24.tech/v1/leads/fields" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — личный ключ

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/leads/fields', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data } = await res.json()
console.log('Полей:', Object.keys(data.fields).length)

JavaScript — OAuth-приложение

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/leads/fields', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { success, data } = await res.json()

Поля ответа

Подписи полей label и description приходят на русском языке, а те, что платформа берёт напрямую с портала, — на языке портала. Заголовками запроса язык не переключается.

Поле Тип RO Описание
id number да ID лида
title string Название лида
name string Имя
lastName string Фамилия
secondName string Отчество
stageId string Статус (стадия) лида — каноническое имя в ответах: NEW, IN_PROCESS, … Список: GET /v1/statuses?filter[entityId]=STATUS
statusId string Алиас stageId на запись, в фильтрах и сортировке. Важно: в ответах list/get/search значение приходит в поле stageId, ключ statusId в ответе не возвращается — читайте stageId. Не передавайте алиас и каноническое имя одновременно в одном запросе
stageSemanticId string да Смысловая категория стадии: P — в работе, S — успех, F — провал. Только чтение. Принимается в фильтре и сортировке
companyTitle string Название компании
companyId number ID компании. Поиск: GET /v1/companies
contactId number ID контакта. Поиск: GET /v1/contacts
opportunity number Сумма — каноническое имя в ответах. Важно: чтобы записанное значение сохранилось, передайте isManualOpportunity: true в том же запросе
amount number Алиас opportunity на запись/в фильтрах. В ответах значение приходит в поле opportunity
isManualOpportunity boolean Ручной режим суммы. Без true сумма пересчитывается по товарным позициям и записанное значение затирается
currency string Алиас currencyId на запись/в фильтрах. Валюта. Список: GET /v1/currencies
currencyId string Валюта — каноническое имя в ответах
sourceId string Источник. Список: GET /v1/statuses?filter[entityId]=SOURCE
sourceDescription string Описание источника
assignedById number Ответственный. Список: GET /v1/users
createdBy number да Создатель. Поиск: GET /v1/users
opened boolean Доступен для всех
comments string Комментарий
post string Должность
phone multifield Телефон. На вход (POST/PATCH) принимает string | string[] | object[]. На выходе phone — строка с первичным значением, значения по типам — в полях phoneWork/phoneMobile, полный перечень с типами — в массиве fm[] (формат { id, typeId, valueType, value }). Важно: PATCH только добавляет новые записи — старые phone не удаляются. См. Обновить лид. UPPER-форма [{ "VALUE": "...", "VALUE_TYPE": "WORK" }] не принимается — вернёт 400 INVALID_MULTIFIELD_SHAPE. Используйте camelCase: [{ "value": "...", "typeId": "WORK" }].
email multifield Email. На вход принимает string | string[] | object[]. На выходе email — строка с первичным значением, значения по типам — в полях emailWork/emailHome/emailMailing, полный перечень — в массиве fm[]. Важно: PATCH только добавляет новые записи — старые email не удаляются. UPPER-форма [{ "VALUE": "...", "VALUE_TYPE": "WORK" }] не принимается — вернёт 400 INVALID_MULTIFIELD_SHAPE. Используйте camelCase: [{ "value": "...", "typeId": "WORK" }].
birthdate datetime Дата рождения
hasPhone boolean да Указан ли телефон
hasEmail boolean да Указан ли email
hasImol boolean да Есть ли контакт в открытой линии
isReturnCustomer boolean да Повторное обращение
createdTime datetime да Дата создания
updatedTime datetime да Дата изменения
originatorId string Внешний источник — идентификатор внешней системы, из которой импортирован лид. Приходит null для лидов, созданных в Битрикс24
dateClosed datetime да Дата закрытия лида. Приходит null, пока лид не закрыт
lastCommunicationTime string да Дата последней коммуникации с лидом. Приходит null, если её не было
utmSource string Метка utm_source источника трафика. Приходит null, если не задана
utmMedium string Метка utm_medium источника трафика. Приходит null, если не задана
utmCampaign string Метка utm_campaign источника трафика. Приходит null, если не задана
utmContent string Метка utm_content источника трафика. Приходит null, если не задана
utmTerm string Метка utm_term источника трафика. Приходит null, если не задана

UTM-поля возвращаются в list/get, но в фильтре и сортировке не принимаются. Запрос с filter[utmSource] отвечает 400 UNKNOWN_FILTER_FIELD, с sort=utmSource — 400 UNKNOWN_SORT_FIELD, и оба отказа приходят до обращения к Битрикс24.

Пользовательские поля (ufCrm_*) также возвращаются в ответах и принимаются при создании/обновлении.

Доступные include

Эндпоинт GET /v1/leads/fields возвращает список доступных include: contact, company.

Пример использования: Получить leads.

Подробнее об include: Связанные данные.

Пример ответа

JSON 
{
  "success": true,
  "data": {
    "fields": {
      "id": { "type": "number", "readonly": true, "label": "ID лида", "description": "Уникальный числовой идентификатор лида." },
      "title": { "type": "string", "readonly": false, "label": "Название лида", "description": "Название лида." },
      "stageSemanticId": { "type": "string", "readonly": true, "label": "Семантика стадии", "description": "Смысловая категория текущей стадии — коды расшифрованы в enum.", "enum": [{ "value": "P", "label": "In progress", "labelRu": "В работе" }, { "value": "S", "label": "Success", "labelRu": "Успех" }, { "value": "F", "label": "Failure", "labelRu": "Провал" }] },
      "assignedById": { "type": "number", "readonly": false, "label": "Ответственный", "description": "ID ответственного пользователя. Список: GET /v1/users." }
    },
    "batch": ["create", "update", "delete"]
  }
}

Показаны 4 из множества полей. Полный список в таблице выше.

Ошибки

HTTP Код Описание
403 SCOPE_DENIED API-ключ не имеет скоупа crm
401 TOKEN_MISSING API-ключ не имеет настроенных токенов

Полный список общих ошибок API — Ошибки.

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