#Пользовательские поля (Userfields)

Управляйте пользовательскими полями CRM-сущностей через API. Создавайте списки, текстовые поля, даты и другие типы — без захода в интерфейс Битрикс24.

#Обзор

Userfields API позволяет программно управлять пользовательскими (custom) полями для CRM-сущностей. Поддерживаются 16 типов полей: строки, числа, списки, даты, файлы, привязки к сотрудникам и CRM-сущностям.

Поддерживаемые сущности: deals, leads, contacts, companies, quotes

Требуемый скоуп: crm

Базовый URL: https://vibecode.bitrix24.tech/v1

Авторизация: заголовок X-Api-Key с вашим API-ключом.

#Быстрый старт

#1. Посмотрите существующие поля

Terminal 
curl -H "X-Api-Key: $VIBE_KEY" \
  "https://vibecode.bitrix24.tech/v1/userfields/deals"

Ответ:

JSON 
{
  "success": true,
  "data": [
    {
      "id": 386,
      "fieldName": "UF_CRM_1545731745470",
      "userTypeId": "enumeration",
      "sort": "100",
      "multiple": "N",
      "mandatory": "N",
      "editFormLabel": { "ru": "Модуль" },
      "list": [
        { "ID": "202", "SORT": "10", "VALUE": "Документооборот", "DEF": "N" }
      ]
    }
  ],
  "meta": { "total": 141 }
}

#2. Создайте поле-список

Terminal 
curl -X POST https://vibecode.bitrix24.tech/v1/userfields/deals \
  -H "X-Api-Key: $VIBE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userTypeId": "enumeration",
    "fieldName": "DEPARTMENT",
    "label": "Отдел",
    "mandatory": "N",
    "list": [
      { "VALUE": "Веб", "SORT": 10 },
      { "VALUE": "1С", "SORT": 20 }
    ]
  }'

Ответ:

JSON 
{
  "success": true,
  "data": { "id": 4200 }
}

#3. Обновите поле

Terminal 
curl -X PATCH https://vibecode.bitrix24.tech/v1/userfields/deals/4200 \
  -H "X-Api-Key: $VIBE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mandatory": "Y",
    "label": "Отдел (обязательно)"
  }'

#Список полей

#GET /v1/userfields/:entity

Возвращает все пользовательские поля для указанной сущности. Поля отсортированы по sort (ASC).

URL-параметр:

Параметр Описание
:entity Сущность: deals, leads, contacts, companies, quotes

Query-параметры (фильтрация):

Параметр Тип Описание
userTypeId string Фильтр по типу поля (string, enumeration, datetime и т.д.)
fieldName string Фильтр по имени поля (UF_CRM_...)
Terminal 
# Все поля сделок
curl -H "X-Api-Key: $VIBE_KEY" \
  "https://vibecode.bitrix24.tech/v1/userfields/deals"

# Только поля-списки
curl -H "X-Api-Key: $VIBE_KEY" \
  "https://vibecode.bitrix24.tech/v1/userfields/deals?userTypeId=enumeration"

# Поле по имени
curl -H "X-Api-Key: $VIBE_KEY" \
  "https://vibecode.bitrix24.tech/v1/userfields/contacts?fieldName=UF_CRM_1545731745470"

JavaScript:

javascript 
const res = await fetch(
  'https://vibecode.bitrix24.tech/v1/userfields/deals?userTypeId=enumeration',
  { headers: { 'X-Api-Key': VIBE_KEY } }
)

const { data, meta } = await res.json()
console.log(`Полей-списков: ${meta.total}`)
data.forEach(f => console.log(`${f.fieldName}: ${f.editFormLabel?.ru ?? '—'}`))

#Типы полей