ConnectCloud Developers

Convert a ticket to another desk space or to a forge project (desk:write; agent in the ticket's space)

POST /api/desk/v1/items/{ref}/convert

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

Header Idempotency-Key and the ticket's version are required. target.module desk: a move (POST /items/{ref}/move semantics: same ticket and number, 200). target.module forge: the conversion contract (version 1) carries title, description, type, status, custom fields by key, priority, dates, estimate, labels, assignees, watchers, the reporter, the agents' comments with author, time, kind and visibility, uploaded files (same DMS documents), links and the checklist (both listed in forge's note) and notes on what stays here (customer, contacts, mails, the requester's messages, time, project, parent). Free text is scrubbed of customer data like a handoff; a confidential ticket goes with full content and confidential. While forge has not confirmed, edits are 409 conversion_pending; once it has, the ticket is the read-only tombstone (convertedTo, closed; a forwarding stub when it has requesters or people in copy) with history converted. 201 confirmed, 202 pending (retried like a handoff), 422 handoff_refused, 409 has_children (sub-tickets), converted, version_conflict; 503 forge_unavailable.

Parameters

Name In Type Required Description
Idempotency-Key header string yes (max length 200)
ref path string yes Item id or number

Request body

application/json (required)

  • target (HandoffTarget, required)
    • container (string, required): Desk space key or forge project key
    • module (string, required): Module of the target (one of desk, forge)
    • statusKey (string): Status key of the new item
    • typeKey (string): Type key of the new item
  • version (integer, required)

Example:

{
  "target": {
    "container": "SUP",
    "module": "desk",
    "typeKey": "problem"
  },
  "version": 6
}

Responses

  • 200 Moved within desk (application/json)
  • 201 Converted (application/json)
  • 202 Pending (forge not reached yet) (application/json)
  • 400 Error (application/json)
  • 403 Error (application/json)
  • 404 Error (application/json)
  • 409 Error (application/json)
  • 422 Error (application/json)
  • 503 Error (application/json)

Fields of the 201 answer:

  • handoff (Handoff): Desk's side of a handoff or conversion (table handoffs).
    • 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
  • item (Item)
  • notes (array of string): What the receiver did not take over

Example 201 answer:

{
  "handoff": {
    "attempts": 1,
    "counterpartContainerId": "0b6c1e1e-3f0b-4e8e-9f3f-1d2c3b4a5f60",
    "counterpartContainerKey": "APP",
    "counterpartItemId": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c18",
    "counterpartModule": "forge",
    "counterpartRef": "APP-24",
    "counterpartStage": "new",
    "counterpartStatusKey": "offen",
    "counterpartStatusName": "Offen",
    "createdAt": "2026-11-13T09:10:00Z",
    "createdByName": "Sophie Huber",
    "createdByRef": "sophie.huber@muster-it.example",
    "id": "3f4a5b6c-7d8e-5f9a-8b0c-2d3e4f5a6b01",
    "itemId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c37",
    "kind": "handoff",
    "role": "origin",
    "state": "open",
    "syncState": "confirmed",
    "updatedAt": "2026-11-13T09:10:02Z",
    "version": 2
  },
  "item": {
    "createdAt": "2026-11-13T08:20:00Z",
    "customer": {
      "id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c11",
      "name": "Alpenhotel Seeblick GmbH \u0026 Co. KG"
    },
    "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c37",
    "number": 37,
    "phase": "waiting",
    "priority": "normal",
    "spaceId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c00",
    "status": "wartet_dritte",
    "title": "App zeigt gelöste Tickets weiterhin als offen",
    "typeId": "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f01",
    "updatedAt": "2026-11-13T09:10:02Z",
    "version": 4
  },
  "notes": []
}

Example request

curl -X POST 'https://api.mbcom.cloud/api/desk/v1/items/string/convert' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Idempotency-Key: string' \
  -H 'Content-Type: application/json' \
  --data '{"target":{"container":"SUP","module":"desk","typeKey":"problem"},"version":6}'

View as Markdown · Interactive reference · OpenAPI