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

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

| 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](/docs/errors).

## See also

- [Create employee](/docs/entities/users/create) — which fields can be passed
- [Update employee](/docs/entities/users/update) — which fields can be changed
- [List employees](/docs/entities/users/list) — filtering and search
- [User fields](/docs/userfields) — managing UF fields
- [Limits and optimization](/docs/optimization)