## Upload a document (tenant:dms:write)

`POST /api/dms/v1/documents/upload`

Module: DMS · operationId: `uploadDocument` · Tag: Documents · Auth: access token (`Authorization: Bearer <accessToken>`)

Stores one file (`file` part) with its metadata. Put all form fields before the file part.
A document type is required: `category` (an active type code) or `documentRole`. The SHA-256
of the content is checked first: if the tenant already has the same unencrypted file, the
existing document is returned with `200` and `duplicate: true` (links requested in the
upload are added to it). The MIME type is detected from the part's `Content-Type`, the file
name and the content. Extractable formats are queued for text extraction unless
`extractText=false`; with a malware scanner the new version starts as `scanStatus: PENDING`.

Size limit: 25 MB per file by default (configurable by the operator); `413` beyond.

### Request body

`multipart/form-data` (required)

- `file` (string (binary), required): The file (exactly one)
- `category` (string): Active document type code (required unless `documentRole` is given)
- `confidentialLevel` (ConfidentialLevel): (one of `PUBLIC`, `INTERNAL`, `CONFIDENTIAL`, `STRICTLY_CONFIDENTIAL`; default `"INTERNAL"`)
- `documentRole` (string): Files the document under the type assigned to the role when no `category` is given (one of `incoming_original`, `incoming_supplement`)
- `encryption` (string): JSON `EncryptionInput`; the file part is then the ciphertext
- `extractText` (boolean): `true` forces, `false` disables text extraction; by default every extractable format is queued
- `folderId` (string): Files the new document in this folder (`400` when unknown, `403` when read-only); `none` = no folder; omitted = the default folder of the document type (if the caller may write there). A duplicate keeps its folder.
- `isEncrypted` (boolean): Marks a client-encrypted upload; requires `encryption`
- `isLocked` (boolean): Lock the document (WORM) on upload
- `isPortalVisible` (boolean): Visible in the customer portal (default `false`)
- `links` (string): JSON array of `LinkInput` (at most 50 links per upload, together with `targetType`)
- `lockRetentionDays` (integer): With `isLocked`, lock for this many days from now
- `metadata` (string): JSON object
- `mimeType` (string): Plaintext MIME type of an encrypted upload
- `relationType` (string): With `targetType`
- `source` (string): How the document entered the DMS (one of `upload`, `mail`, `internal`, `api`; default `"upload"`)
- `targetId` (string): With `targetType`, the record to link
- `targetModule` (string): With `targetType`
- `targetType` (TargetType): Type of the linked record (case-insensitive); `STANDALONE` = no link (one of `CUSTOMER`, `SUPPLIER`, `DISTRIBUTOR`, `ADDRESS`, `ARTICLE`, `TRANSACTION`, `INVOICE`, `CONTRACT`, `EMPLOYEE`, `TRAVEL_REPORT`, `TICKET`, `WORK_ITEM`, `FORGE_ITEM`, `LEAD`, `OPPORTUNITY`, `CAMPAIGN`, `PROJECT`, `ASSET`, `STANDALONE`)
- `title` (string): Defaults to the file name

### Responses

- **200** The file already existed; the existing document is returned (`application/json`)
- **201** Stored (`application/json`)
- **400** Error (`application/json`)
- **413** Error (`application/json`)
- **415** Error (`application/json`)
- **503** Error (`application/json`)

Fields of the 201 answer:

- `document` (Document, required)
  - `confidentialLevel` (ConfidentialLevel, required): (one of `PUBLIC`, `INTERNAL`, `CONFIDENTIAL`, `STRICTLY_CONFIDENTIAL`; default `"INTERNAL"`)
  - `createdAt` (string (date-time), required): Upload time
  - `currentVersion` (integer, required): Current version number
  - `customerNo` (string, required): Customer number of the tenant
  - `documentNumber` (string, required): Per-tenant, per-year document number
  - `extraction` (Extraction, required): Text extraction state of the current version
    - `attempts` (integer, required): Extraction attempts so far
    - `degraded` (boolean, required): At least one page was extracted in degraded quality
    - `pagesProcessed` (integer, required): Pages extracted so far
    - `pagesTotal` (integer, required): Pages of the file
    - `status` (ExtractionStatus, required): (one of `NONE`, `PENDING`, `PROCESSING`, `DONE`, `PARTIAL`, `SKIPPED`, `FAILED`)
    - `eInvoice` (string): Detected e-invoice format (one of `XRECHNUNG_CII`, `XRECHNUNG_UBL`, `ZUGFERD`)
    - `error` (string): Error message of a failed extraction
    - `errorCode` (string): Error code of a FAILED or SKIPPED extraction
    - `updatedAt` (string (date-time)): Time of the last state change
  - `fileName` (string, required): File name of the current version
  - `fileSize` (integer (int64), required): Size of the current version
  - `id` (string (uuid), required): Document id
  - `isArchived` (boolean, required): Same as `isLocked`
  - `isEncrypted` (boolean, required): Content is client-side encrypted
  - `isLocked` (boolean, required): WORM lock (same as `isArchived`)
  - `isPortalVisible` (boolean, required): Visible in the customer portal
  - `legalHold` (boolean, required): A legal hold blocks deletion regardless of retention
  - `mimeType` (string, required): MIME type of the current version
  - `retentionYears` (integer, required): Retention period in years (from the document type)
  - `s3Bucket` (string, required): Storage bucket of the current version
  - `s3Key` (string, required): Storage key of the current version
  - `s3Path` (string, required): Same as `s3Key`
  - `scanStatus` (ScanStatus, required): Malware scan of the version (one of `PENDING`, `CLEAN`, `INFECTED`, `SKIPPED`, `FAILED`)
  - `sha256Hash` (string, required): Same as `hashSha256` (empty when unknown)
  - `sizeBytes` (integer (int64), required): Size of the current version (same as `fileSize`)
  - `tenantName` (string, required): Tenant name
  - `title` (string, required): Defaults to the file name
  - `updatedAt` (string (date-time), required): Time of the last change
  - `uploadedBy` (string, required): Who uploaded the document
  - `version` (integer, required): Current version number (same as `currentVersion`)
  - `category` (string): Document type code
  - `classificationStatus` (string): Document classifier: type taken over automatically, proposal waiting for review, or chosen by a person; omitted when never classified (one of `classified`, `needs_review`, `confirmed`)
  - `deletedAt` (string (date-time)): Time of the soft delete
  - `encryptionAlgorithm` (string): Only for encrypted documents
  - `folderId` (string (uuid)): Folder the document is filed in; omitted when it has none
  - `folderPath` (array of FolderRef): The folder and its ancestors, top level first (detail only)
    - `id` (string (uuid), required): Folder id
    - `name` (string, required): Folder name
  - `hashSha256` (string): SHA-256 (hex) of the current version
  - `links` (array of DocumentLink): Omitted when the document has none
    - `createdAt` (string (date-time), required): Creation time
    - `createdBy` (string, required): Who created the link
    - `customerNo` (string, required): Customer number of the tenant
    - `documentId` (string (uuid), required): The linked document
    - `id` (string (uuid), required): Link id
    - `relationType` (string, required): Kind of relation, a free code (default ATTACHMENT)
    - `targetId` (string, required): Id of the linked record
    - `targetModule` (string, required): Module of the linked record
    - `targetType` (string, required): Type of the linked record (see TargetType)
    - `tenantName` (string, required): Tenant name
  - `lockRetentionUntil` (string (date-time)): End of the WORM lock
  - `metadata` (object): Free metadata (JSON object)
  - `retentionUntil` (string (date-time)): End of the retention period; deletion is refused before
  - `source` (string): How the document entered the DMS (one of `upload`, `mail`, `internal`, `api`)
  - `versions` (array of DocumentVersion): Only in the detail and after a version upload
    - `createdAt` (string (date-time), required): Upload time
    - `createdBy` (string, required): Who uploaded the version
    - `customerNo` (string, required): Customer number of the tenant
    - `documentId` (string (uuid), required): The document of the version
    - `fileName` (string, required): File name of the version
    - `fileSize` (integer (int64), required): Size in bytes
    - `id` (string (uuid), required): Version id
    - `mimeType` (string, required): MIME type of the version
    - `s3Path` (string, required): Storage key of the version
    - `scanStatus` (ScanStatus, required)
    - `sha256Hash` (string, required): SHA-256 (hex) of the version
    - `tenantName` (string, required): Tenant name
    - `versionNumber` (integer, required): Version number, from 1
    - `changeSummary` (string): What changed with this version
- `duplicate` (boolean, required): The tenant already had a document with the same content; it is returned instead

Example 201 answer:

```json
{
  "document": {
    "category": "incoming_document",
    "classificationStatus": "classified",
    "confidentialLevel": "INTERNAL",
    "createdAt": "2026-09-30T08:40:12Z",
    "currentVersion": 1,
    "customerNo": "99999",
    "documentNumber": "DOC-2026-000042",
    "extraction": {
      "attempts": 1,
      "degraded": false,
      "eInvoice": "ZUGFERD",
      "pagesProcessed": 2,
      "pagesTotal": 2,
      "status": "DONE",
      "updatedAt": "2026-09-30T08:41:03Z"
    },
    "fileName": "RE-482117.pdf",
    "fileSize": 184320,
    "folderId": "3b1f6a2c-7d4e-4f1a-9c2b-8e5d0a1f7b63",
    "folderPath": [
      {
        "id": "1d3f5a7c-9e1b-4d3f-8a5c-7e9b1d3f5a7c",
        "name": "Buchhaltung"
      },
      {
        "id": "3b1f6a2c-7d4e-4f1a-9c2b-8e5d0a1f7b63",
        "name": "Eingangsrechnungen 2026"
      }
    ],
    "hashSha256": "5e2b8c4f1a7d3e9b0c6f2a8d4e1b7c3f9a5d0e6b2c8f4a1d7e3b9c5f0a6d2e8b",
    "id": "3f6c2a1e-8b4d-4c7a-9e21-5d0b7a9c1f42",
    "isArchived": true,
    "isEncrypted": false,
    "isLocked": true,
    "isPortalVisible": false,
    "legalHold": false,
    "links": [
      {
        "createdAt": "2026-09-30T08:40:12Z",
        "createdBy": "christina.adler@muster-it.example",
        "customerNo": "99999",
        "documentId": "3f6c2a1e-8b4d-4c7a-9e21-5d0b7a9c1f42",
        "id": "6e8a0c2e-4f6a-4b8c-9d0e-2f4a6c8e0a2c",
        "relationType": "ATTACHMENT",
        "targetId": "70001",
        "targetModule": "masterdata",
        "targetType": "SUPPLIER",
        "tenantName": "DEMO"
      }
    ],
    "lockRetentionUntil": "2036-12-31T23:59:59Z",
    "metadata": {
      "invoiceNumber": "RE-482117",
      "supplier": "Nordlicht IT-Distribution GmbH"
    },
    "mimeType": "application/pdf",
    "retentionUntil": "2036-12-31T23:59:59Z",
    "retentionYears": 10,
    "s3Bucket": "99999-demo-prod-mbcom-cloud",
    "s3Key": "dms/99999/DEMO/2026/09/3f6c2a1e-8b4d-4c7a-9e21-5d0b7a9c1f42/RE-482117.pdf",
    "s3Path": "dms/99999/DEMO/2026/09/3f6c2a1e-8b4d-4c7a-9e21-5d0b7a9c1f42/RE-482117.pdf",
    "scanStatus": "CLEAN",
    "sha256Hash": "5e2b8c4f1a7d3e9b0c6f2a8d4e1b7c3f9a5d0e6b2c8f4a1d7e3b9c5f0a6d2e8b",
    "sizeBytes": 184320,
    "source": "mail",
    "tenantName": "DEMO",
    "title": "Rechnung RE-482117 Nordlicht IT-Distribution",
    "updatedAt": "2026-09-30T08:41:03Z",
    "uploadedBy": "christina.adler@muster-it.example",
    "version": 1
  },
  "duplicate": false
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/dms/v1/documents/upload' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@document.pdf'
```
