## Create a tenant-defined field (tenant:settings:write)

`POST /api/masterdata/field-defs`

Module: Master data · operationId: `createFieldDef` · Tag: Settings · Auth: access token (`Authorization: Bearer <accessToken>`)

A key that exists for the entity answers `409`.

### Request body

`application/json` (required)

- `entity` (string, required): Immutable (one of `ADDRESS`, `CONTACT`, `POSTAL`)
- `key` (string, required): Immutable; values are stored under this key and filtered with `cf.<key>`
- `kind` (string, required): Immutable (one of `text`, `longtext`, `number`, `date`, `datetime`, `bool`, `select`, `multiselect`, `url`)
- `label` (string, required): Label shown in forms (max length 128)
- `archived` (boolean): Hidden; values are kept, writes refused
- `createdAt` (string (date-time), read-only): Creation time
- `description` (string): Help text (max length 1000)
- `id` (string (uuid), read-only): Id of the field definition
- `options` (array of FieldOption): Unique non-empty values (select and multiselect)
  - `value` (string, required): Stored value
  - `color` (string): Display colour
  - `label` (string): Defaults to `value`
- `required` (boolean): A value is required on write
- `sortOrder` (integer): Position in forms
- `updatedAt` (string (date-time), read-only): Time of the last change
- `version` (integer): Optimistic locking version (updates)

Example:

```json
{
  "entity": "ADDRESS",
  "key": "branche",
  "kind": "select",
  "label": "Branche",
  "options": [
    {
      "label": "IT",
      "value": "it"
    },
    {
      "label": "Handel",
      "value": "handel"
    }
  ],
  "required": false,
  "sortOrder": 10
}
```

### Responses

- **201** Created (`application/json`)
- **400** Malformed body or query parameter (`application/json`)
- **401** Missing, invalid or expired token (empty body)
- **403** The token lacks the permission or carries no tenant (`application/json`)
- **409** Stale version or conflict with existing data (`application/json`)

Fields of the 201 answer:

- `entity` (string, required): Immutable (one of `ADDRESS`, `CONTACT`, `POSTAL`)
- `key` (string, required): Immutable; values are stored under this key and filtered with `cf.<key>`
- `kind` (string, required): Immutable (one of `text`, `longtext`, `number`, `date`, `datetime`, `bool`, `select`, `multiselect`, `url`)
- `label` (string, required): Label shown in forms (max length 128)
- `archived` (boolean): Hidden; values are kept, writes refused
- `createdAt` (string (date-time), read-only): Creation time
- `description` (string): Help text (max length 1000)
- `id` (string (uuid), read-only): Id of the field definition
- `options` (array of FieldOption): Unique non-empty values (select and multiselect)
  - `value` (string, required): Stored value
  - `color` (string): Display colour
  - `label` (string): Defaults to `value`
- `required` (boolean): A value is required on write
- `sortOrder` (integer): Position in forms
- `updatedAt` (string (date-time), read-only): Time of the last change
- `version` (integer): Optimistic locking version (updates)

Example 201 answer:

```json
{
  "archived": false,
  "createdAt": "2026-01-02T08:00:00Z",
  "entity": "ADDRESS",
  "id": "0a2c4e6a-8b0d-4f2a-9c4e-6a8b0d2f4a6c",
  "key": "branche",
  "kind": "select",
  "label": "Branche",
  "options": [
    {
      "label": "Hotel und Gastronomie",
      "value": "hotel"
    },
    {
      "label": "Kanzlei",
      "value": "kanzlei"
    },
    {
      "label": "Handwerk",
      "value": "handwerk"
    }
  ],
  "required": false,
  "sortOrder": 1,
  "updatedAt": "2026-01-02T08:00:00Z",
  "version": 1
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/masterdata/field-defs' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"entity":"ADDRESS","key":"branche","kind":"select","label":"Branche","options":[{"label":"IT","value":"it"},{"label":"Handel","value":"handel"}],"required":false,"sortOrder":10}'
```
