## Get employee field

`GET /v1/userfields/users/:id`

Returns the description of a single user field of an employee by its numeric identifier.

## Parameters

| Parameter | Type | Required | Description |
|----------|-----|:-----:|---------|
| `:id` (path) | number | yes | Numeric identifier of the field (from the response of [`GET /v1/userfields/users`](/docs/userfields/users/list) or [`POST /v1/userfields/users`](/docs/userfields/users/create)). Leading zeros are ignored — `007` reads as `7` |

## Examples

### curl — personal key

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

### curl — OAuth application

```bash
curl "https://vibecode.bitrix24.com/v1/userfields/users/6007923" \
  -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/userfields/users/6007923',
  {
    headers: { 'X-Api-Key': 'YOUR_API_KEY' },
  }
)
const { success, data } = await res.json()
console.log(data.fieldName, data.userTypeId)
```

### JavaScript — OAuth application

```javascript
const res = await fetch(
  'https://vibecode.bitrix24.com/v1/userfields/users/6007923',
  {
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
    },
  }
)
const { success, data } = await res.json()
```

## Response fields

| Field | Type | Description |
|------|-----|---------|
| `success` | boolean | Always `true` on success |
| `data` | object | Field object |
| `data.id` | number | Numeric identifier of the field |
| `data.entityId` | string | Internal entity identifier — always `USER` |
| `data.fieldName` | string | System field name in the `UF_USR_*` format. The field appears under the same name in the employee schema [`GET /v1/users/fields`](/docs/entities/users/fields) |
| `data.userTypeId` | string | Field type. Allowed values — [Field types](/docs/userfields/users#field-types) |
| `data.xmlId` | string\|null | External identifier for integrations. Set manually on creation or update |
| `data.sort` | string | Sort order in the Bitrix24 interface |
| `data.multiple` | string | Multiple field: `"Y"` or `"N"` |
| `data.mandatory` | string | Required field. Always `"N"` for employee fields — [Which properties are applied](/docs/userfields/users#which-properties-are-applied) |
| `data.showFilter` | string | Show in the filter. `"N"` — off; an enabled filter comes back as `"E"` — Bitrix24's storage form. An `"N"` or an `"E"` you read can be sent back as is |
| `data.showInList` | string | Show in the employee list. Always `"Y"` for employee fields |
| `data.editInList` | string | Allow editing from the list. Always `"Y"` for employee fields |
| `data.isSearchable` | string | Whether it participates in full-text search. Always `"N"` for employee fields |
| `data.settings` | object | Field settings specific to `userTypeId`. For `enumeration` — `DISPLAY`, `LIST_HEIGHT`, `CAPTION_NO_VALUE`, `SHOW_NO_VALUE`. Key sets for other types — in "Known specifics" |
| `data.list` | array | Options of an `enumeration` field. Absent for other types. Each item contains `ID`, `SORT`, `VALUE`, `DEF` and `XML_ID` — all values are strings; Bitrix24 generates `XML_ID` itself when it is not passed |

Field labels — `editFormLabel`, `listColumnLabel`, `listFilterLabel`, `errorMessage`, `helpMessage` — are absent from the response: only the employee schema [`GET /v1/users/fields`](/docs/entities/users/fields) returns them, in the `label` field.

## Response example

```json
{
  "success": true,
  "data": {
    "id": 6007923,
    "entityId": "USER",
    "fieldName": "UF_USR_SHIFT",
    "userTypeId": "enumeration",
    "xmlId": null,
    "sort": "200",
    "multiple": "N",
    "mandatory": "N",
    "showFilter": "E",
    "showInList": "Y",
    "editInList": "Y",
    "isSearchable": "N",
    "settings": {
      "DISPLAY": "LIST",
      "LIST_HEIGHT": 1,
      "CAPTION_NO_VALUE": "",
      "SHOW_NO_VALUE": "Y"
    },
    "list": [
      {
        "ID": "3967",
        "SORT": "10",
        "VALUE": "Morning",
        "DEF": "N",
        "XML_ID": "46e4bae66329c39fafcbaef4262d490b"
      },
      {
        "ID": "3969",
        "SORT": "20",
        "VALUE": "Evening",
        "DEF": "N",
        "XML_ID": "3351c3d103ce376358db5c39019af5c4"
      },
      {
        "ID": "3971",
        "SORT": "30",
        "VALUE": "Night",
        "DEF": "N",
        "XML_ID": "160aa32209dc24bfb699010bf2df174a"
      }
    ]
  }
}
```

## Error response example

404 — the field does not exist:

```json
{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "User field 999999999 not found"
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|---------|
| 400 | `INVALID_ID` | `:id` is not a positive integer — the request is rejected before the portal is contacted |
| 404 | `NOT_FOUND` | No field with this `id` |
| 403 | `SCOPE_DENIED` | The API key does not have the `user.userfield` scope |
| 401 | `MISSING_API_KEY` | The `X-Api-Key` header is missing |
| 401 | `TOKEN_MISSING` | The API key has no configured tokens |

Full list of common API errors — [Errors](/docs/errors).

## Known specifics

**The card is assembled from the list.** The response is the list item selected by `id`: the property set is the same as that of a [list](/docs/userfields/users/list) item; the card carries no additional data. So when you need several fields at once, one list request is cheaper than a card per field.

**The `settings` field.** The structure of the `settings` object depends on the `userTypeId` value. Key sets taken from live fields:

- `string` — `SIZE`, `ROWS`, `REGEXP`, `MIN_LENGTH`, `MAX_LENGTH`, `DEFAULT_VALUE`
- `integer` — `SIZE`, `MIN_VALUE`, `MAX_VALUE`, `DEFAULT_VALUE`
- `double` — `PRECISION`, `SIZE`, `MIN_VALUE`, `MAX_VALUE`, `DEFAULT_VALUE`
- `date` — `DEFAULT_VALUE` as an object `{ "TYPE": "NONE", "VALUE": "" }`
- `datetime` — `DEFAULT_VALUE` as the same object, `USE_SECOND`, `USE_TIMEZONE`
- `boolean` — `DEFAULT_VALUE`, `DISPLAY`, `LABEL`, `LABEL_CHECKBOX`
- `enumeration` — `DISPLAY`, `LIST_HEIGHT`, `CAPTION_NO_VALUE`, `SHOW_NO_VALUE`
- `file` — `SIZE`, `LIST_WIDTH`, `LIST_HEIGHT`, `MAX_SHOW_SIZE`, `MAX_ALLOWED_SIZE`, `EXTENSIONS`, `TARGET_BLANK`, `DEFAULT_VIEW`
- `employee` — `DEFAULT_VALUE` as an empty array
- `crm` — binding flags `LEAD`, `CONTACT`, `COMPANY`, `DEAL` with `"Y"` / `"N"` values

The type of the nested `DEFAULT_VALUE` key also depends on `userTypeId`: an empty string for `string` and `money`, `null` for `integer` and `double`, the number `0` for `boolean`, an object for `date` and `datetime`, an empty array for `employee`. Rely on the specific `userTypeId`, not on a single set.

## See also

- [List employee fields](/docs/userfields/users/list)
- [Create field](/docs/userfields/users/create)
- [Update field](/docs/userfields/users/update)
- [Employee fields](/docs/userfields/users)
- [User fields](/docs/userfields)