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

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

### curl — OAuth application

```bash
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 | Type | Description |
|------|-----|---------|
| `success` | boolean | Always `true` on success |
| `data` | object | The employee field schema and the operations available for employees. Its keys are in the rows below |
| `data.fields` | object | The employee field schema: field name → an object with `type`, `readonly` and `label`. Some fields also carry `description`, `nullable`, `enum` and `items`. The standard fields are listed below. The work-details fields and the `UF_*` user fields of this Bitrix24 account come in addition to them |
| `data.batch` | array | Employee write operations available in [batch calls](/docs/batch): `create`, `update` |
| `data.include` | array | The names the `include` parameter accepts: `department` |
| `data.relations` | object | Employee relations: `department` covers the departments from `departmentId`. See [List departments](/docs/entities/departments/list) |
| `data.aggregatable` | array | Standard fields allowed in the aggregation `groupBy`: `active`, `isAdmin`, `isOnline`, `departmentId`, `workPosition`, `personalGender`, `personalCity` |

### Standard employee fields

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

| 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 allowed values are returned 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`. For details and unsupported input formats, see the "Update 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`](/docs/entities/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 | Date the employee registered in 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 employee 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. The field does not arrive in the [`GET /v1/users/me`](/docs/entities/users/me) response |
| `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_*`) 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](/docs/userfields/users).

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

```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" }
        ]
      }
    },
    "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:

```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 |
| 429 | `RATE_LIMITED` | Rate limit exceeded: 300 requests per minute per portal. All API keys of the portal share one limit. The current limit is returned in the `x-ratelimit-limit` header. Retry after the delay in the `Retry-After` header |

For the full list of common API errors, see [Errors](/docs/errors).

## See also

- [Create employee](/docs/entities/users/create)
- [Update employee](/docs/entities/users/update)
- [List employees](/docs/entities/users/list)
- [User fields](/docs/userfields)
- [Limits and optimization](/docs/optimization)