## 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:

```json
{
  "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:

```json
{
  "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

```bash
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)."}'
```
