## 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:

```json
{
  "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:

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

```bash
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"}'
```
