Set or extend the WORM lock of a document (tenant:dms:write)
POST /api/dms/v1/documents/{id}/lock
Module: DMS · operationId: lockDocument · Tag: Compliance · Auth: access token (Authorization: Bearer <accessToken>)
Locks the document until retentionUntil (a date means the end of that day, UTC). An
existing lock and the retention period are only ever extended: an earlier date keeps the
later one. The date must be in the future.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id |
path | string (uuid) | yes |
Request body
application/json (required)
retentionUntil(string, required): A date (YYYY-MM-DD, end of that day UTC) or an RFC 3339 timestamp; must be in the future
Example:
{
"retentionUntil": "2036-12-31"
}
Responses
- 200 The locked document (
application/json) - 400 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 POST 'https://api.mbcom.cloud/api/dms/v1/documents/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/lock' \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
--data '{"retentionUntil":"2036-12-31"}'