ConnectCloud Developers

Create an item (desk:write)

POST /api/desk/v1/items

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

The body has the item's JSON shape. spaceId and typeId accept ids or keys; without typeId the space's default type is used, without status the workflow's first "new" status. Required fields of the type layout must be filled (422 missing_fields).

Parameters

Name In Type Required Description
Idempotency-Key header string

Request body

application/json (required)

  • assignees (array of object): People working on the item (the whole list)
    • role (string): Key of an assigneeRole entry (bootstrap enums); omitted = the default role
    • userRef (string): Login (e-mail) of the person
  • categoryId (string, nullable): Category of the item
  • confidential (boolean): Only holders of desk:confidential, the item's creator and its assignees see it
  • contact (Ref | null): Masterdata contact person of the item (null clears)
  • customFields (object): Merged; null removes a value
  • customer (Ref | null): Masterdata customer of the item (null clears)
  • dedupeKey (string): Create only; repeated deliveries return the existing item
  • description (string): Markdown
  • dueAt (string (date-time), nullable): Due date
  • dueHasTime (boolean): dueAt carries a time of day (false: only the date counts)
  • estimateMinutes (integer, nullable): Estimate in minutes
  • followUpAt (string (date-time), nullable): When to follow up
  • impact (string, nullable): Impact key of the priority matrix
  • kbWorthy (boolean): Candidate for the knowledge base once resolved
  • labelIds (array of string): Labels of the item (ids; the whole list)
  • parentId (string, nullable): Parent item; a child takes the parent's project (with its own children), detaching keeps it
  • priority (string, nullable): Priority key
  • projectId (string, nullable): Project of the item (decision 19). A child item always has its parent's project: another one is refused (422, field projectId); changing it on a parent changes it on all its descendants
  • projectMilestoneId (string, nullable): Milestone of the item's project it counts for (ADR 0024); cleared when the item leaves the project
  • rank (string): Board order (base-36 fraction)
  • source (string): Create only; key of a source entry (bootstrap enums). API clients send api: the space's due date on receipt (settings.dueOnReceipt) tells the channels apart by it; without a source a ticket counts as manual.
  • sourceOrigin (string): Create only: the activity of Arbeitsplatz › Aktivitäten the ticket is created from (comms:interaction:<id> or comms:calendar:<id>; 400 otherwise); a free reference the portal links to /activities, never changed afterwards
  • sourceRef (string): Reference of the source (e.g. the sender address of a mail ticket)
  • spaceId (string): Create only
  • startOn (string (date), nullable): Start date
  • status (string): Create only
  • summary (string, nullable): Summary pinned above the description (Markdown, trimmed). A new ticket starts with its description (a mail ticket with the trimmed text of its mail), capped at 2000 characters; null fills it that way again. Only the change is in the history, not the text. Never shown in the customer portal or handed to forge. (max length 20000)
  • teams (array of object): Teams of the item (the whole list)
    • role (string): responsible or collaborating (one of responsible, collaborating)
    • teamId (string): Id of the team
  • title (string): Title of the item (max length 500)
  • typeId (string): Create only
  • urgency (string, nullable): Urgency key of the priority matrix
  • weight (integer, nullable): Weight of the item

Example:

{
  "customFields": {
    "betroffenes_system": "FortiClient 7.2"
  },
  "customer": {
    "id": "K-10023",
    "name": "Muster GmbH"
  },
  "description": "Seit heute morgen trennt der VPN-Client alle 5 Minuten.",
  "impact": "mittel",
  "spaceId": "SUP",
  "title": "VPN-Verbindung bricht ab",
  "typeId": "stoerung",
  "urgency": "hoch"
}

Responses

  • 200 Existing item (idempotency or dedupe key) (application/json)
  • 201 Created (application/json)
  • 400 Error (application/json)
  • 403 Error (application/json)
  • 422 Error (application/json)

Fields of the 201 answer:

  • assignees (array of object): People working on the item (the whole list)
    • role (string): Key of an assigneeRole entry (bootstrap enums); omitted = the default role
    • userRef (string): Login (e-mail) of the person
  • categoryId (string, nullable): Category of the item
  • confidential (boolean): Only holders of desk:confidential, the item's creator and its assignees see it
  • contact (Ref | null): Masterdata contact person of the item (null clears)
  • customFields (object): Merged; null removes a value
  • customer (Ref | null): Masterdata customer of the item (null clears)
  • dedupeKey (string): Create only; repeated deliveries return the existing item
  • description (string): Markdown
  • dueAt (string (date-time), nullable): Due date
  • dueHasTime (boolean): dueAt carries a time of day (false: only the date counts)
  • estimateMinutes (integer, nullable): Estimate in minutes
  • followUpAt (string (date-time), nullable): When to follow up
  • impact (string, nullable): Impact key of the priority matrix
  • kbWorthy (boolean): Candidate for the knowledge base once resolved
  • labelIds (array of string): Labels of the item (ids; the whole list)
  • parentId (string, nullable): Parent item; a child takes the parent's project (with its own children), detaching keeps it
  • priority (string, nullable): Priority key
  • projectId (string, nullable): Project of the item (decision 19). A child item always has its parent's project: another one is refused (422, field projectId); changing it on a parent changes it on all its descendants
  • projectMilestoneId (string, nullable): Milestone of the item's project it counts for (ADR 0024); cleared when the item leaves the project
  • rank (string): Board order (base-36 fraction)
  • source (string): Create only; key of a source entry (bootstrap enums). API clients send api: the space's due date on receipt (settings.dueOnReceipt) tells the channels apart by it; without a source a ticket counts as manual.
  • sourceOrigin (string): Create only: the activity of Arbeitsplatz › Aktivitäten the ticket is created from (comms:interaction:<id> or comms:calendar:<id>; 400 otherwise); a free reference the portal links to /activities, never changed afterwards
  • sourceRef (string): Reference of the source (e.g. the sender address of a mail ticket)
  • spaceId (string): Create only
  • startOn (string (date), nullable): Start date
  • status (string): Create only
  • summary (string, nullable): Summary pinned above the description (Markdown, trimmed). A new ticket starts with its description (a mail ticket with the trimmed text of its mail), capped at 2000 characters; null fills it that way again. Only the change is in the history, not the text. Never shown in the customer portal or handed to forge. (max length 20000)
  • teams (array of object): Teams of the item (the whole list)
    • role (string): responsible or collaborating (one of responsible, collaborating)
    • teamId (string): Id of the team
  • title (string): Title of the item (max length 500)
  • typeId (string): Create only
  • urgency (string, nullable): Urgency key of the priority matrix
  • weight (integer, nullable): Weight of the item
  • checklistDone (integer): Ticked checklist items
  • checklistTotal (integer): Checklist items
  • childCount (integer): Number of direct children
  • closedAt (string (date-time), nullable): When the item reached a closed status
  • convertedTo (object): Set on the tombstone of a ticket converted to another module (read-only: edits, transitions, moves, merges, splits, links to or from it, moving entries into it, checklist and plan dependencies are 409 converted; entries, participants and uploads by agents stay possible)
    • at (string (date-time)): When the ticket was converted
    • id (string): Id of the item the ticket became
    • module (string): Module of the item the ticket became (one of desk, forge)
    • path (string): Portal path of that item
    • ref (string): Reference of that item (#42 or APP-12)
  • convertingSince (string (date-time)): A conversion is pending; edits are 409 conversion_pending
  • createdAt (string (date-time)): When the item was created
  • createdBy (string): Login (e-mail) of who created the item
  • forwarding (boolean): A tombstone with requesters or people in copy: the forwarding stub
  • handoffs (array of Handoff): The ticket's handoffs and conversions in both roles, newest first (single-item answers only: GET /items/{ref} and the answers of writes; omitted when there are none)
    • attempts (integer): Delivery attempts so far
    • counterpartCheckedAt (string (date-time)): When the other side was last synchronised
    • counterpartContainerId (string (uuid)): Space or project id of the other side
    • counterpartContainerKey (string): Space or project key of the other side
    • counterpartItemId (string (uuid)): Item id of the other side
    • counterpartModule (string): Module of the other side (one of desk, forge)
    • counterpartRef (string): Reference of the other side's item (e.g. #42 or APP-12)
    • counterpartStage (string): Last known stage of the other side's item (gone: deleted) (one of new, active, waiting, done, cancelled, gone)
    • counterpartStatusKey (string): Last known status key of the other side's item
    • counterpartStatusName (string): Last known status name of the other side's item
    • createdAt (string (date-time)): When the handoff was started
    • createdByName (string): Name of who started the handoff
    • createdByRef (string): Login (e-mail) of who started the handoff
    • id (string (uuid)): Id of the handoff
    • itemId (string (uuid)): Desk item of this side
    • kind (string): handoff (a new linked item) or conversion (the item moved) (one of handoff, conversion)
    • lastError (string, read-only): Why the last delivery failed or waits, as a fixed German text (receiver unreachable or not connected, confirmation not stored, the refusal reason by code, 24 hours passed); never the transport error, which is only logged
    • nextAttemptAt (string (date-time)): When delivery is tried next (pending)
    • returnNote (string): Note given when the item was handed back
    • returnedAt (string (date-time)): When the item was handed back
    • returnedByName (string): Name of who handed it back
    • returnedByRef (string): Login (e-mail) of who handed it back
    • role (string): origin: this ticket handed over; receiver: this ticket was received (one of origin, receiver)
    • state (string): State of the handoff (one of open, handed_back, closed, converted)
    • syncState (string): Delivery to the other module: pending, confirmed or failed (one of pending, confirmed, failed)
    • updatedAt (string (date-time)): When the handoff row last changed
    • version (integer): Version of the handoff row
  • id (string): Id of the item
  • lastAgentPublicAt (string (date-time), nullable): Last public
  • lastCustomerAt (string (date-time), nullable): Last public
  • mergedIntoId (string): Item this one was merged into (read-only afterwards)
  • number (integer): Number of the item, unique in the tenant (#42)
  • pendingSuggestions (integer): AI suggestions waiting for a person
  • phase (Phase): (one of new, active, waiting, done)
  • projectTicketDisplay (string, read-only): Ticket display of the item's project (tickets, projects, hidden); empty without project (one of ``, tickets, projects, hidden)
  • rating (object): The requester's satisfaction rating from the customer portal (single-item answers only; omitted when there is none)
    • comment (string): Comment of the requester
    • ratedAt (string (date-time)): When the ticket was rated
    • rating (integer): Stars (1–5) (max 5)
    • requesterEmail (string): E-mail of the requester who rated
    • requesterName (string): Name of the requester who rated
  • slaDueAt (string (date-time), nullable): Earliest running SLA deadline
  • slaState (string): State of the item's SLA clocks (one of none, running, warning, breached, paused, met)
  • spentMinutes (integer, nullable): Work HR booked on the ticket (subject desk:item:<id>, worked minus breaks, ADR 0040), filled in single answers and lists; null when HR does not answer
  • statusChangedAt (string (date-time)): When the status last changed
  • summarySource (string, read-only): Who wrote the summary last: auto (the first message), ai (an AI summary was applied) or person (edited by a person, the assistant or an API key; automatic AI summaries never overwrite it) (one of auto, ai, person)
  • updatedAt (string (date-time)): When the item was last changed
  • updatedBy (string): Login (e-mail) of who last changed the item
  • version (integer): Version of the item; send it back on change (409 version_conflict when it is outdated)

Example 201 answer:

{
  "assignees": [],
  "createdAt": "2026-11-18T09:14:00Z",
  "createdBy": "api:ticket-import",
  "customFields": {
    "betroffenes_system": "FortiClient 7.2"
  },
  "customer": {
    "id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c12",
    "name": "Kanzlei Hofmann \u0026 Partner Rechtsanwälte mbB"
  },
  "description": "Seit heute morgen trennt der VPN-Client alle 5 Minuten.",
  "handoffs": [],
  "id": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5c4e",
  "impact": "mittel",
  "labelIds": [],
  "number": 78,
  "phase": "new",
  "priority": "hoch",
  "slaDueAt": "2026-11-18T13:14:00Z",
  "slaState": "running",
  "source": "api",
  "spaceId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c00",
  "status": "neu",
  "statusChangedAt": "2026-11-18T09:14:00Z",
  "summary": "Seit heute morgen trennt der VPN-Client alle 5 Minuten.",
  "summarySource": "auto",
  "teams": [],
  "title": "VPN-Verbindung bricht ab",
  "typeId": "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f01",
  "updatedAt": "2026-11-18T09:14:00Z",
  "updatedBy": "api:ticket-import",
  "urgency": "hoch",
  "version": 1
}

Example request

curl -X POST 'https://api.mbcom.cloud/api/desk/v1/items' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"customFields":{"betroffenes_system":"FortiClient 7.2"},"customer":{"id":"K-10023","name":"Muster GmbH"},"description":"Seit heute morgen trennt der VPN-Client alle 5 Minuten.","impact":"mittel","spaceId":"SUP","title":"VPN-Verbindung bricht ab","typeId":"stoerung","urgency":"hoch"}'

View as Markdown · Interactive reference · OpenAPI