Notification API

Send, list, and manage notifications with per-user read tracking via a readBy[] array.

Endpoints

Method	Path	Description
POST	/api/notifications/:orgId/trigger	Trigger a system notification
POST	/api/notifications/cleanup	Clean up expired notifications
GET	/api/notifications/:orgId/config	Get notification configuration
PUT	/api/notifications/:orgId/config	Update notification configuration
GET	/api/notifications/:orgId/unread-count	Get unread count for the current user
GET	/api/notifications/:orgId/readers/:notificationId	Get read-by list for a notification
GET	/api/notifications/:orgId	List notifications (paginated)
POST	/api/notifications/:orgId	Create a notification
PATCH	/api/notifications/:orgId/read-all	Mark all notifications as read
PATCH	/api/notifications/:orgId/:notificationId/read	Mark a single notification as read
DELETE	/api/notifications/:orgId/:notificationId	Delete a notification

Path Parameters

Parameter	Type	Description
orgId	string	Organization ID
notificationId	string	Notification ID

Query Parameters

Endpoint	Parameter	Type	Default	Description
List	page	number	1	Page number
List	limit	number	20	Items per page
List	type	string	—	Filter by notification type

---

Trigger Notification

POST /api/notifications/:orgId/trigger

Triggers a system-generated notification (e.g. new booking, payment received).

Request Body

{
  "type": "booking_created",
  "title": "New Booking Created",
  "message": "Booking BKG-587 has been created for Room 101",
  "referenceId": "665f6a7b8c9d0e1f2a3b4c5d",
  "referenceType": "booking",
  "recipients": ["665c3d4e5f6a7b8c9d0e1f2a", "665c3d4e5f6a7b8c9d0e1f2b"]
}

Response — 201 Created

{
  "success": true,
  "message": "Notification triggered successfully",
  "data": {
    "_id": "66601a2b3c4d5e6f7a8b9c0d",
    "type": "booking_created",
    "title": "New Booking Created",
    "message": "Booking BKG-587 has been created for Room 101",
    "referenceId": "665f6a7b8c9d0e1f2a3b4c5d",
    "referenceType": "booking",
    "recipients": ["665c3d4e5f6a7b8c9d0e1f2a", "665c3d4e5f6a7b8c9d0e1f2b"],
    "readBy": [],
    "orgId": "663f1a2b3c4d5e6f7a8b9c0d",
    "createdAt": "2026-02-23T10:30:00.000Z"
  }
}

---

Cleanup Notifications

POST /api/notifications/cleanup

Removes notifications older than the configured retention period.

Response — 200 OK

{
  "success": true,
  "message": "Cleanup completed",
  "data": {
    "deletedCount": 142
  }
}

---

Get Notification Config

GET /api/notifications/:orgId/config

Response — 200 OK

{
  "success": true,
  "data": {
    "emailEnabled": true,
    "pushEnabled": false,
    "retentionDays": 90,
    "enabledTypes": [
      "booking_created",
      "booking_updated",
      "booking_cancelled",
      "payment_received",
      "invoice_generated",
      "guest_checked_in",
      "guest_checked_out"
    ]
  }
}

---

Update Notification Config

PUT /api/notifications/:orgId/config

Request Body

{
  "emailEnabled": true,
  "pushEnabled": true,
  "retentionDays": 60,
  "enabledTypes": [
    "booking_created",
    "booking_cancelled",
    "payment_received",
    "invoice_generated"
  ]
}

Response — 200 OK

{
  "success": true,
  "message": "Notification config updated successfully",
  "data": {
    "emailEnabled": true,
    "pushEnabled": true,
    "retentionDays": 60,
    "enabledTypes": [
      "booking_created",
      "booking_cancelled",
      "payment_received",
      "invoice_generated"
    ]
  }
}

---

Get Unread Count

GET /api/notifications/:orgId/unread-count

Returns the number of unread notifications for the currently authenticated user.

Response — 200 OK

{
  "success": true,
  "data": {
    "unreadCount": 7
  }
}

---

Get Readers

GET /api/notifications/:orgId/readers/:notificationId

Returns the list of users who have read a specific notification.

Response — 200 OK

{
  "success": true,
  "data": {
    "notificationId": "66601a2b3c4d5e6f7a8b9c0d",
    "readBy": [
      {
        "userId": "665c3d4e5f6a7b8c9d0e1f2a",
        "name": "Rahul Sharma",
        "readAt": "2026-02-23T10:35:00.000Z"
      },
      {
        "userId": "665c3d4e5f6a7b8c9d0e1f2b",
        "name": "Priya Patel",
        "readAt": "2026-02-23T10:42:00.000Z"
      }
    ]
  }
}

---

List Notifications (Paginated)

GET /api/notifications/:orgId?page=1&limit=20

Response — 200 OK

{
  "success": true,
  "data": [
    {
      "_id": "66601a2b3c4d5e6f7a8b9c0d",
      "type": "booking_created",
      "title": "New Booking Created",
      "message": "Booking BKG-587 has been created for Room 101",
      "referenceId": "665f6a7b8c9d0e1f2a3b4c5d",
      "referenceType": "booking",
      "readBy": ["665c3d4e5f6a7b8c9d0e1f2a"],
      "isRead": false,
      "createdAt": "2026-02-23T10:30:00.000Z"
    },
    {
      "_id": "66601a2b3c4d5e6f7a8b9c0e",
      "type": "payment_received",
      "title": "Payment Received",
      "message": "Payment of ₹12,500 received for INV-1041",
      "referenceId": "665f6a7b8c9d0e1f2a3b4c5e",
      "referenceType": "payment",
      "readBy": [],
      "isRead": false,
      "createdAt": "2026-02-23T09:15:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "totalPages": 3,
    "totalCount": 47
  }
}

---

Create Notification

POST /api/notifications/:orgId

Request Body

{
  "type": "custom",
  "title": "Maintenance Alert",
  "message": "Scheduled maintenance for elevators on Feb 25, 2026 from 10:00 AM to 2:00 PM",
  "recipients": ["665c3d4e5f6a7b8c9d0e1f2a", "665c3d4e5f6a7b8c9d0e1f2b"]
}

Response — 201 Created

{
  "success": true,
  "message": "Notification created successfully",
  "data": {
    "_id": "66601a2b3c4d5e6f7a8b9c0f",
    "type": "custom",
    "title": "Maintenance Alert",
    "message": "Scheduled maintenance for elevators on Feb 25, 2026 from 10:00 AM to 2:00 PM",
    "recipients": ["665c3d4e5f6a7b8c9d0e1f2a", "665c3d4e5f6a7b8c9d0e1f2b"],
    "readBy": [],
    "orgId": "663f1a2b3c4d5e6f7a8b9c0d",
    "createdAt": "2026-02-23T11:00:00.000Z"
  }
}

---

Mark All as Read

PATCH /api/notifications/:orgId/read-all

Marks all notifications as read for the currently authenticated user by adding their ID to each notification's readBy[] array.

Response — 200 OK

{
  "success": true,
  "message": "All notifications marked as read",
  "data": {
    "modifiedCount": 7
  }
}

---

Mark Single as Read

PATCH /api/notifications/:orgId/:notificationId/read

Response — 200 OK

{
  "success": true,
  "message": "Notification marked as read",
  "data": {
    "_id": "66601a2b3c4d5e6f7a8b9c0d",
    "readBy": [
      {
        "userId": "665c3d4e5f6a7b8c9d0e1f2a",
        "readAt": "2026-02-23T10:35:00.000Z"
      }
    ]
  }
}

---

Delete Notification

DELETE /api/notifications/:orgId/:notificationId

Response — 200 OK

{
  "success": true,
  "message": "Notification deleted successfully"
}