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 of the "employee" entity, including the Bitrix24 account's user (UF_*) fields.

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

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
personalCity PERSONAL_CITY string City
personalPhoto PERSONAL_PHOTO string Photo URL
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. Populated only on GET /v1/users/me (true/false/null); unavailable on GET /v1/users/:id and the list
isOnline IS_ONLINE boolean yes The employee is currently online
dateRegister DATE_REGISTER datetime yes Bitrix24 account registration date
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" — intranet employee, "extranet" — external user
timestampX TIMESTAMP_X datetime yes Marker of the record's last change in Bitrix24. For some users it is returned as an empty object {}

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

Response example

JSON 
{
  "success": true,
  "data": {
    "fields": {
      "id": { "type": "number", "readonly": true },
      "name": { "type": "string", "readonly": false },
      "lastName": { "type": "string", "readonly": false },
      "email": { "type": "string", "readonly": false },
      "active": { "type": "boolean", "readonly": false },
      "workPosition": { "type": "string", "readonly": false },
      "departmentId": { "type": "array", "readonly": false },
      "personalPhone": { "type": "string", "readonly": false },
      "isAdmin": { "type": "boolean", "readonly": true },
      "lastLogin": { "type": "datetime", "readonly": true },
      "timeZone": { "type": "string", "readonly": false },
      "userType": { "type": "string", "readonly": true },
      "UF_DEPARTMENT": { "type": "string", "readonly": false, "label": "UF_DEPARTMENT" },
      "UF_PHONE_INNER": { "type": "string", "readonly": false, "label": "UF_PHONE_INNER" },
      "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"]
  }
}

A few fields from the full list are shown. The real response contains 30+ schema fields in camelCase, non-mapped Bitrix24 fields in UPPER_SNAKE_CASE (WORK_*, some PERSONAL_*), and UF fields of the specific Bitrix24 account.

Error response example

403 — no scope:

JSON 
{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "This endpoint requires 'user' scope"
  }
}

Errors

HTTP Code Description
401 TOKEN_MISSING The API key has no configured tokens
403 SCOPE_DENIED The API key lacks the user scope

Full list of common API errors — Errors.

See also