ConnectCloud Developers

Create a callback (desk:write)

POST /api/desk/v1/callbacks

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

The status is the callbackStatus entry with the default flag unless status names one; the responsible person defaults to the caller; responsibleRef: "" creates it without one (the pool of unassigned callbacks, scope=unassigned), and nobody is notified. The responsible person gets the notification desk.callback_notice unless they created it themselves. Custom fields are those of settings.callbacks.fields (customFields, keys without cf.).

The note must satisfy the tenant's note rules (settings.callbacks.note): required, minimum length, pattern (each 400 invalid, field note, with a message for the person) and the optional AI check (422 note_rejected, the message is the hint). The AI check never blocks when the AI is unavailable. A callback created in a status with a customer mail behaves like a status change into it (customerMail, see POST /callbacks/{id}/status).

Request body

application/json (required)

  • clearDesiredAt (boolean): Removes the desired time
  • contact (Ref): Reference into another system (masterdata, ERP) with a name snapshot.
    • id (string, required): Id in the other system
    • name (string, required): Name at the time of the reference
    • extra (object): Further facts of the referenced record
  • contactName (string): ≤ 200 characters
  • customFields (object): Values of the custom fields of the callback form by key
  • customer (Ref): Reference into another system (masterdata, ERP) with a name snapshot.
    • id (string, required): Id in the other system
    • name (string, required): Name at the time of the reference
    • extra (object): Further facts of the referenced record
  • desiredAt (string (date-time)): When the contact wants to be called back
  • desiredHasTime (boolean): desiredAt carries a time of day (false: only the date counts)
  • doneNote (string): ≤ 10000 characters
  • note (string): ≤ 10000 characters
  • origin (string): Create only (ignored on change): the activity it is made from, comms:interaction:<id> or comms:calendar:<id> (400 otherwise); Arbeitsplatz › Aktivitäten „Rückruf anlegen“
  • phone (string): Required on create; digits, a leading +, spaces and ( ) / - . (≤ 40)
  • reason (string): Key of a callbackReason entry
  • responsibleName (string): Name of the person responsible
  • responsibleRef (string): User ref; absent or null on create: the caller; "" = nobody (the pool of unassigned callbacks; on change it unassigns)
  • status (string): Create only: a callbackStatus key (default: the default entry)
  • version (integer): Required on change

Example:

{
  "contact": {
    "id": "6b8d0f2a-4c6e-4a8b-9d1f-3a5c7e9b1d11",
    "name": "Katrin Stadler"
  },
  "contactName": "Katrin Stadler",
  "customer": {
    "id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c11",
    "name": "Alpenhotel Seeblick GmbH \u0026 Co. KG"
  },
  "desiredAt": "2026-11-19T08:00:00Z",
  "desiredHasTime": true,
  "note": "Frau Stadler möchte kurz zur Kassenanbindung sprechen, bevor die Frühschicht beginnt.",
  "phone": "+49 8652 987612",
  "reason": "callback_requested",
  "responsibleRef": "elias.gruber@muster-it.example"
}

Responses

  • 201 Created; customerMail is set when its status has a customer mail (application/json)
  • 400 Error (application/json)
  • 403 Error (application/json)
  • 422 note_rejected: the AI check refused the note (the message is the hint) (application/json)

Fields of the 201 answer:

  • 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): (one of new, active, waiting, done)
    • 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)

Example 201 answer:

{
  "closed": false,
  "contact": {
    "id": "6b8d0f2a-4c6e-4a8b-9d1f-3a5c7e9b1d11",
    "name": "Katrin Stadler"
  },
  "contactName": "Katrin Stadler",
  "createdAt": "2026-11-17T15:20:00Z",
  "createdBy": "sophie.huber@muster-it.example",
  "createdByName": "Sophie Huber",
  "customFields": {},
  "customer": {
    "id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c11",
    "name": "Alpenhotel Seeblick GmbH \u0026 Co. KG"
  },
  "desiredAt": "2026-11-19T08:00:00Z",
  "desiredHasTime": true,
  "doneNote": "",
  "id": "7b4c5d6e-8f9a-4b0c-9d2e-4f5a6b7c8d01",
  "itemId": "",
  "note": "Frau Stadler möchte kurz zur Kassenanbindung sprechen, bevor die Frühschicht beginnt.",
  "number": 12,
  "origin": "",
  "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
}

Example request

curl -X POST 'https://api.mbcom.cloud/api/desk/v1/callbacks' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"contact":{"id":"6b8d0f2a-4c6e-4a8b-9d1f-3a5c7e9b1d11","name":"Katrin Stadler"},"contactName":"Katrin Stadler","customer":{"id":"3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c11","name":"Alpenhotel Seeblick GmbH \u0026 Co. KG"},"desiredAt":"2026-11-19T08:00:00Z","desiredHasTime":true,"note":"Frau Stadler möchte kurz zur Kassenanbindung sprechen, bevor die Frühschicht beginnt.","phone":"+49 8652 987612","reason":"callback_requested","responsibleRef":"elias.gruber@muster-it.example"}'

View as Markdown · Interactive reference · OpenAPI