ConnectCloud Developers

Upload a file to the ticket, within the tenant's mail limits (desk:write, agent role)

POST /api/desk/v1/items/{ref}/attachments

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

The file is stored in DMS and scanned for malware afterwards: until the scan cleared it, its content answers 409 scan_pending, a file the scan found something in 403 infected.

Parameters

Name In Type Required Description
ref path string yes Item id or number

Request body

multipart/form-data (required)

  • file (string (binary), required)

Responses

  • 201 The stored file (application/json)
  • 400 No multipart file part, no usable file name, or the file breaks the tenant's mail limits (size, blocked type) – code invalid, field file (application/json)
  • 403 No desk:write, or not at least the agent role in the ticket's space (code forbidden) (application/json)
  • 404 No such ticket, or one the caller does not see (application/json)
  • 503 The file store is not configured (code unavailable) (application/json)

Fields of the 201 answer:

  • contentId (string): Content-ID of an inline image
  • createdAt (string (date-time)): When the file was added
  • documentId (string): DMS document holding the file
  • entryId (string): Entry (mail or comment) the file came with
  • id (string): Id of the file record
  • inline (boolean): An inline image of a mail body
  • itemId (string): Item the file belongs to
  • mime (string): MIME type
  • name (string): File name
  • portalVisible (boolean): Requesters see the file in the customer portal
  • size (integer): Size in bytes
  • source (string): mail: attachment of a mail; upload: staff upload; portal: requester upload; conversion: brought along by a conversion; eml: the original (.eml) of a received or sent mail (entryId set, never visible to requesters, never handed to forge); generated: made by desk (meeting transcripts) (one of mail, upload, portal, conversion, eml, generated)
  • uploadedBy (string): Login (e-mail) of who uploaded it

Example 201 answer:

{
  "contentId": "",
  "createdAt": "2026-11-17T08:41:00Z",
  "documentId": "3d0e1f2a-4b5c-4d6e-9f8a-0b1c2d3e4f01",
  "entryId": "",
  "id": "2c9d0e1f-3a4b-4c5d-8e7f-9a0b1c2d3e01",
  "inline": false,
  "itemId": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5c01",
  "mime": "text/plain",
  "name": "Controller-Log_AP-207.txt",
  "portalVisible": false,
  "size": 18233,
  "source": "upload",
  "uploadedBy": "lukas.wimmer@muster-it.example"
}

Example request

curl -X POST 'https://api.mbcom.cloud/api/desk/v1/items/string/attachments' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@document.pdf'

View as Markdown · Interactive reference · OpenAPI