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 also 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

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

curl — OAuth application

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

JavaScript — personal key

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

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.

Standard employee fields

Each row is a key of the data.fields object.

Work-details fields (WORK_*, some PERSONAL_*) are returned 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 may be 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. For information on creating and editing employee fields, see Employee fields.

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.

The response elements of departmentId are numbers (number[]): OpenAPI describes them as number, while this endpoint and fieldsDetailed in /v1/guide publish readItemSchema: { "type": "number" }. This describes responses only: UserInput.departmentId retains its previous string[] schema, and accepted values and their order do not change.

Response example

{
  "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" }
        ]
      }
    },
    "relations": {
      "department": { "type": "many", "entity": "departments", "operations": [] }
    },
    "include": ["department"],
    "aggregatable": ["active", "isAdmin", "isOnline", "departmentId", "workPosition", "personalGender", "personalCity"],
    "batch": ["create", "update"]
  }
}

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:

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

Errors

For the full list of common API errors, see Errors.

See also

• Create employee
• Update employee
• List employees
• User fields
• Limits and optimization