## Create or change a document type (tenant:settings:write)

`PUT /api/dms/v1/document-types/{code}`

Module: DMS · operationId: `upsertDocumentType` · Tag: Document types · Auth: access token (`Authorization: Bearer <accessToken>`)

Without `sortOrder` a new type goes to the end and an existing one keeps its place. Types in
use by the platform (`mail`, `outgoing_invoice` and the types assigned to a role) cannot be deactivated (`422`
on `isActive`).

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `code` | path | string | yes | Document type code (lower-cased by the server) |

### Request body

`application/json` (required)

- `name` (string, required): Display name (max length 128)
- `retentionYears` (integer, required): Retention period in years (max 30)
- `classifierDescription` (string, nullable): Description for the document classifier; `null` or empty clears it, omitted keeps it (max length 1000)
- `defaultFolderId` (string (uuid), nullable): Default folder; `null` clears it, omitted keeps it
- `isActive` (boolean): Only active types can be chosen for uploads (default `true`)
- `sortOrder` (integer): Position in the list
- `targetModule` (string): Target module; omitted keeps it (`none` for a new type) (one of `none`, `trade.invoice`, `trade.delivery_note`, `trade.order_confirmation`, `hr`)

Example:

```json
{
  "isActive": true,
  "name": "Lieferantenvertrag",
  "retentionYears": 10
}
```

### Responses

- **200** The document type (`application/json`)
- **400** Error (`application/json`)

Fields of the 200 answer:

- `code` (string, required): Code of the type, used as `category`
- `createdAt` (string (date-time), required): Creation time
- `isActive` (boolean, required): Only active types can be chosen for uploads
- `name` (string, required): Display name
- `platform` (boolean, required): Used by the platform (`mail`, `outgoing_invoice` or assigned to a role); cannot be deleted or deactivated
- `retentionYears` (integer, required): Retention period of documents of the type in years
- `sortOrder` (integer, required): Position in the list
- `updatedAt` (string (date-time), required): Time of the last change
- `classifierDescription` (string): Tells the document classifier when the type applies; types without one are never chosen (except the type of the Original-Eingangsbeleg) (max length 1000)
- `defaultFolderId` (string (uuid)): Uploads of this type without a folder are filed here
- `role` (string): Role the type is assigned to, if any (one of `incoming_original`, `incoming_supplement`)
- `targetModule` (string): Module that processes classified documents of the type; `none` only files them (one of `none`, `trade.invoice`, `trade.delivery_note`, `trade.order_confirmation`, `hr`)

Example 200 answer:

```json
{
  "classifierDescription": "Eingangsrechnung, Gutschrift oder Rechnungskorrektur eines Lieferanten: Rechnungsnummer, Rechnungsdatum und ein zu zahlender oder zu erstattender Betrag.",
  "code": "incoming_document",
  "createdAt": "2026-01-02T08:00:00Z",
  "defaultFolderId": "3b1f6a2c-7d4e-4f1a-9c2b-8e5d0a1f7b63",
  "isActive": true,
  "name": "Eingangsbeleg",
  "platform": true,
  "retentionYears": 10,
  "role": "incoming_original",
  "sortOrder": 1,
  "targetModule": "trade.invoice",
  "updatedAt": "2026-01-02T08:00:00Z"
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/dms/v1/document-types/supplier_contract' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"isActive":true,"name":"Lieferantenvertrag","retentionYears":10}'
```
