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 inactivecategory(fieldnames it). 413 – the file is larger than the limit (25 MB by default). 415multipart_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.
listFoldersreturns every folder the caller may see, flat: build the tree fromparentId(null= top level). Each folder hasdocumentCount,restricted, the caller'saccess(READorWRITE) and aversion.createFolderwithnameand optionalparentId; names are unique among siblings, ignoring case (409).updateFolderrenames or moves a folder at itsversion(409 when the version is stale or a sibling has the name, 422 when it would move into its own subtree).moveDocumentsfiles up to 500 documents in one folder (folderId: nulltakes them out of every folder), all or nothing. Moving changes neither content, hash nor retention.- An upload with
folderIdfiles the new document there (400when the folder is unknown,403when the caller may only read it);folderId=nonefiles it nowhere, nofolderIdfiles 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.