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

Поля контакта

GET /v1/contacts/fields

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

Примеры

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

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

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

Terminal 
curl "https://vibecode.bitrix24.tech/v1/contacts/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/contacts/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/contacts/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 контакта
name string Имя, не более 50 кодовых точек Unicode. Более длинное значение отклоняется до записи; имя не обрезается.
lastName string Фамилия
secondName 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" }]. Объект с полем id не принимается ни на одной двери записи — 400 MULTIFIELD_ID_NOT_SUPPORTED, ничего не записывается. То же касается записи с id в сыром массиве fm[].
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" }]. Объект с полем id не принимается ни на одной двери записи — 400 MULTIFIELD_ID_NOT_SUPPORTED, ничего не записывается. То же касается записи с id в сыром массиве fm[].
phoneWork string да Рабочий телефон, развёрнутый из мультиполя phone. Только для чтения: номер записывается через phone; присланное значение не сохраняется ни на одной двери, поэтому запись отклоняется: создание и изменение — 400 READONLY_FIELD, импорт — 400 IMPORT_ITEM_VALIDATION, пакет сущности — 400 BATCH_ITEM_VALIDATION, общий пакет — READONLY_FIELD под вызовом. null, если такого номера нет. Фильтр (точный и $contains) и сортировка работают
phoneMobile string да Мобильный телефон, развёрнутый из мультиполя phone. Только для чтения, как phoneWork. null, если такого номера нет
phoneMailing string да Телефон для рассылок, развёрнутый из мультиполя phone. Только для чтения, как phoneWork. null, если такого номера нет
imol string да Контакт человека в открытой линии (мессенджере), развёрнутый из коллекции мультиполей. Только для чтения. null, если такого контакта нет
address string да Адрес контакта одной строкой (старая колонка). Битрикс24 отдаёт её, но не сохраняет через item-API, которым пишет этот метод: присланное значение не сохраняется ни на одной двери записи, запрос отклоняется (коды — как у phoneWork); заполняет её только старый метод crm.contact.add прежних интеграций, а адрес правится в реквизитах контакта. null, если не заполнен. Фильтр (точный и $contains) и сортировка работают
shortName string да Краткое имя — фамилия с инициалами («Иванов И. И.»), вычисляет Битрикс24. Приходит только в списке или поиске, где поле названо в select явно (без *); одиночный GET /v1/contacts/{id}, список без select и список пачки сущности (её select — проекция) отдают null. Только для чтения (коды отказа — как у phoneWork). Фильтр (точный и $contains) и сортировка работают
hasPhone boolean да Указан ли телефон
hasEmail boolean да Указан ли email
hasImol boolean да Есть ли контакт в открытой линии
companyId number ID компании. Поиск: GET /v1/companies
post string Должность
comments string Комментарий
typeId string Тип контакта. Список: GET /v1/statuses?filter[entityId]=CONTACT_TYPE
sourceId string Источник. Список: GET /v1/statuses?filter[entityId]=SOURCE
sourceDescription string Описание источника
assignedById number Ответственный. Список: GET /v1/users
createdBy number да Создатель. Поиск: GET /v1/users
updatedBy number да Кто изменил. Поиск: GET /v1/users
createdTime datetime да Дата создания
updatedTime datetime да Дата изменения
opened boolean Доступен для всех
export boolean Разрешён экспорт
leadId number ID лида-источника
honorific string Обращение. Список: GET /v1/statuses?filter[entityId]=HONORIFIC

Пользовательские поля (ufCrm*) также возвращаются в ответах и принимаются при создании/обновлении. У поля типа enumeration в ответе этого эндпоинта по пути data.fields.<имя поля>.items приходит массив вариантов вида { "ID": "3989", "VALUE": "warm" }. Для записи в пользовательское поле берётся ID, а VALUE — подпись варианта для показа. Подпись, отправленная вместо идентификатора, теряется без ошибки. Подробнее — Формат значения по типам.

Доступные include

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

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

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

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

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

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

Ошибки

HTTP Код Описание
403 SCOPE_DENIED API-ключ не имеет скоупа crm
401 TOKEN_MISSING API-ключ не имеет настроенных токенов
429 RATE_LIMITED Превышен лимит запросов: 300 в минуту на портал, все API-ключи портала делят один лимит. Точное значение — в заголовке x-ratelimit-limit (потолок делится на реплики). Повторите после срока из заголовка Retry-After

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

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