Поля лида

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).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()

Поля ответа

Поле Тип 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. Не передавайте алиас и каноническое имя одновременно в одном запросе
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 для лидов, созданных в Bitrix24
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, если не задана

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

Доступные include

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

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

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

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

JSON 
{
  "success": true,
  "data": {
    "fields": {
      "id": { "type": "number", "readonly": true },
      "title": { "type": "string", "readonly": false },
      "assignedById": { "type": "number", "readonly": false }
    },
    "batch": ["create", "update", "delete"]
  }
}

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

Пример ответа при ошибке

404 — не найден:

JSON 
{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Элемент не найден"
  }
}

Ошибки

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

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

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