Set the due date of a ticket relative to now (desk:write, agent role)
POST /api/desk/v1/items/{ref}/due
Module: Desk · operationId: setItemDue · Tag: Items · Auth: access token (Authorization: Bearer <accessToken>)
in is a duration (90m, 4h, 2d; days are 24 hours; else 400 in). businessHours: true counts it in the tenant's default service calendar (wall-clock time when there is none). One of the single steps automations and flows take on a ticket (ADR 0044): it needs neither the ticket's version nor its whole list. History, outbox, SLA and automations follow as for every change; a converted ticket is 409 converted.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
ref |
path | string | yes | Item id or number |
Request body
application/json (required)
in(string, required): Duration from now: 90m, 4h, 2dbusinessHours(boolean): Count the duration in the tenant's default service calendar
Example:
{
"businessHours": true,
"in": "4h"
}
Responses
- 200 The ticket after the step and the automations it started (
application/json) - 400 Error (
application/json) - 403 Error (
application/json) - 404 Error (
application/json) - 409 Error (
application/json) - 422 Error (
application/json)
Fields of the 200 answer:
assignees(array of object): People working on the item (the whole list)role(string): Key of an assigneeRole entry (bootstrap enums); omitted = the default roleuserRef(string): Login (e-mail) of the person
categoryId(string, nullable): Category of the itemconfidential(boolean): Only holders of desk:confidential, the item's creator and its assignees see itcontact(Ref | null): Masterdata contact person of the item (null clears)customFields(object): Merged; null removes a valuecustomer(Ref | null): Masterdata customer of the item (null clears)dedupeKey(string): Create only; repeated deliveries return the existing itemdescription(string): MarkdowndueAt(string (date-time), nullable): Due datedueHasTime(boolean): dueAt carries a time of day (false: only the date counts)estimateMinutes(integer, nullable): Estimate in minutesfollowUpAt(string (date-time), nullable): When to follow upimpact(string, nullable): Impact key of the priority matrixkbWorthy(boolean): Candidate for the knowledge base once resolvedlabelIds(array of string): Labels of the item (ids; the whole list)parentId(string, nullable): Parent item; a child takes the parent's project (with its own children), detaching keeps itpriority(string, nullable): Priority keyprojectId(string, nullable): Project of the item (decision 19). A child item always has its parent's project: another one is refused (422, field projectId); changing it on a parent changes it on all its descendantsprojectMilestoneId(string, nullable): Milestone of the item's project it counts for (ADR 0024); cleared when the item leaves the projectrank(string): Board order (base-36 fraction)source(string): Create only; key of a source entry (bootstrap enums). API clients sendapi: the space's due date on receipt (settings.dueOnReceipt) tells the channels apart by it; without a source a ticket counts as manual.sourceOrigin(string): Create only: the activity of Arbeitsplatz › Aktivitäten the ticket is created from (comms:interaction:<id>orcomms:calendar:<id>; 400 otherwise); a free reference the portal links to /activities, never changed afterwardssourceRef(string): Reference of the source (e.g. the sender address of a mail ticket)spaceId(string): Create onlystartOn(string (date), nullable): Start datestatus(string): Create onlysummary(string, nullable): Summary pinned above the description (Markdown, trimmed). A new ticket starts with its description (a mail ticket with the trimmed text of its mail), capped at 2000 characters; null fills it that way again. Only the change is in the history, not the text. Never shown in the customer portal or handed to forge. (max length 20000)teams(array of object): Teams of the item (the whole list)role(string): responsible or collaborating (one ofresponsible,collaborating)teamId(string): Id of the team
title(string): Title of the item (max length 500)typeId(string): Create onlyurgency(string, nullable): Urgency key of the priority matrixweight(integer, nullable): Weight of the itemchecklistDone(integer): Ticked checklist itemschecklistTotal(integer): Checklist itemschildCount(integer): Number of direct childrenclosedAt(string (date-time), nullable): When the item reached a closed statusconvertedTo(object): Set on the tombstone of a ticket converted to another module (read-only: edits, transitions, moves, merges, splits, links to or from it, moving entries into it, checklist and plan dependencies are 409converted; entries, participants and uploads by agents stay possible)at(string (date-time)): When the ticket was convertedid(string): Id of the item the ticket becamemodule(string): Module of the item the ticket became (one ofdesk,forge)path(string): Portal path of that itemref(string): Reference of that item (#42 or APP-12)
convertingSince(string (date-time)): A conversion is pending; edits are 409conversion_pendingcreatedAt(string (date-time)): When the item was createdcreatedBy(string): Login (e-mail) of who created the itemforwarding(boolean): A tombstone with requesters or people in copy: the forwarding stubhandoffs(array of Handoff): The ticket's handoffs and conversions in both roles, newest first (single-item answers only:GET /items/{ref}and the answers of writes; omitted when there are none)attempts(integer): Delivery attempts so farcounterpartCheckedAt(string (date-time)): When the other side was last synchronisedcounterpartContainerId(string (uuid)): Space or project id of the other sidecounterpartContainerKey(string): Space or project key of the other sidecounterpartItemId(string (uuid)): Item id of the other sidecounterpartModule(string): Module of the other side (one ofdesk,forge)counterpartRef(string): Reference of the other side's item (e.g. #42 or APP-12)counterpartStage(string): Last known stage of the other side's item (gone: deleted) (one ofnew,active,waiting,done,cancelled,gone)counterpartStatusKey(string): Last known status key of the other side's itemcounterpartStatusName(string): Last known status name of the other side's itemcreatedAt(string (date-time)): When the handoff was startedcreatedByName(string): Name of who started the handoffcreatedByRef(string): Login (e-mail) of who started the handoffid(string (uuid)): Id of the handoffitemId(string (uuid)): Desk item of this sidekind(string): handoff (a new linked item) or conversion (the item moved) (one ofhandoff,conversion)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 loggednextAttemptAt(string (date-time)): When delivery is tried next (pending)returnNote(string): Note given when the item was handed backreturnedAt(string (date-time)): When the item was handed backreturnedByName(string): Name of who handed it backreturnedByRef(string): Login (e-mail) of who handed it backrole(string): origin: this ticket handed over; receiver: this ticket was received (one oforigin,receiver)state(string): State of the handoff (one ofopen,handed_back,closed,converted)syncState(string): Delivery to the other module: pending, confirmed or failed (one ofpending,confirmed,failed)updatedAt(string (date-time)): When the handoff row last changedversion(integer): Version of the handoff row
id(string): Id of the itemlastAgentPublicAt(string (date-time), nullable): Last publiclastCustomerAt(string (date-time), nullable): Last publicmergedIntoId(string): Item this one was merged into (read-only afterwards)number(integer): Number of the item, unique in the tenant (#42)pendingSuggestions(integer): AI suggestions waiting for a personphase(Phase): (one ofnew,active,waiting,done)projectTicketDisplay(string, read-only): Ticket display of the item's project (tickets,projects,hidden); empty without project (one of ``,tickets,projects,hidden)rating(object): The requester's satisfaction rating from the customer portal (single-item answers only; omitted when there is none)comment(string): Comment of the requesterratedAt(string (date-time)): When the ticket was ratedrating(integer): Stars (1–5) (max 5)requesterEmail(string): E-mail of the requester who ratedrequesterName(string): Name of the requester who rated
slaDueAt(string (date-time), nullable): Earliest running SLA deadlineslaState(string): State of the item's SLA clocks (one ofnone,running,warning,breached,paused,met)spentMinutes(integer, nullable): Work HR booked on the ticket (subjectdesk:item:<id>, worked minus breaks, ADR 0040), filled in single answers and lists; null when HR does not answerstatusChangedAt(string (date-time)): When the status last changedsummarySource(string, read-only): Who wrote the summary last:auto(the first message),ai(an AI summary was applied) orperson(edited by a person, the assistant or an API key; automatic AI summaries never overwrite it) (one ofauto,ai,person)updatedAt(string (date-time)): When the item was last changedupdatedBy(string): Login (e-mail) of who last changed the itemversion(integer): Version of the item; send it back on change (409 version_conflict when it is outdated)
Example 200 answer:
{
"assignees": [
{
"role": "owner",
"userRef": "lukas.wimmer@muster-it.example"
},
{
"role": "assignee",
"userRef": "sophie.huber@muster-it.example"
}
],
"categoryId": "0c7d8e9f-1a2b-4c3d-8e5f-7a8b9c0d1e02",
"checklistDone": 1,
"checklistTotal": 2,
"childCount": 0,
"closedAt": null,
"confidential": false,
"contact": {
"id": "6b8d0f2a-4c6e-4a8b-9d1f-3a5c7e9b1d11",
"name": "Katrin Stadler"
},
"createdAt": "2026-11-17T07:12:00Z",
"createdBy": "sophie.huber@muster-it.example",
"customFields": {
"betroffenes_system": "Access Points 2. OG (AP-201, AP-207)"
},
"customer": {
"id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c11",
"name": "Alpenhotel Seeblick GmbH \u0026 Co. KG"
},
"description": "Frau Stadler meldet telefonisch: Seit gestern Abend beschweren sich Gäste im 2. Obergeschoss, dass das WLAN alle paar Minuten abbricht. Betroffen sind vor allem die Zimmer 201 bis 212.",
"dueAt": "2026-11-17T11:12:00Z",
"dueHasTime": true,
"estimateMinutes": null,
"followUpAt": null,
"forwarding": false,
"handoffs": [],
"id": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5c01",
"impact": "mittel",
"kbWorthy": false,
"labelIds": [
"9b6c7d8e-0f1a-4b2c-9d4e-6f7a8b9c0d01",
"9b6c7d8e-0f1a-4b2c-9d4e-6f7a8b9c0d02"
],
"lastAgentPublicAt": "2026-11-17T08:55:00Z",
"lastCustomerAt": "2026-11-17T07:12:00Z",
"number": 1,
"parentId": null,
"pendingSuggestions": 0,
"phase": "active",
"priority": "hoch",
"projectId": null,
"slaDueAt": "2026-11-17T15:12:00Z",
"slaState": "running",
"source": "phone",
"spaceId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c00",
"spentMinutes": 45,
"status": "in_bearbeitung",
"statusChangedAt": "2026-11-17T07:21:00Z",
"summary": "Seit gestern Abend bricht das WLAN in den Zimmern 201 bis 212 alle paar Minuten ab.",
"summarySource": "auto",
"teams": [
{
"role": "responsible",
"teamId": "1d8e9f0a-2b3c-4d4e-9f6a-8b9c0d1e2f02"
}
],
"title": "WLAN in den Gästezimmern 2. OG fällt immer wieder aus",
"typeId": "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f01",
"updatedAt": "2026-11-17T08:55:00Z",
"updatedBy": "lukas.wimmer@muster-it.example",
"urgency": "hoch",
"version": 6
}
Example request
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/items/string/due' \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
--data '{"businessHours":true,"in":"4h"}'