ConnectCloud Developers

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:

{
  "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

curl -X GET 'https://api.mbcom.cloud/api/masterdata/field-defs' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

View as Markdown · Interactive reference · OpenAPI