ConnectCloud Developers

Upload a document (tenant:dms:write)

POST /api/dms/v1/documents

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

The same upload as POST /api/dms/v1/documents/upload (201 new, 200 duplicate, body UploadResult). Only multipart/form-data is accepted: any other body is 415 multipart_required (the former JSON variant, which registered an already stored file by s3Bucket/s3Key, was removed – a document only points at a file DMS stored itself).

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 Created (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:

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

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

View as Markdown · Interactive reference · OpenAPI