Files & Upload API

Upload files, manage stored files, and search across all resources. File uploads support linking to submissions, include server-side security validation, and persist file binaries in the database-backed stored file layer.

Endpoints

List Files

Returns all uploaded files for your workspace.

GET /api/files?search=passport&type=documents

Query Parameters

Response

{
  "files": [
    {
      "id": "cm_attachment_abc123",
      "filename": "passport-scan.pdf",
      "fileUrl": "/api/documents/5f9d6c13e2_mi2f6b_4sB...pdf",
      "fileSize": 245760,
      "mimeType": "application/pdf",
      "createdAt": "2026-02-13T09:30:00.000Z",
      "submission": {
        "id": "SUB-8XQ2M7K9P1ZT",
        "formTitle": "Client Onboarding",
        "user": {
          "id": "cm_user_123",
          "name": "Jane Smith"
        }
      }
    }
  ],
  "stats": {
    "totalFiles": 56,
    "totalSize": 9830400,
    "fileTypes": {
      "pdf": 20,
      "png": 11
    }
  }
}

Upload via Files Workspace

Uploads a standalone file and links it to the system File Uploads submission.

POST /api/files
Content-Type: multipart/form-data

------boundary
Content-Disposition: form-data; name="file"; filename="company-logo.png"
Content-Type: image/png

<binary data>
------boundary--

Response

{
  "success": true,
  "file": {
    "id": "cm_attachment_def456",
    "filename": "company-logo.png",
    "fileUrl": "/api/documents/5f9d6c13e2_mi2f70_EJd...png",
    "fileSize": 82944,
    "mimeType": "image/png"
  }
}

Browse Files

Returns files for your workspace with extraction status, quality scores, and entity link information. Supports filtering by entity, folder, and special views.

GET /api/files/browse?search=passport&entityId=cm_row_rec1&entityType=ROW

Query Parameters

Response

Each file includes optional extraction and quality fields. The extraction object shows the document extraction pipeline status (PENDING, PROCESSING, COMPLETED, FAILED, or TIMED_OUT) and completion timestamp. The quality object includes a structureScore (0-1) and a passed boolean. Both fields are null when not yet available.

{
  "files": [
    {
      "id": "cm_file_abc123",
      "filename": "passport-scan.pdf",
      "fileUrl": "/api/documents/5f9d6c13e2_mi2f6b_4sB...pdf",
      "fileSize": 245760,
      "mimeType": "application/pdf",
      "starred": false,
      "folderId": null,
      "createdAt": "2026-02-13T09:30:00.000Z",
      "extraction": {
        "status": "COMPLETED",
        "completedAt": "2026-02-13T09:31:12.000Z"
      },
      "quality": {
        "structureScore": 0.92,
        "passed": true
      },
      "links": [
        {
          "entityId": "cm_row_rec1",
          "entityType": "ROW",
          "tableId": "cm_table_456"
        }
      ]
    }
  ],
  "total": 56
}

Browse Folder Structure

Returns a smart folder structure for the file browser sidebar. Files are grouped into sections by linked entity type (e.g. Individuals, Matters), with counts per entity. Also returns totals for the Recent, Starred, and Unlinked virtual folders.

GET /api/files/browse/structure

Response

{
  "sections": [
    {
      "key": "clients",
      "label": "Individuals",
      "icon": "Users",
      "totalFiles": 12,
      "entities": [
        {
          "id": "cm_row_rec1",
          "name": "Acme Corp",
          "count": 4,
          "tableId": "cm_table_456"
        }
      ]
    }
  ],
  "recent": 8,
  "starred": 3,
  "unlinked": 5
}

Toggle Star

Toggles the starred status of a file. Starred files appear in the Starred virtual folder in the file browser.

PUT /api/files/:fileId/star

Response

{
  "success": true,
  "starred": true
}

Create Folder

Creates a new folder for organising files.

POST /api/files/folders
Content-Type: application/json

{
  "name": "Client Documents"
}

Body Parameters

Response

{
  "id": "cm_folder_abc123",
  "name": "Client Documents",
  "organizationId": "cm_org_123",
  "createdAt": "2026-03-01T10:00:00.000Z"
}

Rename Folder

Renames an existing folder.

PUT /api/files/folders
Content-Type: application/json

{
  "id": "cm_folder_abc123",
  "name": "Renamed Folder"
}

Body Parameters

Delete Folder

Deletes a folder. Files inside the folder are moved to the root level (not deleted).

DELETE /api/files/folders
Content-Type: application/json

{
  "id": "cm_folder_abc123"
}

Body Parameters

Move File to Folder

Moves a file into a folder, or back to the root level by passing null as the folder ID.

PUT /api/files/:fileId/move
Content-Type: application/json

{
  "folderId": "cm_folder_abc123"
}

Body Parameters

Response

{
  "success": true,
  "file": {
    "id": "cm_file_abc123",
    "folderId": "cm_folder_abc123"
  }
}

Upload a File

Uploads a file using multipart/form-data encoding. Files can optionally be linked to a submission by passing submissionId.

POST /api/upload
Content-Type: multipart/form-data

------boundary
Content-Disposition: form-data; name="file"; filename="passport-scan.pdf"
Content-Type: application/pdf

<binary data>
------boundary
Content-Disposition: form-data; name="submissionId"

SUB-8XQ2M7K9P1ZT
------boundary--

Body Parameters

Response

{
  "success": true,
  "file": {
    "key": "5f9d6c13e2_mi2f6b_4sB...pdf",
    "filename": "passport-scan.pdf",
    "size": 245760,
    "mimeType": "application/pdf",
    "url": "/api/documents/5f9d6c13e2_mi2f6b_4sB...pdf",
    "attachmentId": "cm_attachment_abc123"
  }
}

Upload Security

• Max file size: 10MB by default (configurable by the workspace administrator).
• MIME type validation: Dangerous executable/script MIME types are blocked (for example PE binaries, shell scripts, HTML, and JavaScript MIME types).
• Content inspection: Server-side validation ensures that the file's actual content matches its declared MIME type. Files masquerading as images (e.g. SVG with image/png header) are rejected.
• Content-Disposition: Markup-like MIME types such as image/svg+xml are forced to download via Content-Disposition: attachment.
• Security token: File uploads require authentication.

Blocked MIME Types

Global Search

Searches across all resource types in your workspace. Results are grouped by type: forms, submissions, tables, matters, boards, documents, records, workflows, and navigation pages.

GET /api/search?q=onboarding

Query Parameters

Response

{
  "results": {
    "forms": [
      {
        "id": "cm_form_123",
        "title": "Client Onboarding",
        "description": "Collect client details for onboarding",
        "status": "PUBLISHED"
      }
    ],
    "submissions": [
      {
        "id": "SUB-8XQ2M7K9P1ZT",
        "formTitle": "Client Onboarding",
        "status": "PENDING",
        "createdAt": "2026-02-12T09:15:00.000Z"
      }
    ],
    "tables": [
      {
        "id": "cm_table_456",
        "name": "Individuals",
        "category": "SYSTEM"
      }
    ],
    "matters": [
      {
        "id": "cm_matter_789",
        "number": "MAT-0012",
        "title": "Acme Corp Onboarding",
        "status": "IN_PROGRESS",
        "priority": "HIGH",
        "boardName": "Client Onboarding"
      }
    ],
    "boards": [
      {
        "id": "cm_template_abc",
        "title": "Client Onboarding",
        "status": "ACTIVE"
      }
    ],
    "documents": [
      {
        "id": "cm_row_doc1",
        "title": "Onboarding Checklist",
        "tableName": "Documents"
      }
    ],
    "records": [
      {
        "id": "cm_row_rec1",
        "title": "Acme Corp",
        "tableName": "Companies"
      }
    ],
    "pages": [
      {
        "id": "page-matters",
        "title": "Matters",
        "url": "/matters"
      }
    ],
    "workflows": []
  },
  "query": "onboarding",
  "totalResults": 8,
  "durationMs": 12
}

Search Result Groups

Entity File Intelligence

Deep file aggregation endpoints for CSP entities and individuals. These endpoints traverse company rows, linked matters, and stakeholder relationships to provide a complete file picture for a given entity.

Entity Files (Company)

Deep file aggregation for a CSP entity (company). Returns files from direct company row links, all linked matters, and all stakeholders with roles in the entity.

GET /api/csp/entities/:entityId/files

Path Parameters

Response

{
  "entityId": "cm_row_ent1",
  "entityName": "Acme Holdings Ltd",
  "direct": [
    {
      "id": "cm_file_abc123",
      "filename": "certificate-of-incorporation.pdf",
      "fileSize": 245760,
      "mimeType": "application/pdf",
      "createdAt": "2026-01-15T10:00:00.000Z"
    }
  ],
  "fromMatters": [
    {
      "matterId": "cm_matter_789",
      "matterTitle": "Acme Holdings - Annual Return 2026",
      "files": [
        {
          "id": "cm_file_def456",
          "filename": "annual-return-draft.pdf",
          "fileSize": 184320,
          "mimeType": "application/pdf",
          "createdAt": "2026-02-20T14:30:00.000Z"
        }
      ]
    }
  ],
  "fromStakeholders": [
    {
      "individualId": "cm_row_ind1",
      "name": "John Smith",
      "files": [
        {
          "id": "cm_file_ghi789",
          "filename": "passport-scan.pdf",
          "fileSize": 102400,
          "mimeType": "application/pdf",
          "createdAt": "2026-01-10T09:00:00.000Z"
        }
      ]
    }
  ],
  "totalFiles": 3
}

Individual Files

Deep file aggregation for a CSP individual. Returns files from direct stakeholder row links, linked matters, and bridged KYC documents.

GET /api/csp/individuals/:individualId/files

Path Parameters

Response

{
  "individualId": "cm_row_ind1",
  "individualName": "John Smith",
  "direct": [
    {
      "id": "cm_file_ghi789",
      "filename": "passport-scan.pdf",
      "fileSize": 102400,
      "mimeType": "application/pdf",
      "createdAt": "2026-01-10T09:00:00.000Z"
    }
  ],
  "fromMatters": [
    {
      "matterId": "cm_matter_789",
      "matterTitle": "Acme Holdings - Annual Return 2026",
      "files": [
        {
          "id": "cm_file_jkl012",
          "filename": "director-resolution.pdf",
          "fileSize": 76800,
          "mimeType": "application/pdf",
          "createdAt": "2026-02-22T11:00:00.000Z"
        }
      ]
    }
  ],
  "totalFiles": 2
}

Stakeholder File Timeline

Chronological view of every document associated with a stakeholder across all entities and matters.

GET /api/stakeholders/:id/files

Path Parameters

Query Parameters

Response

{
  "stakeholderId": "cm_row_ind1",
  "entries": [
    {
      "file": {
        "id": "cm_file_ghi789",
        "filename": "passport-scan.pdf",
        "fileSize": 102400,
        "mimeType": "application/pdf"
      },
      "source": "ROW",
      "sourceLabel": "Stakeholders - John Smith",
      "date": "2026-01-10T09:00:00.000Z"
    },
    {
      "file": {
        "id": "cm_file_jkl012",
        "filename": "director-resolution.pdf",
        "fileSize": 76800,
        "mimeType": "application/pdf"
      },
      "source": "MATTER",
      "sourceLabel": "Acme Holdings - Annual Return 2026",
      "date": "2026-02-22T11:00:00.000Z"
    }
  ],
  "totalEntries": 2
}