For AI agents: markdown of this page — /docs-content-en/userfields/users/create.md documentation index — /llms.txt

Create employee field

POST /v1/userfields/users

Creates a new employee user field. Field properties are passed flat at the JSON root — without a fields wrapper.

Request fields (body)

Field Type Required Description
userTypeId string yes Field type. Allowed values — Field types. Examples: string, enumeration, integer, double, datetime
fieldName string yes System name of the field. Stored in upper case with the UF_USR_ prefix: pass UF_USR_BADGE_NO or badge_no — in both cases the field gets the name UF_USR_BADGE_NO. Under this name the field appears in the employee schema GET /v1/users/fields and is accepted in employee requests
label string no Field label. Substituted into editFormLabel, listColumnLabel and listFilterLabel when they are not passed explicitly. Responses in this section do not return labels — Field labels
editFormLabel object no Label in the edit form per Bitrix24 account language. Example: { "ru": "Badge number", "en": "Badge number" }. This is the label that arrives in the employee schema as label
sort string no Sort order in the Bitrix24 interface. Defaults to "100"
multiple boolean no Allow multiple values: true / false or "Y" / "N". Off by default. Set only on creation — an update does not change it
showFilter boolean no Show in the filter: true or "Y" — yes, false or "N" — no. Off by default. An enabled filter reads back as "E"
xmlId string no External identifier for integrations
settings object no Field settings specific to userTypeId. For string — SIZE, ROWS, REGEXP, MIN_LENGTH, MAX_LENGTH, DEFAULT_VALUE. For double — PRECISION, the number of decimal places. Settings for other types — Get field
list array no Options for an enumeration field. Each item: { "VALUE": "Name", "SORT": 10 }. Ignored for other types
mandatory, isSearchable, showInList, editInList boolean no Accepted, but not applied to an employee field: the field always reads back with mandatory: "N", isSearchable: "N", showInList: "Y", editInList: "Y" — Which properties are applied

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/userfields/users" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userTypeId": "enumeration",
    "fieldName": "UF_USR_SHIFT",
    "label": "Shift",
    "sort": "200",
    "showFilter": true,
    "list": [
      { "VALUE": "Morning", "SORT": 10 },
      { "VALUE": "Evening", "SORT": 20 },
      { "VALUE": "Night", "SORT": 30 }
    ]
  }'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/userfields/users" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "userTypeId": "enumeration",
    "fieldName": "UF_USR_SHIFT",
    "label": "Shift",
    "sort": "200",
    "showFilter": true,
    "list": [
      { "VALUE": "Morning", "SORT": 10 },
      { "VALUE": "Evening", "SORT": 20 },
      { "VALUE": "Night", "SORT": 30 }
    ]
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/userfields/users', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    userTypeId: 'enumeration',
    fieldName: 'UF_USR_SHIFT',
    label: 'Shift',
    sort: '200',
    showFilter: true,
    list: [
      { VALUE: 'Morning', SORT: 10 },
      { VALUE: 'Evening', SORT: 20 },
      { VALUE: 'Night', SORT: 30 },
    ],
  }),
})

const { success, data } = await res.json()
console.log('Created field with id:', data.id)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/userfields/users', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    userTypeId: 'enumeration',
    fieldName: 'UF_USR_SHIFT',
    label: 'Shift',
    sort: '200',
    showFilter: true,
    list: [
      { VALUE: 'Morning', SORT: 10 },
      { VALUE: 'Evening', SORT: 20 },
      { VALUE: 'Night', SORT: 30 },
    ],
  }),
})

const { success, data } = await res.json()

Response fields

Field Type Description
success boolean Always true on success
data.id number Numeric identifier of the created field

The HTTP response status is 201 Created. Full description of the created field — GET /v1/userfields/users/:id.

Response example

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

Error response example

400 — the required parameter fieldName is missing:

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_FIELD",
    "message": "fieldName is required. Employee custom fields use the UF_USR_ prefix, e.g. \"UF_USR_BADGE_NO\"."
  }
}

Errors

HTTP Code Description
400 MISSING_FIELD userTypeId is missing — the message lists example types
400 MISSING_FIELD fieldName is missing — the message names the UF_USR_ prefix
400 INVALID_REQUEST The request body is not an object
422 BITRIX_ERROR An unknown userTypeId was passed — the message is The custom type is invalid. The text arrives in the portal language
422 BITRIX_ERROR A field with this name already exists — the message is The field UF_USR_SHIFT for entity USER already exists. The text arrives in the portal language
403 SCOPE_DENIED The API key does not have the user.userfield scope
401 TOKEN_MISSING The API key has no configured tokens
401 MISSING_API_KEY The X-Api-Key header is missing

Full list of common API errors — Errors.

Known specifics

A new field is visible in the employee schema immediately. After creation the field appears in GET /v1/users/fields without delay — under its UF_USR_* name, with its type and label, and for enumeration also with the items array of options. The field's value is written together with the employee card: PATCH /v1/users/:id.

See also