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 ofdesk,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;gonewhen it no longer exists (one ofnew,active,waiting,done,cancelled,gone)createdAt(string (date-time), required): When the handoff was startedid(string (uuid), required): Handoff id, shared with the other sideitemId(string (uuid), required): The forge item of this sidekind(string, required):handoff: a new linked item;conversion: the item moved and left a tombstone (one ofhandoff,conversion)role(string, required): Which side this row is: the origin (handed over) or the receiver (one oforigin,receiver)state(string, required): State of the handoff (one ofopen,handed_back,closed,converted)syncState(string, required): Delivery to the other side: pending, confirmed or failed (one ofpending,confirmed,failed)attempts(integer): Delivery attempts so farcounterpartCheckedAt(string (date-time)): When the other side was last checkedcounterpartContainerId(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 sidecounterpartItemId(string): Id of the item on the other side (once known)counterpartStatusKey(string): Last known status key of the other itemcounterpartStatusName(string): Last known status name of the other itemcreatedByName(string): Name of who started the handoffcreatedByRef(string): E-mail of who started the handofflastError(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)): Next delivery attempt while pendingprojectId(string (uuid)): Project of the forge itemreturnNote(string): Note given when the item was handed backreturnedAt(string (date-time)): When it was handed backreturnedByName(string): Name of who handed it backreturnedByRef(string): E-mail of who handed it backupdatedAt(string (date-time)): Last change of this sideversion(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)."}'