ConnectCloud Developers

Hand a received ticket back (desk:write; agent in the ticket's space)

POST /api/desk/v1/items/{ref}/handoffs/{handoffId}/return

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

Receiver side: the received handoff of this ticket (open or closed; otherwise 409 handoff_state) is marked handed back with the note (at most 2000 characters). The space's settings.handoff.receiverOnReturn applies as a system move ignoring transitions and required fields (default close: its status when the workflow has it, else the closed status; keep: nothing), reason „Zurückgegeben: “; history handed_back, desk.handoff.returned, the automations of desk.item.handed_back. A desk origin learns it in the same transaction (system entry with the note, originOnReturn of its space – default none –, history handback_received, the automations of desk.item.handback_received); forge learns it from desk's feed.

Parameters

Name In Type Required Description
ref path string yes Item id or number
handoffId path string (uuid) yes

Request body

application/json (required)

  • note (string): (max length 2000)

Example:

{
  "note": "Kein Fehler: Die Kundin nutzte eine alte Version der App, nach dem Update stimmt die Anzeige."
}

Responses

  • 200 The handed-back row (application/json)
  • 400 Error (application/json)
  • 403 Error (application/json)
  • 404 Error (application/json)
  • 409 Error (application/json)

Fields of the 200 answer:

  • 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

Example 200 answer:

{
  "attempts": 1,
  "counterpartCheckedAt": "2026-11-16T10:02:00Z",
  "counterpartContainerId": "0b6c1e1e-3f0b-4e8e-9f3f-1d2c3b4a5f60",
  "counterpartContainerKey": "APP",
  "counterpartItemId": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c18",
  "counterpartModule": "forge",
  "counterpartRef": "APP-24",
  "counterpartStage": "active",
  "counterpartStatusKey": "in_arbeit",
  "counterpartStatusName": "In Arbeit",
  "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-16T10:02:00Z",
  "version": 3
}

Example request

curl -X POST 'https://api.mbcom.cloud/api/desk/v1/items/string/handoffs/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/return' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"note":"Kein Fehler: Die Kundin nutzte eine alte Version der App, nach dem Update stimmt die Anzeige."}'

View as Markdown · Interactive reference · OpenAPI