[{"data":1,"prerenderedAt":7},["ShallowReactive",2],{"docs-userfields\u002Fusers\u002Fcreate":3,"docs-tabs-userfields\u002Fusers\u002Fcreate":6},{"content":4,"lastmod":5},"## Create employee field\n\n`POST \u002Fv1\u002Fuserfields\u002Fusers`\n\nCreates a new custom employee field. Field properties are passed flat at the JSON root — without a `fields` wrapper.\n\n## Request fields (body)\n\n| Field | Type | Required | Description |\n|------|-----|:-----:|---------|\n| `userTypeId` | string | yes | Field type. Allowed values — [Field types](\u002Fdocs\u002Fuserfields\u002Fusers#field-types). Examples: `string`, `enumeration`, `integer`, `double`, `datetime` |\n| `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 \u002Fv1\u002Fusers\u002Ffields`](\u002Fdocs\u002Fentities\u002Fusers\u002Ffields) and is accepted in employee requests |\n| `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](\u002Fdocs\u002Fuserfields\u002Fusers#field-labels) |\n| `editFormLabel` | object | no | Label in the edit form per Bitrix24 account language. Example: `{ \"ru\": \"Badge number\", \"en\": \"Badge number\" }`. This label is returned in the employee schema as `label` |\n| `editFormLabel.\u003Clanguage code>` | string | no | Label for one Bitrix24 account language. The key is the language code, for example `ru` or `en` |\n| `sort` | number \\| string | no | Sort order in the Bitrix24 interface. Accepted as a number or a string, read back as a string. Defaults to `\"100\"` |\n| `multiple` | boolean | no | Allow multiple values: `true` \u002F `false` or `\"Y\"` \u002F `\"N\"`. Off by default. Set only on creation — an update does not change it |\n| `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\"` |\n| `xmlId` | string | no | External identifier for integrations |\n| `settings` | object | no | Field settings specific to `userTypeId`. For `string` and `double`, the keys in the rows below are saved. Settings for other types — [Get employee field](\u002Fdocs\u002Fuserfields\u002Fusers\u002Fget) |\n| `settings.ROWS` | number | no | For the `string` type: height of the input field in lines |\n| `settings.DEFAULT_VALUE` | string | no | For the `string` type: default value |\n| `settings.PRECISION` | number | no | For the `double` type: number of decimal places |\n| `list` | array | no | Options for an `enumeration` field. Each item: `{ \"VALUE\": \"Name\", \"SORT\": 10 }`. Ignored for other types |\n| `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](\u002Fdocs\u002Fuserfields\u002Fusers#which-properties-are-applied) |\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fuserfields\u002Fusers\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"userTypeId\": \"enumeration\",\n    \"fieldName\": \"UF_USR_SHIFT\",\n    \"label\": \"Shift\",\n    \"sort\": \"200\",\n    \"showFilter\": true,\n    \"list\": [\n      { \"VALUE\": \"Morning\", \"SORT\": 10 },\n      { \"VALUE\": \"Evening\", \"SORT\": 20 },\n      { \"VALUE\": \"Night\", \"SORT\": 30 }\n    ]\n  }'\n```\n\n### curl — OAuth application\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fuserfields\u002Fusers\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"userTypeId\": \"enumeration\",\n    \"fieldName\": \"UF_USR_SHIFT\",\n    \"label\": \"Shift\",\n    \"sort\": \"200\",\n    \"showFilter\": true,\n    \"list\": [\n      { \"VALUE\": \"Morning\", \"SORT\": 10 },\n      { \"VALUE\": \"Evening\", \"SORT\": 20 },\n      { \"VALUE\": \"Night\", \"SORT\": 30 }\n    ]\n  }'\n```\n\n### JavaScript — personal key\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fuserfields\u002Fusers', {\n  method: 'POST',\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({\n    userTypeId: 'enumeration',\n    fieldName: 'UF_USR_SHIFT',\n    label: 'Shift',\n    sort: '200',\n    showFilter: true,\n    list: [\n      { VALUE: 'Morning', SORT: 10 },\n      { VALUE: 'Evening', SORT: 20 },\n      { VALUE: 'Night', SORT: 30 },\n    ],\n  }),\n})\n\nconst { success, data } = await res.json()\nconsole.log('Created field with id:', data.id)\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fuserfields\u002Fusers', {\n  method: 'POST',\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({\n    userTypeId: 'enumeration',\n    fieldName: 'UF_USR_SHIFT',\n    label: 'Shift',\n    sort: '200',\n    showFilter: true,\n    list: [\n      { VALUE: 'Morning', SORT: 10 },\n      { VALUE: 'Evening', SORT: 20 },\n      { VALUE: 'Night', SORT: 30 },\n    ],\n  }),\n})\n\nconst { success, data } = await res.json()\n```\n\n## Response fields\n\n| Field | Type | Description |\n|------|-----|---------|\n| `success` | boolean | Always `true` on success |\n| `data` | object | Creation result |\n| `data.id` | number | Numeric identifier of the created field |\n\nThe HTTP response status is `201 Created`. Full description of the created field — [`GET \u002Fv1\u002Fuserfields\u002Fusers\u002F:id`](\u002Fdocs\u002Fuserfields\u002Fusers\u002Fget).\n\n## Response example\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"id\": 6007923\n  }\n}\n```\n\n## Error response example\n\n400 — the required parameter `fieldName` is missing:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"MISSING_FIELD\",\n    \"message\": \"fieldName is required. Employee custom fields use the UF_USR_ prefix, e.g. \\\"UF_USR_BADGE_NO\\\".\"\n  }\n}\n```\n\n## Errors\n\n| HTTP | Code | Description |\n|------|-----|---------|\n| 400 | `MISSING_FIELD` | `userTypeId` is missing — the message lists example types |\n| 400 | `MISSING_FIELD` | `fieldName` is missing — the message names the `UF_USR_` prefix |\n| 400 | `INVALID_REQUEST` | The request body is not an object |\n| 422 | `BITRIX_ERROR` | An unknown `userTypeId` was passed — the message is `The custom type is invalid.` The text arrives in the portal language |\n| 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 |\n| 403 | `SCOPE_DENIED` | The API key does not have the `user.userfield` scope |\n| 401 | `TOKEN_MISSING` | The API key has no configured tokens |\n| 401 | `MISSING_API_KEY` | The `X-Api-Key` header is missing |\n\nFull list of common API errors — [Errors](\u002Fdocs\u002Ferrors).\n\n## Known specifics\n\n**A new field is visible in the employee schema immediately.** After creation the field appears in [`GET \u002Fv1\u002Fusers\u002Ffields`](\u002Fdocs\u002Fentities\u002Fusers\u002Ffields) 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 \u002Fv1\u002Fusers\u002F:id`](\u002Fdocs\u002Fentities\u002Fusers\u002Fupdate).\n\n## See also\n\n- [Get employee field](\u002Fdocs\u002Fuserfields\u002Fusers\u002Fget)\n- [Update employee field](\u002Fdocs\u002Fuserfields\u002Fusers\u002Fupdate)\n- [Delete employee field](\u002Fdocs\u002Fuserfields\u002Fusers\u002Fdelete)\n- [Employee fields](\u002Fdocs\u002Fuserfields\u002Fusers)\n- [User fields](\u002Fdocs\u002Fuserfields)\n","2026-10-16",{},1794739617801]