Skip to main content

​
Overview

Notifications inform users about important events, updates, and activities within the platform. Each notification can be linked to a related entity and tracks read/unread status.

​
Create Notification

curl -X POST http://localhost:8080/api/notifications \
  -H "Content-Type: application/json" \
  -d '{
    "userId": 10,
    "type": "BOOKING_CONFIRMED",
    "title": "Booking Confirmed",
    "body": "Your tour booking for Barcelona City Tour has been confirmed.",
    "relatedEntityType": "TripBooking",
    "relatedEntityId": 42,
    "isRead": false,
    "createdAt": "2026-03-11T14:30:00",
    "readAt": null
  }'
Create a new notification for a user.

​
Request Body

​
userId
integer
required
The ID of the user who will receive this notification
​
type
string
required
The notification type (e.g., BOOKING_CONFIRMED, MESSAGE_RECEIVED, REVIEW_POSTED)
​
title
string
required
The notification title
​
body
string
required
The notification message body
​
relatedEntityType
string
The type of entity this notification relates to (e.g., TripBooking, ChatMessage, Review)
​
relatedEntityId
integer
The ID of the related entity
​
isRead
boolean
Whether the notification has been read. Defaults to false.
​
createdAt
string
Timestamp when the notification was created in ISO 8601 format (e.g., 2026-03-11T14:30:00)
​
readAt
string
Timestamp when the notification was read in ISO 8601 format. Null if unread.

​
Response

​
notificationId
integer
Unique identifier for the notification
​
userId
integer
The user ID who received this notification
​
type
string
The notification type
​
title
string
The notification title
​
body
string
The notification message body
​
relatedEntityType
string
The type of related entity
​
relatedEntityId
integer
The ID of the related entity
​
isRead
boolean
Whether the notification has been read
​
createdAt
string
Notification creation timestamp
​
readAt
string
Timestamp when notification was read (null if unread)
{
  "notificationId": 789,
  "userId": 10,
  "type": "BOOKING_CONFIRMED",
  "title": "Booking Confirmed",
  "body": "Your tour booking for Barcelona City Tour has been confirmed.",
  "relatedEntityType": "TripBooking",
  "relatedEntityId": 42,
  "isRead": false,
  "createdAt": "2026-03-11T14:30:00",
  "readAt": null
}

​
Get All Notifications

curl -X GET http://localhost:8080/api/notifications \
  -H "Content-Type: application/json"
Retrieve a list of all notifications in the system.

​
Response

Returns an array of notification objects. 
[
  {
    "notificationId": 789,
    "userId": 10,
    "type": "BOOKING_CONFIRMED",
    "title": "Booking Confirmed",
    "body": "Your tour booking for Barcelona City Tour has been confirmed.",
    "relatedEntityType": "TripBooking",
    "relatedEntityId": 42,
    "isRead": true,
    "createdAt": "2026-03-11T14:30:00",
    "readAt": "2026-03-11T15:00:00"
  },
  {
    "notificationId": 790,
    "userId": 10,
    "type": "MESSAGE_RECEIVED",
    "title": "New Message",
    "body": "You have a new message from your guide.",
    "relatedEntityType": "ChatMessage",
    "relatedEntityId": 123,
    "isRead": false,
    "createdAt": "2026-03-11T16:20:00",
    "readAt": null
  }
]

​
Get Notification by ID

curl -X GET http://localhost:8080/api/notifications/789 \
  -H "Content-Type: application/json"
Retrieve a specific notification by its ID.

​
Path Parameters

​
id
integer
required
The unique identifier of the notification

​
Response

{
  "notificationId": 789,
  "userId": 10,
  "type": "BOOKING_CONFIRMED",
  "title": "Booking Confirmed",
  "body": "Your tour booking for Barcelona City Tour has been confirmed.",
  "relatedEntityType": "TripBooking",
  "relatedEntityId": 42,
  "isRead": true,
  "createdAt": "2026-03-11T14:30:00",
  "readAt": "2026-03-11T15:00:00"
}

​
Update Notification

curl -X PUT http://localhost:8080/api/notifications/789 \
  -H "Content-Type: application/json" \
  -d '{
    "userId": 10,
    "type": "BOOKING_CONFIRMED",
    "title": "Booking Confirmed",
    "body": "Your tour booking for Barcelona City Tour has been confirmed.",
    "relatedEntityType": "TripBooking",
    "relatedEntityId": 42,
    "isRead": true,
    "createdAt": "2026-03-11T14:30:00",
    "readAt": "2026-03-11T15:00:00"
  }'
Update an existing notification. Commonly used to mark notifications as read.

​
Path Parameters

​
id
integer
required
The unique identifier of the notification to update

​
Request Body

​
userId
integer
The ID of the user who received this notification
​
type
string
The notification type
​
title
string
The notification title
​
body
string
The notification message body
​
relatedEntityType
string
The type of entity this notification relates to
​
relatedEntityId
integer
The ID of the related entity
​
isRead
boolean
Whether the notification has been read. Set to true to mark as read.
​
createdAt
string
Notification creation timestamp in ISO 8601 format
​
readAt
string
Timestamp when the notification was read. Set this along with isRead: true to mark as read.

​
Response

{
  "notificationId": 789,
  "userId": 10,
  "type": "BOOKING_CONFIRMED",
  "title": "Booking Confirmed",
  "body": "Your tour booking for Barcelona City Tour has been confirmed.",
  "relatedEntityType": "TripBooking",
  "relatedEntityId": 42,
  "isRead": true,
  "createdAt": "2026-03-11T14:30:00",
  "readAt": "2026-03-11T15:00:00"
}

​
Delete Notification

curl -X DELETE http://localhost:8080/api/notifications/789 \
  -H "Content-Type: application/json"
Permanently delete a notification.

​
Path Parameters

​
id
integer
required
The unique identifier of the notification to delete

​
Response

Returns a success status code (typically 204 No Content) if the deletion was successful.

​
Notification Types

Common notification types include:
  • BOOKING_CONFIRMED: Trip booking has been confirmed
  • BOOKING_CANCELLED: Trip booking has been cancelled
  • MESSAGE_RECEIVED: New chat message received
  • REVIEW_POSTED: New review posted on a tour or guide
  • PAYMENT_RECEIVED: Payment has been processed
  • TOUR_REMINDER: Upcoming tour reminder
  • PROFILE_UPDATE: Profile information updated

​
Read Status

Notifications track their read status in two ways:
  1. isRead boolean flag: Quick check if notification has been read
  2. readAt timestamp: Exact time when notification was marked as read
To mark a notification as read, update both fields:
  • Set isRead to true
  • Set readAt to the current timestamp
Notifications can be linked to various entity types:
  • TripBooking: Booking-related notifications
  • ChatMessage: Message notifications
  • Review: Review-related notifications
  • User: User profile notifications
  • Tour: Tour-related notifications
Use relatedEntityType and relatedEntityId to associate notifications with specific entities, enabling users to navigate directly to the relevant content.

Build docs developers (and LLMs) love

Get started for freeTalk to us