Check a new item without creating it (desk:write)
POST /api/desk/v1/items/check
Module: Desk · operationId: checkItem · Tag: Items · Auth: access token (Authorization: Bearer <accessToken>)
Runs every check of POST /items (space, type, status, field values, required fields of the type
layout) except the parent, without storing anything. Answers the same errors as POST /items.
With preview=true the answer also says what creating the item would do (the portal's create form,
„Beim Anlegen passiert“): the due date on receipt of its space and source, the SLA policy with the due
time of each target (none while the start status pauses the clock) and the enabled automations of
desk.item.created in the tenant and the space whose filter holds for the new item. Nothing runs and
nothing is recorded; the server decides again when the item is created.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
preview |
query | boolean | Also answer preview: what creating the item would do |
Request body
application/json (required)
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 item
Example:
{
"contact": {
"id": "6b8d0f2a-4c6e-4a8b-9d1f-3a5c7e9b1d11",
"name": "Katrin Stadler"
},
"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": "Seit gestern Abend bricht das WLAN in den Zimmern 201 bis 212 alle paar Minuten ab.",
"impact": "mittel",
"source": "api",
"spaceId": "SUP",
"title": "WLAN in den Gästezimmern 2. OG fällt immer wieder aus",
"typeId": "stoerung",
"urgency": "hoch"
}
Responses
- 200 Valid (
application/json) - 400 Error (
application/json) - 403 Error (
application/json) - 422 Error (
application/json)
Fields of the 200 answer:
preview(ItemPreview): What creating an item would do (POST /items/check?preview=true); nothing is stored.automations(array of object): Enabled automations ofdesk.item.created(tenant first, then the space) whose filter holdsid(string)key(string)name(string)scope(string):tenantorspace:<id>
dueAt(string (date-time), nullable): The due date on receipt (space.settings.dueOnReceipt), else nullsla(object, nullable): The SLA policy the item would get; null when none applies (no policy matches, a work type)policyKey(string)policyName(string)targets(array of object)dueAt(string (date-time), nullable): Null while the start status pauses the clocktarget(string): (one offirst_response,resolution)
valid(boolean)
Example 200 answer:
{
"preview": {
"automations": [],
"dueAt": "2026-11-18T13:14:00Z",
"sla": {
"policyKey": "standard",
"policyName": "Standard",
"targets": [
{
"dueAt": "2026-11-18T13:14:00Z",
"target": "first_response"
},
{
"dueAt": "2026-11-19T09:14:00Z",
"target": "resolution"
}
]
}
},
"valid": true
}
Example request
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/items/check' \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
--data '{"contact":{"id":"6b8d0f2a-4c6e-4a8b-9d1f-3a5c7e9b1d11","name":"Katrin Stadler"},"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":"Seit gestern Abend bricht das WLAN in den Zimmern 201 bis 212 alle paar Minuten ab.","impact":"mittel","source":"api","spaceId":"SUP","title":"WLAN in den Gästezimmern 2. OG fällt immer wieder aus","typeId":"stoerung","urgency":"hoch"}'