## Update employee field

`PATCH /v1/userfields/users/:id`

Updates the properties of an existing employee user field. The field type `userTypeId` and the `multiple` flag cannot be changed — to change the type, delete the field and create a new one. Pass only the properties you want to change.

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

## Request fields (body)

| Field | Type | Description |
|------|-----|---------|
| `label` | string | Field label. Substituted into `editFormLabel`, `listColumnLabel` and `listFilterLabel` when they are not passed explicitly. Responses in this section do not return labels — [Field labels](/docs/userfields/users#field-labels) |
| `editFormLabel` | object | Label in the edit form, keyed by Bitrix24 account language. Example: `{ "ru": "Badge number", "en": "Badge number" }`. This is the label returned in the employee schema as `label` |
| `sort` | string | Sort order in the Bitrix24 interface |
| `showFilter` | boolean | Show in the filter: `true` or `"Y"` — yes, `false` or `"N"` — no. The `"E"` you read can be sent back as is — the platform treats it as "on" |
| `xmlId` | string | External identifier for integrations |
| `settings` | object | Type-specific field settings. The structure depends on `userTypeId` — [Get field](/docs/userfields/users/get) |
| `list` | array | Options of an `enumeration` field. An item without `ID` is added as a new option; an item with `ID` and a new `VALUE` renames an existing one; an item `{ "ID": 3967, "DEL": "Y" }` deletes the option. Options not mentioned in the array remain unchanged |
| `mandatory`, `isSearchable`, `showInList`, `editInList`, `multiple` | boolean | Accepted, but not applied to an employee field on update — [Which properties are applied](/docs/userfields/users#which-properties-are-applied) |

Read-only properties — `id`, `entityId`, `fieldName`, `userTypeId` — are ignored when passed: the field identifier is taken only from the path.

## Examples

### curl — personal key

```bash
curl -X PATCH "https://vibecode.bitrix24.com/v1/userfields/users/6007923" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sort": "300",
    "list": [
      { "VALUE": "24-hour", "SORT": 40 }
    ]
  }'
```

### curl — OAuth application

```bash
curl -X PATCH "https://vibecode.bitrix24.com/v1/userfields/users/6007923" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sort": "300",
    "list": [
      { "VALUE": "24-hour", "SORT": 40 }
    ]
  }'
```

### JavaScript — personal key

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/userfields/users/6007923', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    sort: '300',
    list: [
      { VALUE: '24-hour', SORT: 40 },
    ],
  }),
})

const { success, data } = await res.json()
console.log('Updated:', data.updated)
```

### JavaScript — OAuth application

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/userfields/users/6007923', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    sort: '300',
    list: [
      { VALUE: '24-hour', SORT: 40 },
    ],
  }),
})

const { success, data } = await res.json()
```

## Response fields

| Field | Type | Description |
|------|-----|---------|
| `success` | boolean | Always `true` on success |
| `data.updated` | boolean | `true` on successful update |

## Response example

```json
{
  "success": true,
  "data": {
    "updated": true
  }
}
```

## Error response example

404 — there is no field with this `id`:

```json
{
  "success": false,
  "error": {
    "code": "ENTITY_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 |
| 400 | `INVALID_REQUEST` | The request body is not an object |
| 404 | `ENTITY_NOT_FOUND` | There is no field with this `id`. Existence is checked before the update, so no change reaches the portal |
| 422 | `BITRIX_ERROR` | The key owner is not a Bitrix24 account administrator — Bitrix24 responds with the message `Access denied.` |
| 422 | `BITRIX_ERROR` | Other Bitrix24 rejections — including a field removed between the existence check and the update itself. The text is returned verbatim in `error.message` |
| 403 | `SCOPE_DENIED` | The API key does not have the `user.userfield` scope |
| 401 | `TOKEN_MISSING` | The API key has no configured tokens |
| 401 | `MISSING_API_KEY` | The `X-Api-Key` header is missing |

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

## Known specifics

**The response does not confirm that properties were applied.** `updated: true` means that Bitrix24 accepted the request, not that every passed property changed: the properties the [Which properties are applied](/docs/userfields/users#which-properties-are-applied) table marks as not applied keep their previous values even when the response is successful. After an update, re-read the field — [`GET /v1/userfields/users/:id`](/docs/userfields/users/get).

**`enumeration` options are edited individually.** The `list` array does not replace the option set as a whole: options not mentioned in it are kept. The `ID`s of existing options are taken from the response of [`GET /v1/userfields/users/:id`](/docs/userfields/users/get). In the example above a fourth option — "24-hour" — is added to the field's three options.

## See also

- [Get field](/docs/userfields/users/get)
- [Create field](/docs/userfields/users/create)
- [Delete field](/docs/userfields/users/delete)
- [Employee fields](/docs/userfields/users)
- [User fields](/docs/userfields)