ConnectCloud Developers

Update an item type and its field layout (desk:admin)

PUT /api/desk/v1/types/{id}

Module: Desk · operationId: updateType · Tag: Configuration · Auth: access token (Authorization: Bearer <accessToken>)

Parameters

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

Request body

application/json (required)

  • key (string, required): Key of the type, unique in the tenant
  • name (string, required): Name of the item type
  • workflowId (string, required): Workflow of the type
  • archived (boolean): Archived: the item type is kept for existing data but no longer offered in pickers
  • closeRequired (array of string): Fields that must be filled before the item can be closed
  • color (string): Display color of the item type
  • confidential (boolean): Items of the type are confidential
  • description (string): Description of the item type
  • focus (string): What the record page leads with; empty = conversation when the space has a reply mailbox, else work (one of ``, conversation, work)
  • icon (string): Icon of the item type
  • id (string, read-only): Id of the item type
  • layout (array of LayoutField): Custom fields of the record and their sections
    • key (string, required): System field (priority, dueAt, customer, …) or "cf."
    • required (boolean): The field must be filled
    • section (string): Section of the record page the field is shown in (one of facts, main, aside, closure)
  • level (integer): Hierarchy level, 0 = top (e.g. 0 epic, 1 issue/ticket, 2 task); a parent's level is lower than its children's (max 9)
  • sortOrder (integer): Position in lists (ascending)
  • version (integer): Version of the item type; send it back on change (409 version_conflict when it is outdated)

Example:

{
  "archived": false,
  "closeRequired": [
    "cf.ursache",
    "cf.loesung",
    "cf.abschlussgrund"
  ],
  "color": "error",
  "confidential": false,
  "description": "Etwas funktioniert nicht und muss wiederhergestellt werden.",
  "focus": "conversation",
  "icon": "i-lucide-flame",
  "id": "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f01",
  "key": "stoerung",
  "layout": [
    {
      "key": "description",
      "section": "main"
    },
    {
      "key": "customer",
      "section": "aside"
    },
    {
      "key": "priority",
      "section": "aside"
    },
    {
      "key": "cf.betroffenes_system",
      "section": "aside"
    },
    {
      "key": "cf.ursache",
      "section": "closure"
    },
    {
      "key": "cf.loesung",
      "section": "closure"
    },
    {
      "key": "cf.abschlussgrund",
      "section": "closure"
    }
  ],
  "level": 1,
  "name": "Störung",
  "sortOrder": 1,
  "version": 2,
  "workflowId": "4c1d2e3f-5a6b-4c7d-8e9f-1a2b3c4d5e01"
}

Responses

  • 200 Saved (application/json)
  • 409 in_use: the new focus work would make a mail source, route, AI candidate, portal form or platform feedback kind deliver into a work type or a space with only work types (the message names them); version_conflict (application/json)

Fields of the 200 answer:

  • key (string, required): Key of the type, unique in the tenant
  • name (string, required): Name of the item type
  • workflowId (string, required): Workflow of the type
  • archived (boolean): Archived: the item type is kept for existing data but no longer offered in pickers
  • closeRequired (array of string): Fields that must be filled before the item can be closed
  • color (string): Display color of the item type
  • confidential (boolean): Items of the type are confidential
  • description (string): Description of the item type
  • focus (string): What the record page leads with; empty = conversation when the space has a reply mailbox, else work (one of ``, conversation, work)
  • icon (string): Icon of the item type
  • id (string, read-only): Id of the item type
  • layout (array of LayoutField): Custom fields of the record and their sections
    • key (string, required): System field (priority, dueAt, customer, …) or "cf."
    • required (boolean): The field must be filled
    • section (string): Section of the record page the field is shown in (one of facts, main, aside, closure)
  • level (integer): Hierarchy level, 0 = top (e.g. 0 epic, 1 issue/ticket, 2 task); a parent's level is lower than its children's (max 9)
  • sortOrder (integer): Position in lists (ascending)
  • version (integer): Version of the item type; send it back on change (409 version_conflict when it is outdated)

Example 200 answer:

{
  "archived": false,
  "closeRequired": [
    "cf.ursache",
    "cf.loesung",
    "cf.abschlussgrund"
  ],
  "color": "error",
  "confidential": false,
  "description": "Etwas funktioniert nicht und muss wiederhergestellt werden.",
  "focus": "conversation",
  "icon": "i-lucide-flame",
  "id": "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f01",
  "key": "stoerung",
  "layout": [
    {
      "key": "description",
      "section": "main"
    },
    {
      "key": "customer",
      "section": "aside"
    },
    {
      "key": "priority",
      "section": "aside"
    },
    {
      "key": "cf.betroffenes_system",
      "section": "aside"
    },
    {
      "key": "cf.ursache",
      "section": "closure"
    },
    {
      "key": "cf.loesung",
      "section": "closure"
    },
    {
      "key": "cf.abschlussgrund",
      "section": "closure"
    }
  ],
  "level": 1,
  "name": "Störung",
  "sortOrder": 1,
  "version": 2,
  "workflowId": "4c1d2e3f-5a6b-4c7d-8e9f-1a2b3c4d5e01"
}

Example request

curl -X PUT 'https://api.mbcom.cloud/api/desk/v1/types/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"archived":false,"closeRequired":["cf.ursache","cf.loesung","cf.abschlussgrund"],"color":"error","confidential":false,"description":"Etwas funktioniert nicht und muss wiederhergestellt werden.","focus":"conversation","icon":"i-lucide-flame","id":"5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f01","key":"stoerung","layout":[{"key":"description","section":"main"},{"key":"customer","section":"aside"},{"key":"priority","section":"aside"},{"key":"cf.betroffenes_system","section":"aside"},{"key":"cf.ursache","section":"closure"},{"key":"cf.loesung","section":"closure"},{"key":"cf.abschlussgrund","section":"closure"}],"level":1,"name":"Störung","sortOrder":1,"version":2,"workflowId":"4c1d2e3f-5a6b-4c7d-8e9f-1a2b3c4d5e01"}'

View as Markdown · Interactive reference · OpenAPI