List documents (tenant:dms:read)
GET /api/dms/v1/documents
Module: DMS · operationId: listDocuments · Tag: Documents · Auth: access token (Authorization: Bearer <accessToken>)
Newest first; with search ranked by relevance. search (alias q) combines a German
full-text search over title, file name and extracted text with substring matches on title,
file name and document number. Every document carries its links. Deleted documents are not
listed. Pages by cursor: pass nextCursor as cursor (with the same filter and sort) until it is missing;
total counts the whole filter.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
search |
query | string | Search text | |
q |
query | string | Alias of search (used when search is empty) |
|
category |
query | string | Document type code (case-insensitive) | |
source |
query | string | (one of upload, mail, internal, api) |
|
isLocked |
query | boolean | Only locked (true) or unlocked (false) documents |
|
targetType |
query | TargetType | Only documents linked to a record of this type; STANDALONE = documents without any link (one of CUSTOMER, SUPPLIER, DISTRIBUTOR, ADDRESS, ARTICLE, TRANSACTION, INVOICE, CONTRACT, EMPLOYEE, TRAVEL_REPORT, TICKET, WORK_ITEM, FORGE_ITEM, LEAD, OPPORTUNITY, CAMPAIGN, PROJECT, ASSET, STANDALONE) |
|
targetId |
query | string | With targetType: only documents linked to this record (max length 128) |
|
folderId |
query | string | Only documents in this folder; none = documents without a folder |
|
includeSubfolders |
query | boolean | With a folderId: also the documents of its subfolders (default false) |
|
containerId |
query | string (uuid) | Only the documents of this container | |
sort |
query | string | Order (- = descending); default newest first, with search by relevance (one of createdAt, -createdAt, title, -title, documentNumber, -documentNumber) |
|
limit |
query | integer | Page size; another value than 1–100 is a 400 invalid (field: limit) (default 50; max 100) |
|
cursor |
query | string | nextCursor of the previous page (opaque); a cursor of another sort or an altered one is a 400 invalid (field: cursor) |
Responses
- 200 A page of documents (
application/json) - 400 Error (
application/json)
Fields of the 200 answer:
items(array of Document, required): Documents of the pageconfidentialLevel(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)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
total(integer, required): Documents of the whole filternextCursor(string): Cursor of the next page; missing on the last page
Example 200 answer:
{
"items": [
{
"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
}
],
"nextCursor": "eyJjIjoiMjAyNi0wOS0zMFQwODo0MDoxMloiLCJpZCI6IjNmNmMyYTFlIn0",
"total": 128
}
Example request
curl -X GET 'https://api.mbcom.cloud/api/dms/v1/documents' \
-H "Authorization: Bearer $ACCESS_TOKEN"