Notifications API

Managing user notifications

Notifications API

Endpoints for managing user notifications, including approval requests, approval status updates, and other system notifications.

Base URL: https://ycwadelaide.adenmgb.com

Authentication: All endpoints require Authorization: Bearer <token> header.

Overview

The notifications system provides real-time updates about:

  • Approval Requests - When content is submitted for approval
  • Approval Approved - When content is approved and published
  • Approval Rejected - When content is rejected with optional reason
  • System Notifications - Other important system events

GET /api/staff/notifications

Retrieve notifications for the authenticated user.

Headers:

Authorization: Bearer <token>

Query Parameters:

  • unreadOnly (optional) - If true, returns only unread notifications. Default: false

Request Examples:

GET /api/staff/notifications
GET /api/staff/notifications?unreadOnly=true

Success Response (200 OK):

[
  {
    "id": 1,
    "type": "approval_request",
    "title": "Approval Request: Action",
    "message": "John Doe requested approval for \"SOL Music Events\"",
    "contentType": "actions",
    "contentId": 5,
    "read": false,
    "createdAt": "2024-12-15T10:30:00.000Z",
    "readAt": null
  },
  {
    "id": 2,
    "type": "approval_approved",
    "title": "Approval Approved: News Article",
    "message": "\"New Event Announcement\" has been approved by Jane Smith",
    "contentType": "news",
    "contentId": 12,
    "read": true,
    "createdAt": "2024-12-14T14:20:00.000Z",
    "readAt": "2024-12-14T15:00:00.000Z"
  },
  {
    "id": 3,
    "type": "approval_rejected",
    "title": "Approval Rejected: Event",
    "message": "\"Summer Festival\" has been rejected. Reason: Needs more details about location",
    "contentType": "events",
    "contentId": 8,
    "read": false,
    "createdAt": "2024-12-13T09:15:00.000Z",
    "readAt": null
  }
]

Response Fields:

  • id - Notification ID
  • type - Notification type: "approval_request", "approval_approved", "approval_rejected"
  • title - Notification title
  • message - Notification message with details
  • contentType - Type of content: "actions", "events", "news", "newsletters"
  • contentId - ID of the content item
  • read - Boolean indicating if notification has been read
  • createdAt - ISO 8601 timestamp when notification was created
  • readAt - ISO 8601 timestamp when notification was marked as read (null if unread)

Error Responses:

  • 401 Unauthorized - Not authenticated
  • 500 Internal Server Error - Database error

Notes:

  • Results are ordered by createdAt DESC (newest first)
  • Use unreadOnly=true to get only unread notifications for badge counts
  • Notifications are automatically created by the system

POST /api/staff/notifications/:id/read

Mark a notification as read.

Headers:

Authorization: Bearer <token>

URL Parameters:

  • id - Notification ID

Success Response (200 OK):

{
  "success": true
}

What Happens:

  • read is set to true
  • readAt is set to current timestamp

POST /api/staff/notifications/read-all

Mark all notifications as read.

Headers:

Authorization: Bearer <token>

Success Response (200 OK):

{
  "success": true,
  "marked": 5
}

Response Fields:

  • marked - Number of notifications marked as read

DELETE /api/staff/notifications/:id

Delete a notification.

Headers:

Authorization: Bearer <token>

URL Parameters:

  • id - Notification ID

Success Response (200 OK):

{
  "success": true
}

Notes:

  • This action cannot be undone
  • Consider implementing a confirmation dialog

Notification Types

approval_request

Sent to approvers when content is submitted for approval.

Example:

{
  "type": "approval_request",
  "title": "Approval Request: Action",
  "message": "John Doe requested approval for \"SOL Music Events\"",
  "contentType": "actions",
  "contentId": 5
}

approval_approved

Sent to content creator when their content is approved.

Example:

{
  "type": "approval_approved",
  "title": "Approval Approved: News Article",
  "message": "\"New Event Announcement\" has been approved by Jane Smith",
  "contentType": "news",
  "contentId": 12
}

approval_rejected

Sent to content creator when their content is rejected.

Example:

{
  "type": "approval_rejected",
  "title": "Approval Rejected: Event",
  "message": "\"Summer Festival\" has been rejected. Reason: Needs more details about location",
  "contentType": "events",
  "contentId": 8
}

Usage Examples

Get Unread Count:

const response = await fetch('/api/staff/notifications?unreadOnly=true', {
  headers: { 'Authorization': `Bearer ${token}` }
})
const notifications = await response.json()
const unreadCount = notifications.length

Mark Notification as Read:

await fetch(`/api/staff/notifications/${notificationId}/read`, {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${token}` }
})

Mark All as Read:

await fetch('/api/staff/notifications/read-all', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${token}` }
})

Related APIs

Edit this page
Approval APIs
Request, approve, and reject content for publication
Email APIs
Newsletters, compose emails, templates, and subscribers