## List tenant-defined fields (tenant:masterdata:read)

`GET /api/masterdata/field-defs`

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

Ordered by entity, sort order and key.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `entity` | query | string |  | Only fields of this entity (case-insensitive); all when omitted (one of `ADDRESS`, `CONTACT`, `POSTAL`) |
| `includeArchived` | query | boolean |  | (default `false`) |

### Responses

- **200** Field definitions (`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`)

Fields of the 200 answer:

- `items` (array of FieldDef, 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 200 answer:

```json
{
  "items": [
    {
      "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 GET 'https://api.mbcom.cloud/api/masterdata/field-defs' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```
