Change status, fields and labels of many items, or check first with dryRun (desk:write)
POST /api/desk/v1/items/bulk
Module: Desk · operationId: bulkUpdateItems · Tag: Items · Auth: access token (Authorization: Bearer <accessToken>)
Request body
application/json (required)
ids(array of string, required): Ids of the items to changeaddLabelIds(array of string): Labels to add (ids)dryRun(boolean): Change nothing:updatedlists the items the change would apply to,failedandmissingFieldswhy the others would stay as they are (agent role, writable item, the transition with its required fields and comment). An item already in the status would not change. No automation, mail or live notice follows.patch(ItemInput)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
removeLabelIds(array of string): Labels to remove (ids)status(string): Status key to move every item to
Example:
{
"addLabelIds": [
"9b6c7d8e-0f1a-4b2c-9d4e-6f7a8b9c0d02"
],
"dryRun": false,
"ids": [
"#37",
"#41"
],
"patch": {
"priority": "hoch"
}
}
Responses
- 200 Per-item result (
application/json)
Fields of the 200 answer:
dryRun(boolean): True when the request was a dry run (nothing changed).failed(object): Why an item was not changed, in German, per item idmissingFields(object): Required fields the status change needs, per failed item id; retry that item with a transition that sends themupdated(array of string): The items changed – with dryRun the items the change would apply to
Example 200 answer:
{
"dryRun": false,
"failed": {
"#41": "Der Status „Gelöst“ verlangt die Felder Ursache, Lösung und Abschlussgrund"
},
"missingFields": {
"#41": [
"cf.ursache",
"cf.loesung",
"cf.abschlussgrund"
]
},
"updated": [
"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c37"
]
}
Example request
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/items/bulk' \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
--data '{"addLabelIds":["9b6c7d8e-0f1a-4b2c-9d4e-6f7a8b9c0d02"],"dryRun":false,"ids":["#37","#41"],"patch":{"priority":"hoch"}}'