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 ofPUBLIC,INTERNAL,CONFIDENTIAL,STRICTLY_CONFIDENTIAL; default"INTERNAL")createdAt(string (date-time), required): Upload timecurrentVersion(integer, required): Current version numbercustomerNo(string, required): Customer number of the tenantdocumentNumber(string, required): Per-tenant, per-year document numberextraction(Extraction, required): Text extraction state of the current versionattempts(integer, required): Extraction attempts so fardegraded(boolean, required): At least one page was extracted in degraded qualitypagesProcessed(integer, required): Pages extracted so farpagesTotal(integer, required): Pages of the filestatus(ExtractionStatus, required): (one ofNONE,PENDING,PROCESSING,DONE,PARTIAL,SKIPPED,FAILED)eInvoice(string): Detected e-invoice format (one ofXRECHNUNG_CII,XRECHNUNG_UBL,ZUGFERD)error(string): Error message of a failed extractionerrorCode(string): Error code of a FAILED or SKIPPED extractionupdatedAt(string (date-time)): Time of the last state change
fileName(string, required): File name of the current versionfileSize(integer (int64), required): Size of the current versionid(string (uuid), required): Document idisArchived(boolean, required): Same asisLockedisEncrypted(boolean, required): Content is client-side encryptedisLocked(boolean, required): WORM lock (same asisArchived)isPortalVisible(boolean, required): Visible in the customer portallegalHold(boolean, required): A legal hold blocks deletion regardless of retentionmimeType(string, required): MIME type of the current versionretentionYears(integer, required): Retention period in years (from the document type)s3Bucket(string, required): Storage bucket of the current versions3Key(string, required): Storage key of the current versions3Path(string, required): Same ass3KeyscanStatus(ScanStatus, required): Malware scan of the version (one ofPENDING,CLEAN,INFECTED,SKIPPED,FAILED)sha256Hash(string, required): Same ashashSha256(empty when unknown)sizeBytes(integer (int64), required): Size of the current version (same asfileSize)tenantName(string, required): Tenant nametitle(string, required): Defaults to the file nameupdatedAt(string (date-time), required): Time of the last changeuploadedBy(string, required): Who uploaded the documentversion(integer, required): Current version number (same ascurrentVersion)category(string): Document type codeclassificationStatus(string): Document classifier: type taken over automatically, proposal waiting for review, or chosen by a person; omitted when never classified (one ofclassified,needs_review,confirmed)deletedAt(string (date-time)): Time of the soft deleteencryptionAlgorithm(string): Only for encrypted documentsfolderId(string (uuid)): Folder the document is filed in; omitted when it has nonefolderPath(array of FolderRef): The folder and its ancestors, top level first (detail only)id(string (uuid), required): Folder idname(string, required): Folder name
hashSha256(string): SHA-256 (hex) of the current versionlinks(array of DocumentLink): Omitted when the document has nonecreatedAt(string (date-time), required): Creation timecreatedBy(string, required): Who created the linkcustomerNo(string, required): Customer number of the tenantdocumentId(string (uuid), required): The linked documentid(string (uuid), required): Link idrelationType(string, required): Kind of relation, a free code (default ATTACHMENT)targetId(string, required): Id of the linked recordtargetModule(string, required): Module of the linked recordtargetType(string, required): Type of the linked record (see TargetType)tenantName(string, required): Tenant name
lockRetentionUntil(string (date-time)): End of the WORM lockmetadata(object): Free metadata (JSON object)retentionUntil(string (date-time)): End of the retention period; deletion is refused beforesource(string): How the document entered the DMS (one ofupload,mail,internal,api)versions(array of DocumentVersion): Only in the detail and after a version uploadcreatedAt(string (date-time), required): Upload timecreatedBy(string, required): Who uploaded the versioncustomerNo(string, required): Customer number of the tenantdocumentId(string (uuid), required): The document of the versionfileName(string, required): File name of the versionfileSize(integer (int64), required): Size in bytesid(string (uuid), required): Version idmimeType(string, required): MIME type of the versions3Path(string, required): Storage key of the versionscanStatus(ScanStatus, required): Malware scan of the version (one ofPENDING,CLEAN,INFECTED,SKIPPED,FAILED)sha256Hash(string, required): SHA-256 (hex) of the versiontenantName(string, required): Tenant nameversionNumber(integer, required): Version number, from 1changeSummary(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"}'