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 timecontact(Ref): Reference into another system (masterdata, ERP) with a name snapshot.id(string, required): Id in the other systemname(string, required): Name at the time of the referenceextra(object): Further facts of the referenced record
contactName(string): ≤ 200 characterscustomFields(object): Values of the custom fields of the callback form by keycustomer(Ref): Reference into another system (masterdata, ERP) with a name snapshot.id(string, required): Id in the other systemname(string, required): Name at the time of the referenceextra(object): Further facts of the referenced record
desiredAt(string (date-time)): When the contact wants to be called backdesiredHasTime(boolean): desiredAt carries a time of day (false: only the date counts)doneNote(string): ≤ 10000 charactersnote(string): ≤ 10000 charactersorigin(string): Create only (ignored on change): the activity it is made from,comms:interaction:<id>orcomms: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 entryresponsibleName(string): Name of the person responsibleresponsibleRef(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;
customerMailis 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 flagclosedAt(string (date-time), nullable): When the callback was closedclosedBy(string): Login (e-mail) of who closed the callbackcontact(object): Masterdata contact snapshot (only with a customer)contactName(string): Name of the person to call backconvertedAt(string (date-time), nullable): When the callback was turned into a ticketcreatedAt(string (date-time)): When the callback was createdcreatedBy(string): Login (e-mail) of who created the callbackcreatedByName(string): Name of who created the callbackcustomFields(object): Values of the fields of settings.callbacks.fields, keyed without cf.customer(object): Masterdata address snapshotcustomerMail(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 (modeauto, nomissing) or, when it was not sent, why (missing). Never on reads.desiredAt(string (date-time), nullable): When the contact wants to be called backdesiredHasTime(boolean): false: only the day of desiredAt countsdoneNote(string): Result of the callid(string (uuid)): Id of the callbackitem(ItemSummary)id(string): Id of the itemnumber(integer): Number of the itemphase(Phase): (one ofnew,active,waiting,done)spaceId(string): Space of the itemstatus(string): Status keytitle(string): TitletypeId(string): Type of the item
itemId(string, nullable): The ticket it becamenote(string): Note of the callbacknumber(integer): Per tenantorigin(string): The call it was made from in Arbeitsplatz › Aktivitäten (comms:interaction:<id>,comms:calendar:<id>); "" noneoverdue(boolean, read-only): Open and the desired time (without time: the desired day) has passedphone(string): Phone number to call backreason(string): Key of a callbackReason entry, "" = noneresponsibleName(string): Name of the person responsibleresponsibleRef(string): User ref of the person who calls back; "" = nobody yet (the pool of unassigned callbacks)status(string): Key of a callbackStatus entryupdatedAt(string (date-time)): When the callback was last changedversion(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"}'