## Create employee field

`POST /v1/userfields/users`

Creates a new employee user field. Field properties are passed flat at the JSON root — without a `fields` wrapper.

## Request fields (body)

| Field | Type | Required | Description |
|------|-----|:-----:|---------|
| `userTypeId` | string | yes | Field type. Allowed values — [Field types](/docs/userfields/users#field-types). Examples: `string`, `enumeration`, `integer`, `double`, `datetime` |
| `fieldName` | string | yes | System name of the field. Stored in upper case with the `UF_USR_` prefix: pass `UF_USR_BADGE_NO` or `badge_no` — in both cases the field gets the name `UF_USR_BADGE_NO`. Under this name the field appears in the employee schema [`GET /v1/users/fields`](/docs/entities/users/fields) and is accepted in employee requests |
| `label` | string | no | 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 | no | Label in the edit form per Bitrix24 account language. Example: `{ "ru": "Badge number", "en": "Badge number" }`. This is the label that arrives in the employee schema as `label` |
| `sort` | string | no | Sort order in the Bitrix24 interface. Defaults to `"100"` |
| `multiple` | boolean | no | Allow multiple values: `true` / `false` or `"Y"` / `"N"`. Off by default. Set only on creation — an update does not change it |
| `showFilter` | boolean | no | Show in the filter: `true` or `"Y"` — yes, `false` or `"N"` — no. Off by default. An enabled filter reads back as `"E"` |
| `xmlId` | string | no | External identifier for integrations |
| `settings` | object | no | Field settings specific to `userTypeId`. For `string` — `SIZE`, `ROWS`, `REGEXP`, `MIN_LENGTH`, `MAX_LENGTH`, `DEFAULT_VALUE`. For `double` — `PRECISION`, the number of decimal places. Settings for other types — [Get field](/docs/userfields/users/get) |
| `list` | array | no | Options for an `enumeration` field. Each item: `{ "VALUE": "Name", "SORT": 10 }`. Ignored for other types |
| `mandatory`, `isSearchable`, `showInList`, `editInList` | boolean | no | Accepted, but not applied to an employee field: the field always reads back with `mandatory: "N"`, `isSearchable: "N"`, `showInList: "Y"`, `editInList: "Y"` — [Which properties are applied](/docs/userfields/users#which-properties-are-applied) |

## Examples

### curl — personal key

```bash
curl -X POST "https://vibecode.bitrix24.com/v1/userfields/users" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userTypeId": "enumeration",
    "fieldName": "UF_USR_SHIFT",
    "label": "Shift",
    "sort": "200",
    "showFilter": true,
    "list": [
      { "VALUE": "Morning", "SORT": 10 },
      { "VALUE": "Evening", "SORT": 20 },
      { "VALUE": "Night", "SORT": 30 }
    ]
  }'
```

### curl — OAuth application

```bash
curl -X POST "https://vibecode.bitrix24.com/v1/userfields/users" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "userTypeId": "enumeration",
    "fieldName": "UF_USR_SHIFT",
    "label": "Shift",
    "sort": "200",
    "showFilter": true,
    "list": [
      { "VALUE": "Morning", "SORT": 10 },
      { "VALUE": "Evening", "SORT": 20 },
      { "VALUE": "Night", "SORT": 30 }
    ]
  }'
```

### JavaScript — personal key

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/userfields/users', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    userTypeId: 'enumeration',
    fieldName: 'UF_USR_SHIFT',
    label: 'Shift',
    sort: '200',
    showFilter: true,
    list: [
      { VALUE: 'Morning', SORT: 10 },
      { VALUE: 'Evening', SORT: 20 },
      { VALUE: 'Night', SORT: 30 },
    ],
  }),
})

const { success, data } = await res.json()
console.log('Created field with id:', data.id)
```

### JavaScript — OAuth application

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/userfields/users', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    userTypeId: 'enumeration',
    fieldName: 'UF_USR_SHIFT',
    label: 'Shift',
    sort: '200',
    showFilter: true,
    list: [
      { VALUE: 'Morning', SORT: 10 },
      { VALUE: 'Evening', SORT: 20 },
      { VALUE: 'Night', SORT: 30 },
    ],
  }),
})

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

## Response fields

| Field | Type | Description |
|------|-----|---------|
| `success` | boolean | Always `true` on success |
| `data.id` | number | Numeric identifier of the created field |

The HTTP response status is `201 Created`. Full description of the created field — [`GET /v1/userfields/users/:id`](/docs/userfields/users/get).

## Response example

```json
{
  "success": true,
  "data": {
    "id": 6007923
  }
}
```

## Error response example

400 — the required parameter `fieldName` is missing:

```json
{
  "success": false,
  "error": {
    "code": "MISSING_FIELD",
    "message": "fieldName is required. Employee custom fields use the UF_USR_ prefix, e.g. \"UF_USR_BADGE_NO\"."
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|---------|
| 400 | `MISSING_FIELD` | `userTypeId` is missing — the message lists example types |
| 400 | `MISSING_FIELD` | `fieldName` is missing — the message names the `UF_USR_` prefix |
| 400 | `INVALID_REQUEST` | The request body is not an object |
| 422 | `BITRIX_ERROR` | An unknown `userTypeId` was passed — the message is `The custom type is invalid.` The text arrives in the portal language |
| 422 | `BITRIX_ERROR` | A field with this name already exists — the message is `The field UF_USR_SHIFT for entity USER already exists.` The text arrives in the portal language |
| 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

**A new field is visible in the employee schema immediately.** After creation the field appears in [`GET /v1/users/fields`](/docs/entities/users/fields) without delay — under its `UF_USR_*` name, with its type and label, and for `enumeration` also with the `items` array of options. The field's value is written together with the employee card: [`PATCH /v1/users/:id`](/docs/entities/users/update).

## See also

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