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 farcounterpartCheckedAt(string (date-time)): When the other side was last synchronisedcounterpartContainerId(string (uuid)): Space or project id of the other sidecounterpartContainerKey(string): Space or project key of the other sidecounterpartItemId(string (uuid)): Item id of the other sidecounterpartModule(string): Module of the other side (one ofdesk,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 ofnew,active,waiting,done,cancelled,gone)counterpartStatusKey(string): Last known status key of the other side's itemcounterpartStatusName(string): Last known status name of the other side's itemcreatedAt(string (date-time)): When the handoff was startedcreatedByName(string): Name of who started the handoffcreatedByRef(string): Login (e-mail) of who started the handoffid(string (uuid)): Id of the handoffitemId(string (uuid)): Desk item of this sidekind(string): handoff (a new linked item) or conversion (the item moved) (one ofhandoff,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 loggednextAttemptAt(string (date-time)): When delivery is tried next (pending)returnNote(string): Note given when the item was handed backreturnedAt(string (date-time)): When the item was handed backreturnedByName(string): Name of who handed it backreturnedByRef(string): Login (e-mail) of who handed it backrole(string): origin: this ticket handed over; receiver: this ticket was received (one oforigin,receiver)state(string): State of the handoff (one ofopen,handed_back,closed,converted)syncState(string): Delivery to the other module: pending, confirmed or failed (one ofpending,confirmed,failed)updatedAt(string (date-time)): When the handoff row last changedversion(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."}'