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

Employee fields

GET /v1/users/fields

Returns the full list of fields for the "employee" entity, including the Bitrix24 account's user (UF_*) fields.

Every field is described by the type and readonly keys. Schema fields additionally carry a label and a description, and gender (personalGender) and account type (userType) carry an enum of allowed values, each value with its own label. Gender additionally carries nullable: true: when the employee has not filled it in, the response returns null — the OpenAPI schema says the same, declaring the field type as ["string", "null"].

Examples

curl — personal key

Terminal

curl "https://vibecode.bitrix24.com/v1/users/fields" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal

curl "https://vibecode.bitrix24.com/v1/users/fields" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

javascript

const res = await fetch('https://vibecode.bitrix24.com/v1/users/fields', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data } = await res.json()
console.log('Fields:', Object.keys(data.fields).length)

JavaScript — OAuth application

javascript

const res = await fetch('https://vibecode.bitrix24.com/v1/users/fields', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

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

Response fields

The label and description field captions are returned in English, while the ones the platform takes straight from the Bitrix24 account come in the account language. Request headers do not switch the language.

Field	Bitrix24	Type	RO	Description
`id`	`ID`	number	yes	Employee identifier
`name`	`NAME`	string		First name
`lastName`	`LAST_NAME`	string		Last name
`secondName`	`SECOND_NAME`	string		Middle name
`email`	`EMAIL`	string		Email — required on creation, must be unique
`active`	`ACTIVE`	boolean		Activity flag (`true` — active, `false` — deactivated)
`workPosition`	`WORK_POSITION`	string		Position
`workPhone`	`WORK_PHONE`	string		Work phone
`personalPhone`	`PERSONAL_PHONE`	string		Personal phone
`personalMobile`	`PERSONAL_MOBILE`	string		Mobile phone
`personalBirthday`	`PERSONAL_BIRTHDAY`	string		Date of birth (ISO 8601 format)
`personalGender`	`PERSONAL_GENDER`	string		Gender: `M` — male, `F` — female. The list of values arrives in `enum`. When the employee has not filled it in — `null`
`personalCity`	`PERSONAL_CITY`	string		City
`personalPhoto`	`PERSONAL_PHOTO`	string		On READ — the photo URL. On WRITE — the file itself: an array `[file name, base64]` on `POST /v1/users` and `PATCH /v1/users/:id`. Details and the refused shapes are on the «Update an employee» page
`departmentId`	`UF_DEPARTMENT`	number[]		Array of department IDs. List: `GET /v1/departments`
`xmlId`	`XML_ID`	string		External identifier for integrations
`isAdmin`	`IS_ADMIN`	boolean	yes	Bitrix24 account administrator flag, tri-state: `true`, `false` or `null`. Populated only on `GET /v1/users/me`, unavailable on `GET /v1/users/:id` and the list
`isOnline`	`IS_ONLINE`	boolean	yes	The employee is currently online
`dateRegister`	`DATE_REGISTER`	datetime	yes	Registration date on the Bitrix24 account
`lastLogin`	`LAST_LOGIN`	datetime	yes	Last login date
`lastActivityDate`	`LAST_ACTIVITY_DATE`	datetime	yes	Last activity date
`timeZone`	`TIME_ZONE`	string		The employee's time zone. Example: `"UTC"`
`title`	`TITLE`	string		Salutation / title
`personalWww`	`PERSONAL_WWW`	string		Personal website
`personalProfession`	`PERSONAL_PROFESSION`	string		Profession
`personalIcq`	`PERSONAL_ICQ`	string		ICQ (legacy Bitrix24 field)
`personalFax`	`PERSONAL_FAX`	string		Fax
`personalPager`	`PERSONAL_PAGER`	string		Pager
`personalStreet`	`PERSONAL_STREET`	string		Street
`userType`	`USER_TYPE`	string	yes	Account type: `"employee"` — staff member, `"extranet"` — external. The list of values arrives in `enum`. The list hides mail users, chatbots, Open Channel users and Replica records, so a response carries `employee` or `extranet`. The value `"email"` (mail user) is a filter value only — Bitrix24 documents it among the accepted values of the `USER_TYPE` filter, but it does not appear in a response, because the method excludes such users
`timestampX`	`TIMESTAMP_X`	datetime	yes	Timestamp of the record's last change in Bitrix24. For some users it is returned as an empty object `{}`

Work-details fields (WORK_*, some PERSONAL_*) arrive under their original Bitrix24 names in UPPER_SNAKE_CASE — Bitrix24 supplies their labels itself, localized to the language of the Bitrix24 account. Ten of them have no label in Bitrix24 at all (WORK_FAX, WORK_PAGER, WORK_STREET, WORK_MAILBOX, WORK_STATE, WORK_ZIP, WORK_COUNTRY, WORK_PROFILE, WORK_LOGO, WORK_NOTES) — the field name used to arrive in place of a label, and Vibecode now supplies the label and the description. When the Bitrix24 account does label such a field itself, its own label is kept unchanged. An empty work-details field is usually absent from a read response entirely — check for the presence of the key, not for an empty string.

User fields (UF_*) are also returned in responses and accepted on creation or update. In the response, a user field of the "list" type (enumeration) carries an items array of possible values (ID, VALUE, DEF, XML_ID) — provided the key has the user.userfield scope; without it the field is returned with its label but no items.

The field ufDepartment does not exist — the employee's department lives in departmentId, an array of department identifiers. The original Bitrix24 name UF_DEPARTMENT is accepted in select as an alias and projects the canonical departmentId. An unknown name in select is not rejected — the response is extended with an UNKNOWN_SELECT_FIELD warning in meta.warnings.

Response example

JSON

{
  "success": true,
  "data": {
    "fields": {
      "name": {
        "type": "string",
        "readonly": false,
        "label": "First name",
        "description": "Employee's first name."
      },
      "timestampX": {
        "type": "datetime",
        "readonly": true,
        "label": "Modified date",
        "description": "Timestamp of the last modification to the employee record in Bitrix24."
      },
      "personalGender": {
        "type": "string",
        "readonly": false,
        "nullable": true,
        "label": "Gender",
        "description": "Employee's gender. Comes back as null when the employee has not filled it in.",
        "enum": [
          { "value": "M", "label": "Male" },
          { "value": "F", "label": "Female" }
        ]
      },
      "WORK_CITY": { "type": "string", "readonly": false, "label": "Work city" },
      "WORK_FAX": {
        "type": "string",
        "readonly": false,
        "label": "Company fax",
        "description": "Fax number of the company in the employee's work details."
      },
      "UF_USR_STATUS": {
        "type": "enumeration",
        "readonly": false,
        "label": "Status",
        "items": [
          { "ID": "1", "VALUE": "New", "DEF": "N", "XML_ID": "x1" },
          { "ID": "2", "VALUE": "In progress", "DEF": "Y", "XML_ID": "x2" }
        ]
      }
    },
    "batch": ["create", "update", "delete"]
  }
}

One field of each kind is shown. The actual response contains 30+ schema fields in camelCase (each with a label and a description), Bitrix24 work-details fields in UPPER_SNAKE_CASE (WORK_*, some PERSONAL_*), and UF fields of the specific Bitrix24 account. The original Bitrix24 name of a schema field is not duplicated in the response: UF_DEPARTMENT arrives as departmentId, NAME as name.

Error response example

403 — no scope: