# User fields

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

**Scope:** `crm`, `userfieldconfig`, `user.userfield` | **Base URL:** `https://vibecode.bitrix24.com/v1` | **Authorization:** `X-Api-Key`

[Quick start](#quick-start) | [Full example](#full-example) | [Endpoint reference](#endpoint-reference) | [Error codes](#error-codes)

## Documentation sections

- [Module field types](/docs/userfields/types) — `GET /v1/userfields/types?moduleId=crm`
- [CRM entity fields](/docs/userfields/crm) — manage fields of deals, leads, contacts, companies, quotes and requisites
- [Smart process fields](/docs/userfields/smart-processes) — manage fields of smart process items by `entityTypeId`
- [Employee fields](/docs/userfields/users) — manage employee fields, scope `user.userfield`

## Field values in records

The endpoints in this section manage the field itself — its type, label and settings. The value of a field in a particular record is read and written together with the record: `POST /v1/deals`, `PATCH /v1/deals/:id`, `GET /v1/deals/:id`.

The name under which the field is accepted in those requests differs from the `fieldName` value returned by the endpoints in this section. A field created on deals as `fieldName: "PROJECT_CODE"` is listed among the definitions as `UF_CRM_PROJECT_CODE`, while the deal schema uses `ufCrmProjectCode`. The working name always comes from `GET /v1/{entity}/fields`. The value format for each type, multiple fields and clearing — [User fields (UF)](/docs/entity-api#user-fields-uf).

---

## Quick start

### 1. View existing deal fields

```bash
curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://vibecode.bitrix24.com/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": { "en": "Project code" }
    }
  ],
  "meta": { "total": 44 }
}
```

### 2. Create a new field

```bash
curl -X POST "https://vibecode.bitrix24.com/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, HTTP `201 Created` is returned 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.com/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 an 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](/docs/userfields/crm/list) | crm.:entity.userfield.list | List entity fields |
| GET | [/v1/userfields/:entity/types](/docs/userfields/crm/types) | crm.userfield.types | Field type catalog |
| GET | [/v1/userfields/:entity/:id](/docs/userfields/crm/get) | crm.:entity.userfield.get | Single field by identifier |
| POST | [/v1/userfields/:entity](/docs/userfields/crm/create) | crm.:entity.userfield.add | Create field |
| PATCH | [/v1/userfields/:entity/:id](/docs/userfields/crm/update) | crm.:entity.userfield.update | Update field |
| DELETE | [/v1/userfields/:entity/:id](/docs/userfields/crm/delete) | 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](/docs/userfields/smart-processes/list) | userfieldconfig.list | List smart process fields |
| GET | [/v1/items/:entityTypeId/userfields/types](/docs/userfields/smart-processes/types) | crm.userfield.types | Field type catalog |
| GET | [/v1/items/:entityTypeId/userfields/:id](/docs/userfields/smart-processes/get) | userfieldconfig.get | Single field by identifier |
| POST | [/v1/items/:entityTypeId/userfields](/docs/userfields/smart-processes/create) | userfieldconfig.add | Create field |
| PATCH | [/v1/items/:entityTypeId/userfields/:id](/docs/userfields/smart-processes/update) | userfieldconfig.update | Update field |
| DELETE | [/v1/items/:entityTypeId/userfields/:id](/docs/userfields/smart-processes/delete) | userfieldconfig.delete | Delete field |

`entityTypeId` — the smart process type identifier from the [`GET /v1/smart-processes`](/docs/entities/smart-processes) response.

### Employee fields

| Method | Path | Bitrix24 method | Description |
|-------|------|----------------|---------|
| GET | [/v1/userfields/users](/docs/userfields/users/list) | user.userfield.list | List employee fields |
| GET | [/v1/userfields/users/:id](/docs/userfields/users/get) | user.userfield.list | Single field by identifier |
| POST | [/v1/userfields/users](/docs/userfields/users/create) | user.userfield.add | Create field |
| PATCH | [/v1/userfields/users/:id](/docs/userfields/users/update) | user.userfield.update | Update field |
| DELETE | [/v1/userfields/users/:id](/docs/userfields/users/delete) | user.userfield.delete | Delete field |

Employee fields have no type catalog: `GET /v1/userfields/users/types` answers `400 UNSUPPORTED_ACTION`; the type is passed explicitly on creation — [Employee fields](/docs/userfields/users).

---

## 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 |
| 400 | `INVALID_ID` | The employee field `id` in the path is not a positive integer |
| 400 | `UNSUPPORTED_ACTION` | The employee field type catalog was requested — this entity has none |
| 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 — including when updating or deleting an employee field |
| 404 | `NOT_FOUND` | `GET /v1/userfields/users/:id` only — employee 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`. For employee fields, a permission refusal is returned the same way when the key owner is not a Bitrix24 account administrator |

### 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 — for employee fields, the `user.userfield` scope |
| 502 | `BITRIX_UNAVAILABLE` | The Bitrix24 portal is unavailable |

Full list of common API errors — [Errors](/docs/errors).

---

## See also

- [CRM entity fields](/docs/userfields/crm)
- [Smart process fields](/docs/userfields/smart-processes)
- [Employee fields](/docs/userfields/users)
- [API overview](/docs/entity-api)
- [Smart processes](/docs/entities/smart-processes)
- [Deals](/docs/entities/deals)
- [Requisites](/docs/entities/requisites)
- [Employees](/docs/entities/users)
- [Errors](/docs/errors)