## Create an employee field (hr:admin)

`POST /api/hr/v1/fields`

Module: HR · operationId: `createField` · Tag: Configuration · Auth: access token (`Authorization: Bearer <accessToken>`)

### Request body

`application/json` (required)

- `key` (string, required): Stable key; the key in customFields
- `kind` (string, required): Kind of value; `phone` takes digits, spaces and `+ ( ) / . -` (at least 3 digits, `+` only first, at most 40 characters), `email` the shape `local@domain.tld` (one of `text`, `longtext`, `number`, `date`, `datetime`, `bool`, `select`, `multiselect`, `url`, `phone`, `email`)
- `label` (string, required): Display name
- `archived` (boolean): Archived: no longer offered for new data, kept for existing data
- `description` (string): Help text of the field
- `id` (string): Id of the field
- `options` (array of object): Choices of select and multiselect fields
  - `color` (string): Colour of the choice
  - `label` (string): Display text of the choice
  - `value` (string): Stored value of the choice
- `required` (boolean): A value is required
- `restricted` (boolean): Values are visible only to callers with hr:write
- `section` (string): Group in forms; defaults to other (one of `person`, `contact`, `employment`, `working_time`, `confidential`, `other`)
- `sortOrder` (integer): Position within the section
- `standard` (boolean, read-only): From the built-in catalogue; switched on and off with archived, key and kind are fixed
- `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)
- `visibleToColleagues` (boolean): Values are shown to every colleague in the directory (listColleagues); not together with restricted (400)

Example:

```json
{
  "archived": false,
  "description": "Herstellerzertifikate, z. B. MS-102 oder CCNA",
  "id": "2c4e6a8c-0e2a-4c4e-8a6c-0e2a4c6e8a10",
  "key": "zertifizierungen",
  "kind": "multiselect",
  "label": "Zertifizierungen",
  "options": [
    {
      "color": "info",
      "label": "MS-102",
      "value": "ms_102"
    },
    {
      "color": "info",
      "label": "MD-102",
      "value": "md_102"
    },
    {
      "color": "success",
      "label": "CCNA",
      "value": "ccna"
    }
  ],
  "required": false,
  "restricted": false,
  "section": "employment",
  "sortOrder": 70,
  "standard": false,
  "version": 1,
  "visibleToColleagues": true
}
```

### Responses

- **201** Created (`application/json`)
- **400** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 201 answer:

- `key` (string, required): Stable key; the key in customFields
- `kind` (string, required): Kind of value; `phone` takes digits, spaces and `+ ( ) / . -` (at least 3 digits, `+` only first, at most 40 characters), `email` the shape `local@domain.tld` (one of `text`, `longtext`, `number`, `date`, `datetime`, `bool`, `select`, `multiselect`, `url`, `phone`, `email`)
- `label` (string, required): Display name
- `archived` (boolean): Archived: no longer offered for new data, kept for existing data
- `description` (string): Help text of the field
- `id` (string): Id of the field
- `options` (array of object): Choices of select and multiselect fields
  - `color` (string): Colour of the choice
  - `label` (string): Display text of the choice
  - `value` (string): Stored value of the choice
- `required` (boolean): A value is required
- `restricted` (boolean): Values are visible only to callers with hr:write
- `section` (string): Group in forms; defaults to other (one of `person`, `contact`, `employment`, `working_time`, `confidential`, `other`)
- `sortOrder` (integer): Position within the section
- `standard` (boolean, read-only): From the built-in catalogue; switched on and off with archived, key and kind are fixed
- `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)
- `visibleToColleagues` (boolean): Values are shown to every colleague in the directory (listColleagues); not together with restricted (400)

Example 201 answer:

```json
{
  "archived": false,
  "description": "Herstellerzertifikate, z. B. MS-102 oder CCNA",
  "id": "2c4e6a8c-0e2a-4c4e-8a6c-0e2a4c6e8a10",
  "key": "zertifizierungen",
  "kind": "multiselect",
  "label": "Zertifizierungen",
  "options": [
    {
      "color": "info",
      "label": "MS-102",
      "value": "ms_102"
    },
    {
      "color": "info",
      "label": "MD-102",
      "value": "md_102"
    },
    {
      "color": "success",
      "label": "CCNA",
      "value": "ccna"
    }
  ],
  "required": false,
  "restricted": false,
  "section": "employment",
  "sortOrder": 70,
  "standard": false,
  "version": 1,
  "visibleToColleagues": true
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/hr/v1/fields' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"archived":false,"description":"Herstellerzertifikate, z. B. MS-102 oder CCNA","id":"2c4e6a8c-0e2a-4c4e-8a6c-0e2a4c6e8a10","key":"zertifizierungen","kind":"multiselect","label":"Zertifizierungen","options":[{"color":"info","label":"MS-102","value":"ms_102"},{"color":"info","label":"MD-102","value":"md_102"},{"color":"success","label":"CCNA","value":"ccna"}],"required":false,"restricted":false,"section":"employment","sortOrder":70,"standard":false,"version":1,"visibleToColleagues":true}'
```
