Upload a document (tenant:dms:write)
POST /api/dms/v1/documents/upload
Module: DMS · operationId: uploadDocument · Tag: Documents · Auth: access token (Authorization: Bearer <accessToken>)
Stores one file (file part) with its metadata. Put all form fields before the file part.
A document type is required: category (an active type code) or documentRole. The SHA-256
of the content is checked first: if the tenant already has the same unencrypted file, the
existing document is returned with 200 and duplicate: true (links requested in the
upload are added to it). The MIME type is detected from the part's Content-Type, the file
name and the content. Extractable formats are queued for text extraction unless
extractText=false; with a malware scanner the new version starts as scanStatus: PENDING.
Size limit: 25 MB per file by default (configurable by the operator); 413 beyond.
Request body
multipart/form-data (required)
file(string (binary), required): The file (exactly one)category(string): Active document type code (required unlessdocumentRoleis given)confidentialLevel(ConfidentialLevel): (one ofPUBLIC,INTERNAL,CONFIDENTIAL,STRICTLY_CONFIDENTIAL; default"INTERNAL")documentRole(string): Files the document under the type assigned to the role when nocategoryis given (one ofincoming_original,incoming_supplement)encryption(string): JSONEncryptionInput; the file part is then the ciphertextextractText(boolean):trueforces,falsedisables text extraction; by default every extractable format is queuedfolderId(string): Files the new document in this folder (400when unknown,403when read-only);none= no folder; omitted = the default folder of the document type (if the caller may write there). A duplicate keeps its folder.isEncrypted(boolean): Marks a client-encrypted upload; requiresencryptionisLocked(boolean): Lock the document (WORM) on uploadisPortalVisible(boolean): Visible in the customer portal (defaultfalse)links(string): JSON array ofLinkInput(at most 50 links per upload, together withtargetType)lockRetentionDays(integer): WithisLocked, lock for this many days from nowmetadata(string): JSON objectmimeType(string): Plaintext MIME type of an encrypted uploadrelationType(string): WithtargetTypesource(string): How the document entered the DMS (one ofupload,mail,internal,api; default"upload")targetId(string): WithtargetType, the record to linktargetModule(string): WithtargetTypetargetType(TargetType): Type of the linked record (case-insensitive);STANDALONE= no link (one ofCUSTOMER,SUPPLIER,DISTRIBUTOR,ADDRESS,ARTICLE,TRANSACTION,INVOICE,CONTRACT,EMPLOYEE,TRAVEL_REPORT,TICKET,WORK_ITEM,FORGE_ITEM,LEAD,OPPORTUNITY,CAMPAIGN,PROJECT,ASSET,STANDALONE)title(string): Defaults to the file name
Responses
- 200 The file already existed; the existing document is returned (
application/json) - 201 Stored (
application/json) - 400 Error (
application/json) - 413 Error (
application/json) - 415 Error (
application/json) - 503 Error (
application/json)
Fields of the 201 answer:
document(Document, required)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)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
duplicate(boolean, required): The tenant already had a document with the same content; it is returned instead
Example 201 answer:
{
"document": {
"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
},
"duplicate": false
}
Example request
curl -X POST 'https://api.mbcom.cloud/api/dms/v1/documents/upload' \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H 'Content-Type: multipart/form-data' \
-F 'file=@document.pdf'