Sharh

Ramadan Last 10 Nights Campaign

Used by thousands of students worldwide - help us reach 150 members

... / 150 members...
APINotifications

Notifications

/notifications

Push notification device registration and the in-app notification inbox (list, unread count, mark as read) for the authenticated user.

POSTRegister a push notification device tokenDELETEUnregister a push notification device tokenGETList the current user's notificationsGETGet the number of unread notificationsPUTMark a notification as readPUTMark all notifications as read
POST/notifications/device-token

Register a push notification device token

Auth required

Registers a device push token for the authenticated user. The operation is an upsert keyed on the user and token: registering the same token again updates its platform and re-activates it.

Body parameters

tokenrequired
string
The device push token (for example the APNs device token).
platform
string
Device platform: `ios` or `android`.Default: ios

Errors

  • 400JSON `{ "message": "Token is required" }`.
  • 401Plain text `Unauthorized: No token provided`.
  • 403Plain text `Forbidden: Invalid token`, or `Forbidden: You do not have the required permissions`.
  • 500JSON `{ "message": "Error registering device token", "error": "..." }`.
Request
curl -X POST "https://app.ummahspot.com/notifications/device-token" \
  -H "Authorization: Bearer $SHARH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"token":"string"}'
Response · 200
{
  "message": "Device token registered"
}
DELETE/notifications/device-token

Unregister a push notification device token

Auth required

Marks the given device token as inactive for the authenticated user so it no longer receives push notifications (typically called on logout). The token is read from the JSON request body. The call succeeds even if the token was not registered for this user.

Body parameters

tokenrequired
string
The device push token to deactivate.

Errors

  • 400JSON `{ "message": "Token is required" }`.
  • 401Plain text `Unauthorized: No token provided`.
  • 403Plain text `Forbidden: Invalid token`, or `Forbidden: You do not have the required permissions`.
  • 500JSON `{ "message": "Error unregistering device token", "error": "..." }`.
Request
curl -X DELETE "https://app.ummahspot.com/notifications/device-token" \
  -H "Authorization: Bearer $SHARH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"token":"string"}'
Response · 200
{
  "message": "Device token unregistered"
}
GET/notifications

List the current user's notifications

Auth required

Returns the authenticated user's notifications, newest first, with page-based pagination. `actor` is the user who triggered the notification, populated with `username`, `profilePicture` and `profilePictureKey`; it is `null` for system notifications such as `admin_message` and `announcement`. `type` is one of `comment_on_post`, `reply_to_comment`, `like_on_post`, `like_on_comment`, `new_post`, `admin_message`, `announcement`. `post` and `comment` hold the related ObjectIds when applicable.

Query parameters

page
number
1-based page number.Default: 1
limit
number
Notifications per page.Default: 20

Errors

  • 401Plain text `Unauthorized: No token provided`.
  • 403Plain text `Forbidden: Invalid token`, or `Forbidden: You do not have the required permissions`.
  • 500JSON `{ "message": "Error fetching notifications", "error": "..." }`.
Request
curl -X GET "https://app.ummahspot.com/notifications" \
  -H "Authorization: Bearer $SHARH_TOKEN"
Response · 200
{
  "notifications": [
    {
      "_id": "66a1b2c3d4e5f60012345678",
      "recipient": "665f1c2e9b1d4a0012ab34cd",
      "actor": {
        "_id": "665f1c2e9b1d4a0012ab99ef",
        "username": "alghazali",
        "profilePicture": "https://lh3.googleusercontent.com/a/..."
      },
      "type": "comment_on_post",
      "title": "New Comment",
      "body": "alghazali commented on your post",
      "post": "66a1a0009b1d4a0012ab1111",
      "comment": "66a1b2009b1d4a0012ab2222",
      "isRead": false,
      "readAt": null,
      "createdAt": "2026-09-18T10:15:00.000Z",
      "updatedAt": "2026-09-18T10:15:00.000Z",
      "__v": 0
    }
  ],
  "currentPage": 1,
  "totalPages": 3,
  "total": 42
}
GET/notifications/unread-count

Get the number of unread notifications

Auth required

Returns how many of the authenticated user's notifications have not been marked as read.

Errors

  • 401Plain text `Unauthorized: No token provided`.
  • 403Plain text `Forbidden: Invalid token`, or `Forbidden: You do not have the required permissions`.
  • 500JSON `{ "message": "Error fetching unread count", "error": "..." }`.
Request
curl -X GET "https://app.ummahspot.com/notifications/unread-count" \
  -H "Authorization: Bearer $SHARH_TOKEN"
Response · 200
{
  "unreadCount": 5
}
PUT/notifications/:id/read

Mark a notification as read

Auth required

Marks one notification as read and sets its `readAt` timestamp. Only notifications whose recipient is the authenticated user can be updated; anyone else's notification id yields 404. Returns the updated notification (`actor` is an unpopulated ObjectId here).

Path parameters

id
string
Notification ObjectId

Errors

  • 401Plain text `Unauthorized: No token provided`.
  • 403Plain text `Forbidden: Invalid token`, or `Forbidden: You do not have the required permissions`.
  • 404JSON `{ "message": "Notification not found" }` when the notification does not exist or belongs to another user.
  • 500JSON `{ "message": "Error marking notification as read", "error": "..." }` (also returned for a malformed ObjectId).
Request
curl -X PUT "https://app.ummahspot.com/notifications/:id/read" \
  -H "Authorization: Bearer $SHARH_TOKEN"
Response · 200
{
  "notification": {
    "_id": "66a1b2c3d4e5f60012345678",
    "recipient": "665f1c2e9b1d4a0012ab34cd",
    "actor": "665f1c2e9b1d4a0012ab99ef",
    "type": "comment_on_post",
    "title": "New Comment",
    "body": "alghazali commented on your post",
    "post": "66a1a0009b1d4a0012ab1111",
    "comment": "66a1b2009b1d4a0012ab2222",
    "isRead": true,
    "readAt": "2026-09-18T10:20:31.000Z",
    "createdAt": "2026-09-18T10:15:00.000Z",
    "updatedAt": "2026-09-18T10:20:31.000Z",
    "__v": 0
  }
}
PUT/notifications/read-all

Mark all notifications as read

Auth required

Marks every unread notification of the authenticated user as read and sets their `readAt` timestamp.

Errors

  • 401Plain text `Unauthorized: No token provided`.
  • 403Plain text `Forbidden: Invalid token`, or `Forbidden: You do not have the required permissions`.
  • 500JSON `{ "message": "Error marking all as read", "error": "..." }`.
Request
curl -X PUT "https://app.ummahspot.com/notifications/read-all" \
  -H "Authorization: Bearer $SHARH_TOKEN"
Response · 200
{
  "message": "All notifications marked as read"
}