Notifications API

Manage in-app notifications. Notifications are created by system events (pipeline syncs, matter updates, form submissions, @mentions in comments) and can be managed via these endpoints. Users @mentioned in matter comments always receive a notification regardless of their preference settings.

Endpoints

List Notifications

Returns notifications for the authenticated user. Supports filtering by read status and pagination.

GET /api/notifications?unreadOnly=true&page=1&limit=20

Query Parameters

Response

{
  "notifications": [
    {
      "id": "cm_notif_abc123",
      "type": "PIPELINE_SYNC",
      "title": "Pipeline sync completed",
      "message": "Companies pipeline synced 42 records successfully.",
      "read": false,
      "createdAt": "2026-02-13T14:30:00.000Z"
    },
    {
      "id": "cm_notif_def456",
      "type": "MATTER_UPDATE",
      "title": "Matter step completed",
      "message": "Step \"Client Onboarding Form\" in MAT-0012 was completed.",
      "read": true,
      "createdAt": "2026-02-13T10:15:00.000Z"
    },
    {
      "id": "cm_notif_ghi789",
      "type": "FORM_SUBMISSION",
      "title": "New submission received",
      "message": "Jane Smith submitted \"KYC Intake Form\".",
      "read": false,
      "createdAt": "2026-02-12T16:45:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 47,
    "pages": 3
  }
}

Create a Notification

Creates a notification for a specific user. Typically used internally by system events, but can be called directly for custom notifications.

POST /api/notifications
Content-Type: application/json

{
  "type": "GENERAL",
  "title": "Reminder: Review pending submissions",
  "message": "You have 5 submissions awaiting review.",
  "userId": "cm_user_123"
}

Body Parameters

Mark as Read

Marks a single notification as read. Only the notification owner can mark their own notifications.

PATCH /api/notifications/:id
Content-Type: application/json

{
  "read": true
}

Path Parameters

Response

{
  "success": true,
  "notification": {
    "id": "cm_notif_abc123",
    "read": true
  }
}

Mark All Read

Marks all unread notifications for the authenticated user as read in a single operation. Returns the count of notifications updated.

POST /api/notifications/mark-all-read

Response

{
  "success": true,
  "updatedCount": 12
}

Delete a Notification

Permanently deletes a notification. Only the notification owner can delete their own notifications.

DELETE /api/notifications/:id

Notification Types

Notification Categories & Preferences

Users can configure which notification categories they receive in Settings > Notifications. Categories are grouped into three sections with independent toggles.

Access notifications are sent directly to affected users (e.g. the invited/removed member and org admins), bypassing the follower model used by matter notifications. @mentioned users and direct assignees always receive notifications regardless of preference settings.