ConnectCloud Developers

Upload a new version of a document (tenant:dms:write)

POST /api/dms/v1/documents/{id}/versions

Module: DMS · operationId: addDocumentVersion · Tag: Versions · Auth: access token (Authorization: Bearer <accessToken>)

Stores the file part as the next version; the previous versions stay. Encrypted documents only take encrypted versions (encryption field) and plain documents only plain ones. Size limit as for uploads (25 MB by default).

Parameters

Name In Type Required Description
id path string (uuid) yes

Request body

multipart/form-data (required)

  • file (string (binary), required): The file (exactly one)
  • changeSummary (string): What changed with this version (max length 1000)
  • encryption (string): JSON EncryptionInput; required for encrypted documents
  • extractText (boolean): true forces, false disables text extraction
  • mimeType (string): Plaintext MIME type of an encrypted version

Responses

  • 201 The document with its new current version and all versions (application/json)
  • 400 Error (application/json)
  • 404 Error (application/json)
  • 413 Error (application/json)
  • 415 Error (application/json)
  • 503 Error (application/json)

Fields of the 201 answer:

  • 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): Malware scan of the version (one of PENDING, CLEAN, INFECTED, SKIPPED, FAILED)
    • 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

Example 201 answer:

{
  "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
}

Example request

curl -X POST 'https://api.mbcom.cloud/api/dms/v1/documents/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/versions' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@document.pdf'

View as Markdown · Interactive reference · OpenAPI