ConnectCloud Developers

Assign a document type by hand (tenant:dms:write)

PUT /api/dms/v1/documents/{id}/category

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

Sets the document type (category, an active type of the tenant) and with it the retention period of the type when that is longer (a change of type never shortens the retention, and it never ends before a WORM lock). It confirms or corrects the document classifier: the classification is recorded with source manual, the document's classificationStatus becomes confirmed, the start of its text is kept as example for later classifications of the tenant, and dms.document.classified is published with final: true. Sending the current type confirms it. The platform types – the e-mail original (mail), filed by the mailbox import, and outgoing_invoice, filed by trade for issued invoices – and the type of the Zusatzbeleg are assigned by the platform only: a document neither gets nor leaves them by hand (400 invalid with field: category).

Parameters

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

Request body

application/json (required)

  • category (string, required): Code of an active document type (max length 64)

Example:

{
  "category": "delivery_note"
}

Responses

  • 200 The document (application/json)
  • 400 Error (application/json)
  • 403 Error (application/json)
  • 404 Error (application/json)

Fields of the 200 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 200 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 PUT 'https://api.mbcom.cloud/api/dms/v1/documents/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/category' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"category":"delivery_note"}'

View as Markdown · Interactive reference · OpenAPI