# 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 Bitrix24 account — keep this in mind when working on production data.

**Scope:** `crm`, `userfieldconfig` | **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

- [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`

---

## 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, 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.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 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.

---

## 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` | 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)
- [Smart processes](/docs/entities/smart-processes)
- [Deals](/docs/entities/deals)
- [Requisites](/docs/entities/requisites)
- [Errors](/docs/errors)