## List callbacks (desk:write)

`GET /api/desk/v1/callbacks`

Module: Desk · operationId: `listCallbacks` · Tag: Callbacks · Auth: access token (`Authorization: Bearer <accessToken>`)

Callbacks (Rückrufe) with the total, `openMine` (the caller's open callbacks, the header badge) and
`openUnassigned` (open callbacks without a responsible person). `scope` `mine` lists the callbacks the caller is
responsible for, `unassigned` the pool of callbacks nobody is responsible for yet (`responsible` is ignored),
`all` everyone's (default). `status` is `open` (no
closed flag), `closed`, `any` (default) or a key of the value list `callbackStatus`. Sorted by desired time
(without one last), then newest (`sort=due`, default), or newest first by `created` / `updated`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `scope` | query | string |  | (one of `mine`, `unassigned`, `all`; default `"all"`) |
| `status` | query | string |  | open, closed, any (default) or a callbackStatus key |
| `responsible` | query | string |  | User ref of the responsible person |
| `customerId` | query | string |  | Masterdata address id |
| `reason` | query | string |  | Key of a callbackReason entry |
| `q` | query | string |  | Phone, contact name, customer name, note or number |
| `from` | query | string (date-time) |  | Desired time from (date or RFC 3339) |
| `to` | query | string (date-time) |  | Desired time before |
| `sort` | query | string |  | (one of `due`, `created`, `updated`; default `"due"`) |
| `limit` | query | integer |  | 1–200; another value is a 400 invalid. (default `50`; max 200) |
| `offset` | query | integer |  |  |

### Responses

- **200** A page of callbacks (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)

Fields of the 200 answer:

- `items` (array of Callback, required): Callbacks of the page
  - `closed` (boolean, read-only): The status carries the closed flag
  - `closedAt` (string (date-time), nullable): When the callback was closed
  - `closedBy` (string): Login (e-mail) of who closed the callback
  - `contact` (object): Masterdata contact snapshot (only with a customer)
  - `contactName` (string): Name of the person to call back
  - `convertedAt` (string (date-time), nullable): When the callback was turned into a ticket
  - `createdAt` (string (date-time)): When the callback was created
  - `createdBy` (string): Login (e-mail) of who created the callback
  - `createdByName` (string): Name of who created the callback
  - `customFields` (object): Values of the fields of settings.callbacks.fields, keyed without cf.
  - `customer` (object): Masterdata address snapshot
  - `customerMail` (object): Only in the answer of a create or status change into a status with a customer mail: the draft of a manual mail; for an automatic one the mail as queued (`mode` `auto`, no `missing`) or, when it was not sent, why (`missing`). Never on reads.
  - `desiredAt` (string (date-time), nullable): When the contact wants to be called back
  - `desiredHasTime` (boolean): false: only the day of desiredAt counts
  - `doneNote` (string): Result of the call
  - `id` (string (uuid)): Id of the callback
  - `item` (ItemSummary)
    - `id` (string): Id of the item
    - `number` (integer): Number of the item
    - `phase` (Phase)
    - `spaceId` (string): Space of the item
    - `status` (string): Status key
    - `title` (string): Title
    - `typeId` (string): Type of the item
  - `itemId` (string, nullable): The ticket it became
  - `note` (string): Note of the callback
  - `number` (integer): Per tenant
  - `origin` (string): The call it was made from in Arbeitsplatz › Aktivitäten (`comms:interaction:<id>`, `comms:calendar:<id>`); "" none
  - `overdue` (boolean, read-only): Open and the desired time (without time: the desired day) has passed
  - `phone` (string): Phone number to call back
  - `reason` (string): Key of a callbackReason entry, "" = none
  - `responsibleName` (string): Name of the person responsible
  - `responsibleRef` (string): User ref of the person who calls back; "" = nobody yet (the pool of unassigned callbacks)
  - `status` (string): Key of a callbackStatus entry
  - `updatedAt` (string (date-time)): When the callback was last changed
  - `version` (integer): Version of the callback; send it back on change (409 version_conflict when it is outdated)
- `openMine` (integer, required): Open callbacks the caller is responsible for
- `openUnassigned` (integer, required): Open callbacks without a responsible person (the pool)
- `total` (integer, required): Number of callbacks matching the filter

Example 200 answer:

```json
{
  "items": [
    {
      "closed": false,
      "contactName": "Katrin Stadler",
      "createdAt": "2026-11-17T15:20:00Z",
      "customer": {
        "id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c11",
        "name": "Alpenhotel Seeblick GmbH \u0026 Co. KG"
      },
      "desiredAt": "2026-11-19T08:00:00Z",
      "desiredHasTime": true,
      "id": "7b4c5d6e-8f9a-4b0c-9d2e-4f5a6b7c8d01",
      "note": "Frau Stadler möchte kurz zur Kassenanbindung sprechen, bevor die Frühschicht beginnt.",
      "number": 12,
      "overdue": false,
      "phone": "+49 8652 987612",
      "reason": "callback_requested",
      "responsibleName": "Elias Gruber",
      "responsibleRef": "elias.gruber@muster-it.example",
      "status": "open",
      "updatedAt": "2026-11-17T15:20:00Z",
      "version": 1
    }
  ],
  "openMine": 1,
  "openUnassigned": 2,
  "total": 1
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/desk/v1/callbacks' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```
