ConnectCloud Developers

Update a tenant-defined field (tenant:settings:write)

PUT /api/masterdata/field-defs/{id}

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

key, kind and entity cannot change (400); version must match.

Parameters

Name In Type Required Description
id path string (uuid) yes

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:

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

Responses

  • 200 Saved (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)
  • 404 Not found in the caller's tenant (or merged, see code) (application/json)
  • 409 Stale version or conflict with existing data (application/json)

Fields of the 200 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 200 answer:

{
  "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 PUT 'https://api.mbcom.cloud/api/masterdata/field-defs/3f6c1a52-7b1e-4d2a-9c8e-2b5f0d6a91e4' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"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}'

View as Markdown · Interactive reference · OpenAPI