ConnectCloud Developers

Documents (DMS)

The DMS (Dokumentenmanagement) keeps a tenant's files audit-proof: every file is stored with its SHA-256 hash, new content becomes a new immutable version, every read and change is written to an audit trail, and a document cannot be deleted before its retention period has ended. Everything below is under https://api.mbcom.cloud/api/dms/v1; every operation is in the DMS reference.

Step Operations Permission
Upload uploadDocument (or createDocument, the same upload) tenant:dms:write
Read and list getDocument, listDocuments tenant:dms:read
File in folders listFolders, createFolder, updateFolder, moveDocuments read: tenant:dms:read, changes: tenant:dms:write
New version addDocumentVersion, listDocumentVersions tenant:dms:write / tenant:dms:read
Download getDocumentContent, downloadDocument, getDocumentVersionContent tenant:dms:read
Text getDocumentText tenant:dms:read
Link to a record addDocumentLink, removeDocumentLink tenant:dms:write

Document types

Every upload needs a document type (Dokumentart, the field category). Types are tenant configuration with a retention period each: read the active ones with listDocumentTypes instead of hard-coding codes. New tenants start with types such as incoming_document (Eingangsbeleg), delivery_note, contract, correspondence and other. Instead of a type an upload may name a role (documentRole: incoming_original or incoming_supplement); the DMS files it under the type the tenant assigned to that role (getDocumentTypeRoles).

Upload a document

Uploads are multipart/form-data with exactly one file part. Put every form field before the file part – fields after it are ignored. curl sends the parts in the order you give them:

curl -X POST 'https://api.mbcom.cloud/api/dms/v1/documents/upload' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -F 'title=Lieferschein LS-2026-0815' \
  -F 'category=delivery_note' \
  -F 'source=api' \
  -F 'metadata={"deliveryNote":"LS-2026-0815"}' \
  -F 'links=[{"targetType":"SUPPLIER","targetId":"70011"}]' \
  -F 'file=@lieferschein-2026-0815.pdf;type=application/pdf'

The answer is an UploadResult: the document and duplicate.

  • 201 – a new document with version 1 and its documentNumber (DOC-2026-000042).
  • 200 with duplicate: true – the tenant already has a file with the same SHA-256. The existing document is returned and the links of the upload are added to it, so an upload is idempotent by content: retrying it after a network error never stores the file twice.
  • 400 invalid – e.g. no or an inactive category (field names it). 413 – the file is larger than the limit (25 MB by default). 415 multipart_required – the body is not multipart.

Optional fields: folderId (see Folders), links (a JSON array of up to 50 links, or one link as targetType / targetId / relationType), confidentialLevel, isLocked with lockRetentionDays (WORM lock) and extractText (false skips text extraction). The MIME type is detected from the part's Content-Type, the file name and the content.

The malware scan

Every file is scanned for malware before it is served, extracted or handed on. The state is scanStatus on the document (its current version) and on every entry of versions:

scanStatus Meaning Content endpoints answer
PENDING stored, not scanned yet – every new version starts here 409 not_scanned
CLEAN scanned, no finding 200 with the file
INFECTED the scanner found malware 403 infected, never served
FAILED the scan failed repeatedly; it is tried again after an hour 409 not_scanned
SKIPPED no scanner ran (or a client-encrypted upload); scanned as soon as a scanner runs 409 not_scanned

So right after an upload the document exists – it is listed, can be linked, filed and moved – but its file cannot be read yet. A client that needs the content reads getDocument until scanStatus is CLEAN (start after a second and back off; most scans take seconds), or simply retries the content request on 409 not_scanned. Stop on INFECTED: the version stays stored for the audit trail, but its content is never served, its text never extracted (extraction.status SKIPPED, errorCode infected) and it is left out of auditor exports. Upload a clean file as a new version or as a new document.

Text extraction (text layer, OCR, e-invoice detection) waits for CLEAN as well, so extraction.status stays PENDING until the scan has passed.

Read and list documents

getDocument returns the document with its links, versions, folder path, scanStatus and extraction. listDocuments lists newest first and pages by cursor (limit 1–100, pass nextCursor as cursor with the same filter until it is missing, see Pagination). Filters: search (full text over title, file name, document number and extracted text), category, source, isLocked, folderId (with includeSubfolders), containerId and a linked record (targetType + targetId, or targetType=STANDALONE for documents without any link):

curl 'https://api.mbcom.cloud/api/dms/v1/documents?targetType=SUPPLIER&targetId=70011&limit=50' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Documents a platform module owns (for example the mails of desk tickets) follow that module's access rules and never appear in this API.

Folders

Folders file a tenant's documents in a tree (at most 10 levels). A document is in at most one folder, independent of its links; documents without one are Ohne Ordner.

  • listFolders returns every folder the caller may see, flat: build the tree from parentId (null = top level). Each folder has documentCount, restricted, the caller's access (READ or WRITE) and a version.
  • createFolder with name and optional parentId; names are unique among siblings, ignoring case (409).
  • updateFolder renames or moves a folder at its version (409 when the version is stale or a sibling has the name, 422 when it would move into its own subtree).
  • moveDocuments files up to 500 documents in one folder (folderId: null takes them out of every folder), all or nothing. Moving changes neither content, hash nor retention.
  • An upload with folderId files the new document there (400 when the folder is unknown, 403 when the caller may only read it); folderId=none files it nowhere, no folderId files it in the default folder of its document type.

A folder can be restricted to people and key groups by an administrator. Folders the caller may not see do not exist for it: their documents answer 404 and are left out of lists. A change in a folder with READ access answers 403 with code folder_read_only.

Versions

New content for a document is a new version; older ones stay readable.

curl -X POST 'https://api.mbcom.cloud/api/dms/v1/documents/3f6c2a1e-8b4d-4c7a-9e21-5d0b7a9c1f42/versions' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -F 'changeSummary=Unterschriebene Fassung' \
  -F 'file=@vertrag-v2.pdf;type=application/pdf'

addDocumentVersion answers 201 with the document, its new currentVersion and all versions. The new version starts as scanStatus: PENDING like every upload, so the document's content is 409 not_scanned until it is clean – even if the previous version was. Older versions are still served by getDocumentVersionContent (/versions/{version}/content) while they are CLEAN. listDocumentVersions lists them newest first, each with versionNumber, fileName, sha256Hash, changeSummary and its own scanStatus.

Download

Call Returns
GET /documents/{id}/content the file of the current version, inline (download=true: as attachment)
GET /documents/{id}/download a JSON descriptor (fileName, mimeType, fileSize, sha256Hash, downloadUrl); with stream=true the file as attachment
GET /documents/{id}/versions/{version}/content the file of one version

Files come with their MIME type, the SHA-256 as ETag, Cache-Control: private, no-store and X-Content-Type-Options: nosniff; compare the hash to make sure you hold the stored bytes. Every content read is written to the document's audit trail (VIEW or DOWNLOAD). Errors: 403 infected, 409 not_scanned (see The malware scan), 404 for a document the caller may not see, 503 storage_unavailable – retry later.

The extracted text is getDocumentText (Markdown or plain text, per page). It answers 409 extraction_pending while the extraction is queued or running and 422 when there is no text (not_extracted, encrypted or the extraction's error code such as no_text), both with the extraction status in details.

Delete

deleteDocument is a soft delete: the document disappears from the API, its record, hashes and audit trail stay. It is refused with 409 while the retention period runs (retention_active, with details.retentionUntil), under a WORM lock (locked) or a legal hold (legal_hold).

Events

For webhooks and flows, the DMS announces dms.document.created, dms.document.version_created, dms.document.linked, dms.document.unlinked, dms.document.filed, dms.document.text_extracted, dms.document.deleted and more (listed in the reference). Events carry ids and states, never document text: read the document through the API, and expect its content to answer 409 not_scanned until the scan has finished.

View as Markdown