ConnectCloud Developers

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 page
    • 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)
      • 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)
      • 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
  • total (integer, required): Documents of the whole filter
  • nextCursor (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"

View as Markdown · Interactive reference · OpenAPI