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 ofADDRESS,CONTACT,POSTAL)key(string, required): Immutable; values are stored under this key and filtered withcf.<key>kind(string, required): Immutable (one oftext,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 refusedcreatedAt(string (date-time), read-only): Creation timedescription(string): Help text (max length 1000)id(string (uuid), read-only): Id of the field definitionoptions(array of FieldOption): Unique non-empty values (select and multiselect)value(string, required): Stored valuecolor(string): Display colourlabel(string): Defaults tovalue
required(boolean): A value is required on writesortOrder(integer): Position in formsupdatedAt(string (date-time), read-only): Time of the last changeversion(integer): Optimistic locking version (updates)
Example:
{
"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 ofADDRESS,CONTACT,POSTAL)key(string, required): Immutable; values are stored under this key and filtered withcf.<key>kind(string, required): Immutable (one oftext,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 refusedcreatedAt(string (date-time), read-only): Creation timedescription(string): Help text (max length 1000)id(string (uuid), read-only): Id of the field definitionoptions(array of FieldOption): Unique non-empty values (select and multiselect)value(string, required): Stored valuecolor(string): Display colourlabel(string): Defaults tovalue
required(boolean): A value is required on writesortOrder(integer): Position in formsupdatedAt(string (date-time), read-only): Time of the last changeversion(integer): Optimistic locking version (updates)
Example 201 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 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}'