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 custom employee field. Field properties are passed flat at the JSON root — without a fields wrapper.

Request fields (body)

Field Type Required Description
FielduserTypeId Typestring Requiredyes DescriptionField type. Allowed values — Field types. Examples: string, enumeration, integer, double, datetime
FieldfieldName Typestring Requiredyes DescriptionSystem 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
Fieldlabel Typestring Requiredno DescriptionField label. Substituted into editFormLabel, listColumnLabel and listFilterLabel when they are not passed explicitly. Responses in this section do not return labels — Field labels
FieldeditFormLabel Typeobject Requiredno DescriptionLabel in the edit form per Bitrix24 account language. Example: { "ru": "Badge number", "en": "Badge number" }. This label is returned in the employee schema as label
FieldeditFormLabel.<language code> Typestring Requiredno DescriptionLabel for one Bitrix24 account language. The key is the language code, for example ru or en
Fieldsort Typenumber | string Requiredno DescriptionSort order in the Bitrix24 interface. Accepted as a number or a string, read back as a string. Defaults to "100"
Fieldmultiple Typeboolean Requiredno DescriptionAllow multiple values: true / false or "Y" / "N". Off by default. Set only on creation — an update does not change it
FieldshowFilter Typeboolean Requiredno DescriptionShow in the filter: true or "Y" — yes, false or "N" — no. Off by default. An enabled filter reads back as "E"
FieldxmlId Typestring Requiredno DescriptionExternal identifier for integrations
Fieldsettings Typeobject Requiredno DescriptionField settings specific to userTypeId. For string and double, the keys in the rows below are saved. Settings for other types — Get employee field
Fieldsettings.ROWS Typenumber Requiredno DescriptionFor the string type: height of the input field in lines
Fieldsettings.DEFAULT_VALUE Typestring Requiredno DescriptionFor the string type: default value
Fieldsettings.PRECISION Typenumber Requiredno DescriptionFor the double type: number of decimal places
Fieldlist Typearray Requiredno DescriptionOptions for an enumeration field. Each item: { "VALUE": "Name", "SORT": 10 }. Ignored for other types
Fieldmandatory, isSearchable, showInList, editInList Typeboolean Requiredno DescriptionAccepted, 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
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typeobject DescriptionCreation result
Fielddata.id Typenumber DescriptionNumeric 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
HTTP400 CodeMISSING_FIELD DescriptionuserTypeId is missing — the message lists example types
HTTP400 CodeMISSING_FIELD DescriptionfieldName is missing — the message names the UF_USR_ prefix
HTTP400 CodeINVALID_REQUEST DescriptionThe request body is not an object
HTTP422 CodeBITRIX_ERROR DescriptionAn unknown userTypeId was passed — the message is The custom type is invalid. The text arrives in the portal language
HTTP422 CodeBITRIX_ERROR DescriptionA 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
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the user.userfield scope
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no configured tokens
HTTP401 CodeMISSING_API_KEY DescriptionThe 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