# 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](/reference/dms).

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

```bash
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](#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`](/reference/dms/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`](/reference/dms/getDocument) returns the document with its links, versions, folder path, `scanStatus`
and `extraction`. [`listDocuments`](/reference/dms/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](/guides/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):

```bash
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`](/reference/dms/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`](/reference/dms/createFolder) with `name` and optional `parentId`; names are unique among siblings,
  ignoring case (**409**).
- [`updateFolder`](/reference/dms/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`](/reference/dms/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.

```bash
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`](/reference/dms/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`](/reference/dms/getDocumentVersionContent) (`/versions/{version}/content`)
while they are `CLEAN`. [`listDocumentVersions`](/reference/dms/listDocumentVersions) lists them newest first, each
with `versionNumber`, `fileName`, `sha256Hash`, `changeSummary` and its own `scanStatus`.

## Download

| Call | Returns |
|---|---|
| [`GET /documents/{id}/content`](/reference/dms/getDocumentContent) | the file of the current version, inline (`download=true`: as attachment) |
| [`GET /documents/{id}/download`](/reference/dms/downloadDocument) | a JSON descriptor (`fileName`, `mimeType`, `fileSize`, `sha256Hash`, `downloadUrl`); with `stream=true` the file as attachment |
| [`GET /documents/{id}/versions/{version}/content`](/reference/dms/getDocumentVersionContent) | 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](#the-malware-scan)), **404** for a document the caller may not see, **503**
`storage_unavailable` – retry later.

The extracted text is [`getDocumentText`](/reference/dms/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`](/reference/dms/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](/guides/webhooks) and [flows](/guides/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.
