ConnectCloud Developers

Hand a received item back (tenant:forge:write and, as a member, at least developer)

POST /api/forge/v1/projects/{key}/items/{number}/handoffs/{id}/return

Module: Forge · operationId: returnForgeItemHandoff · Tag: Handoffs · Auth: access token (Authorization: Bearer <accessToken>)

Requires the permission to change the item (forge write; CanEditItem). The item must be the receiver of the handoff (else 404), the handoff open or closed (409 handoff_state). Marks it handed back with the note (≤ 2 000 characters), applies the project's receiverOnReturn (default: close with resolution returned) as a system move, records handed_back, writes forge.handoff.returned and runs the automations on forge.item.handed_back. A forge origin is updated in the same transaction (system comment with the note, its project's originOnReturn, handback_received); desk learns it from forge's feed.

Parameters

Name In Type Required Description
key path string yes Project key (e.g. APP)
number path integer yes Item number in the project (12 of APP-12)
id path string (uuid) yes

Request body

application/json (required)

  • note (string): (max length 2000)

Example:

{
  "note": "Kein Fehler und vorerst keine Funktion der App: Den PDF-Export der Ticketliste gibt es im Kundenportal im Browser (Tickets → Exportieren)."
}

Responses

  • 200 Handed back (application/json)
  • 400 Error (application/json)
  • 403 Error (application/json)
  • 404 Error (application/json)
  • 409 Error (application/json)

Fields of the 200 answer:

  • counterpartModule (string, required): Module of the other side (one of desk, forge)
  • counterpartRef (string, required): Reference of the item on the other side (#123 or APP-12)
  • counterpartStage (string, required): Last known stage of the other item; gone when it no longer exists (one of new, active, waiting, done, cancelled, gone)
  • createdAt (string (date-time), required): When the handoff was started
  • id (string (uuid), required): Handoff id, shared with the other side
  • itemId (string (uuid), required): The forge item of this side
  • kind (string, required): handoff: a new linked item; conversion: the item moved and left a tombstone (one of handoff, conversion)
  • role (string, required): Which side this row is: the origin (handed over) or the receiver (one of origin, receiver)
  • state (string, required): State of the handoff (one of open, handed_back, closed, converted)
  • syncState (string, required): Delivery to the other side: pending, confirmed or failed (one of pending, confirmed, failed)
  • attempts (integer): Delivery attempts so far
  • counterpartCheckedAt (string (date-time)): When the other side was last checked
  • counterpartContainerId (string): Desk space or forge project id of the other side (once known)
  • counterpartContainerKey (string): Desk space key or forge project key of the other side
  • counterpartItemId (string): Id of the item on the other side (once known)
  • counterpartStatusKey (string): Last known status key of the other item
  • counterpartStatusName (string): Last known status name of the other item
  • createdByName (string): Name of who started the handoff
  • createdByRef (string): E-mail of who started the handoff
  • 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)): Next delivery attempt while pending
  • projectId (string (uuid)): Project of the forge item
  • returnNote (string): Note given when the item was handed back
  • returnedAt (string (date-time)): When it was handed back
  • returnedByName (string): Name of who handed it back
  • returnedByRef (string): E-mail of who handed it back
  • updatedAt (string (date-time)): Last change of this side
  • version (integer): Version of this row

Example 200 answer:

{
  "attempts": 0,
  "counterpartCheckedAt": "2026-11-12T11:00:05Z",
  "counterpartContainerId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c00",
  "counterpartContainerKey": "SUP",
  "counterpartItemId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c38",
  "counterpartModule": "desk",
  "counterpartRef": "#38",
  "counterpartStage": "active",
  "counterpartStatusKey": "in_bearbeitung",
  "counterpartStatusName": "In Bearbeitung",
  "createdAt": "2026-11-11T14:30:00Z",
  "createdByName": "Elias Gruber",
  "createdByRef": "elias.gruber@muster-it.example",
  "id": "3f4a5b6c-7d8e-5f9a-8b0c-2d3e4f5a6b02",
  "itemId": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c19",
  "kind": "handoff",
  "projectId": "0b6c1e1e-3f0b-4e8e-9f3f-1d2c3b4a5f60",
  "returnNote": "Kein Fehler und vorerst keine Funktion der App: Den PDF-Export der Ticketliste gibt es im Kundenportal im Browser (Tickets → Exportieren).",
  "returnedAt": "2026-11-12T11:00:00Z",
  "returnedByName": "Emma Maier",
  "returnedByRef": "emma.maier@muster-it.example",
  "role": "receiver",
  "state": "handed_back",
  "syncState": "confirmed",
  "updatedAt": "2026-11-12T11:00:00Z",
  "version": 3
}

Example request

curl -X POST 'https://api.mbcom.cloud/api/forge/v1/projects/string/items/1/handoffs/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/return' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"note":"Kein Fehler und vorerst keine Funktion der App: Den PDF-Export der Ticketliste gibt es im Kundenportal im Browser (Tickets → Exportieren)."}'

View as Markdown · Interactive reference · OpenAPI