#User fields

Manage user fields of Bitrix24 CRM entities and smart processes: create, update, delete text fields, lists, dates, numbers, bindings to employees and CRM entities. Changes apply to the entity's fields across the whole portal — keep this in mind when working on production data.

Scope: crm, userfieldconfig | Base URL: https://vibecode.bitrix24.tech/v1 | Authorization: X-Api-Key

Quick start | Full example | Endpoint reference | Error codes

#Documentation sections

#Quick start

#1. View existing deal fields

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

Response:

JSON 
{
  "success": true,
  "data": [
    {
      "id": 7115,
      "entityId": "CRM_DEAL",
      "fieldName": "UF_CRM_PROJECT_CODE",
      "userTypeId": "string",
      "mandatory": "N",
      "sort": "100",
      "editFormLabel": { "ru": "Project code" }
    }
  ],
  "meta": { "total": 44 }
}

#2. Create a new field

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/userfields/deals" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userTypeId": "string",
    "fieldName": "PROJECT_CODE",
    "label": "Project code"
  }'

On successful creation, returns HTTP 201 Created with the numeric id of the new field.

#Full example

Scenario: add a list field "Lead source", fetch its full description, make it visible in the filter, delete it.

javascript 
const KEY = process.env.VIBECODE_API_KEY
const BASE = 'https://vibecode.bitrix24.tech/v1'

async function api(method, path, body) {
  const opts = { method, headers: { 'X-Api-Key': KEY } }
  if (body) {
    opts.headers['Content-Type'] = 'application/json'
    opts.body = JSON.stringify(body)
  }
  const res = await fetch(`${BASE}${path}`, opts)
  return res.status === 204 ? null : res.json()
}

// 1. Find out how many user fields already exist
const before = await api('GET', '/userfields/deals')
console.log(`Fields before creation: ${before.meta.total}`)

// 2. Create a list field "Lead source"
const created = await api('POST', '/userfields/deals', {
  userTypeId: 'enumeration',
  fieldName: 'LEAD_SOURCE',
  label: 'Lead source',
  mandatory: 'Y',
  list: [
    { VALUE: 'Website', SORT: 10 },
    { VALUE: 'Social media', SORT: 20 },
    { VALUE: 'Advertising', SORT: 30 }
  ]
})
const newId = created.data.id
console.log('Created field with id:', newId)

// 3. Fetch the full description of the created field
const detail = await api('GET', `/userfields/deals/${newId}`)
console.log('List options:', detail.data.list.map(v => v.VALUE).join(', '))

// 4. Make the field visible in the card filter
await api('PATCH', `/userfields/deals/${newId}`, { showFilter: 'Y' })

// 5. Delete the field — response HTTP 204 with empty body
await api('DELETE', `/userfields/deals/${newId}`)
console.log('Field deleted')

#Endpoint reference

#CRM entity fields

Method Path Bitrix24 method Description
GET /v1/userfields/:entity crm.:entity.userfield.list List entity fields
GET /v1/userfields/:entity/types crm.userfield.types Field type catalog
GET /v1/userfields/:entity/:id crm.:entity.userfield.get Single field by identifier
POST /v1/userfields/:entity crm.:entity.userfield.add Create field
PATCH /v1/userfields/:entity/:id crm.:entity.userfield.update Update field
DELETE /v1/userfields/:entity/:id crm.:entity.userfield.delete Delete field

:entity — one of: deals, leads, contacts, companies, quotes, requisites.

#Smart process fields

Method Path Bitrix24 method Description
GET /v1/items/:entityTypeId/userfields userfieldconfig.list List smart process fields
GET /v1/items/:entityTypeId/userfields/types crm.userfield.types Field type catalog
GET /v1/items/:entityTypeId/userfields/:id userfieldconfig.get Single field by identifier
POST /v1/items/:entityTypeId/userfields userfieldconfig.add Create field
PATCH /v1/items/:entityTypeId/userfields/:id userfieldconfig.update Update field
DELETE /v1/items/:entityTypeId/userfields/:id userfieldconfig.delete Delete field

entityTypeId — the smart process type identifier from the `GET /v1/smart-processes` response.

#Error codes

#User field errors

HTTP Code Description
400 UNKNOWN_ENTITY Entity is not in the supported list (deals, leads, contacts, companies, quotes, requisites)
400 INVALID_ENTITY_TYPE_ID Smart process entityTypeId is not a positive integer
400 MISSING_FIELD Required parameter userTypeId not passed on creation
400 INVALID_REQUEST Request body is not an object
403 BITRIX_ACCESS_DENIED The Bitrix24 OAuth application lacks permissions for userfieldconfig.* on smart processes
404 ENTITY_NOT_FOUND Field with the specified id does not exist
404 SMART_PROCESS_NOT_FOUND Smart process with the specified entityTypeId not found on the portal
422 BITRIX_ERROR Bitrix24 rejected the request — invalid value, illegal field name, unknown userTypeId

#System errors

HTTP Code Description
401 MISSING_API_KEY Missing X-Api-Key header
401 TOKEN_MISSING API key has no configured tokens
403 SCOPE_DENIED API key lacks the crm scope
502 BITRIX_UNAVAILABLE Bitrix24 portal is unavailable

Full list of common API errors — Errors.

#See also