Skip to main content

Notification Management

Author: Grok, AI Assistant
Last Updated: 2025-10-18
Version: v1.0

Base URL: https://api.nextgate.com/api/v1

Short Description: The Notification Management API enables authenticated users to manage their in-app notifications, including retrieving paginated lists of notifications, viewing unread notifications, getting summary counts, marking notifications as read, and deleting them. This API is designed for users to interact with their personal notification data securely and efficiently. It supports operations for individual, batch, and bulk actions on notifications.

Hints:

  • All endpoints require Bearer Token authentication (Authorization: Bearer your_token).
  • Responses use UTC timestamps in ISO 8601 format (e.g., 2025-10-18T11:32:00Z).
  • Rate limiting: 100 requests per minute per user.
  • Pagination is used for list endpoints with default page=1 and size=20.
  • Testing/sandbox information: Use the sandbox environment at https://sandbox.nextgate.com/api/v1 for development.

Standard Response Format

All API responses follow a consistent structure using our Globe Response Builder pattern:

Success Response Structure

{
  "success": true,
  "httpStatus": "OK",
  "message": "Operation completed successfully",
  "action_time": "2025-10-18T11:32:00Z",
  "data": {
    // Actual response data goes here
  }
}

Error Response Structure

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Error description",
  "action_time": "2025-10-18T11:32:00Z",
  "data": "Error description" // or detailed error object
}

Standard Response Fields

Field Type Description
success boolean Always true for successful operations, false for errors
httpStatus string HTTP status name (OK, BAD_REQUEST, NOT_FOUND, etc.)
message string Human-readable message describing the operation result
action_time string ISO 8601 timestamp of when the response was generated
data object/string Response payload for success, error details for failures

HTTP Method Badge Standards

For better visual clarity, all endpoints use colored badges for HTTP methods with the following standard colors:

  • GET - GET - Green (Safe, read-only operations)
  • POST - POST - Blue (Create new resources)
  • PUT - PUT - Yellow (Update/replace entire resource)
  • PATCH - PATCH - Orange (Partial updates)
  • DELETE - DELETE - Red (Remove resources)

Endpoints

1. Get My Notifications

Purpose: Retrieves a paginated list of the authenticated user's in-app notifications.

Endpoint: GET {base_url}/notifications/me

Access Level: 🔒 Protected (Authenticated user only)

Authentication: Bearer Token

Request Headers:

Header Type Required Description
Authorization string Yes Bearer token for authentication (Bearer your_token)

Query Parameters:

Parameter Type Required Description Validation Default
page integer No Page number for pagination Min: 1 1
size integer No Number of items per page Min: 1, Max: 100 20

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Notifications retrieved successfully",
  "action_time": "2025-10-18T11:32:00Z",
  "data": {
    "content": [
      {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "userId": "223e4567-e89b-12d3-a456-426614174001",
        "shopId": "323e4567-e89b-12d3-a456-426614174002",
        "serviceId": "service-123",
        "serviceType": "ORDER",
        "title": "Order Shipped",
        "message": "Your order has been shipped.",
        "type": "INFO",
        "priority": "NORMAL",
        "isRead": false,
        "data": {
          "orderId": "order-456"
        },
        "createdAt": "2025-10-17T10:00:00Z",
        "readAt": null
      }
    ],
    "pageable": {
      "sort": {
        "sorted": true,
        "unsorted": false,
        "empty": false
      },
      "pageNumber": 0,
      "pageSize": 20,
      "offset": 0,
      "paged": true,
      "unpaged": false
    },
    "totalPages": 1,
    "totalElements": 1,
    "last": true,
    "numberOfElements": 1,
    "first": true,
    "size": 20,
    "number": 0,
    "sort": {
      "sorted": true,
      "unsorted": false,
      "empty": false
    },
    "empty": false
  }
}

Success Response Fields:

Field Description
content Array of notifications
content[].id Unique identifier of the notification
content[].userId ID of the user receiving the notification
content[].shopId ID of the associated shop (if applicable)
content[].serviceId ID of the service generating the notification
content[].serviceType Type of service (e.g., ORDER)
content[].title Title of the notification
content[].message Body message of the notification
content[].type Type of notification (e.g., INFO)
content[].priority Priority level (e.g., NORMAL)
content[].isRead Whether the notification has been read
content[].data Additional data as key-value pairs
content[].createdAt Timestamp when notification was created
content[].readAt Timestamp when notification was read (null if unread)
pageable Pagination details
totalPages Total number of pages
totalElements Total number of notifications
last Whether this is the last page
numberOfElements Number of elements in this page
first Whether this is the first page
size Page size
number Current page number
sort Sorting details
empty Whether the page is empty

Error Response JSON Sample:

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Invalid pagination parameters",
  "action_time": "2025-10-18T11:32:00Z",
  "data": "Invalid pagination parameters"
}

Standard Error Types:

  • 400 BAD_REQUEST: Invalid pagination parameters
  • 401 UNAUTHORIZED: Invalid or expired token
  • 404 NOT_FOUND: No notifications found

2. Get Unread Notifications

Purpose: Retrieves a paginated list of the authenticated user's unread in-app notifications.

Endpoint: GET {base_url}/notifications/unread

Access Level: 🔒 Protected (Authenticated user only)

Authentication: Bearer Token

Request Headers:

Header Type Required Description
Authorization string Yes Bearer token for authentication (Bearer your_token)

Query Parameters:

Parameter Type Required Description Validation Default
page integer No Page number for pagination Min: 1 1
size integer No Number of items per page Min: 1, Max: 100 20

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Unread notifications retrieved successfully",
  "action_time": "2025-10-18T11:32:00Z",
  "data": {
    "content": [
      {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "userId": "223e4567-e89b-12d3-a456-426614174001",
        "shopId": "323e4567-e89b-12d3-a456-426614174002",
        "serviceId": "service-123",
        "serviceType": "ORDER",
        "title": "Order Shipped",
        "message": "Your order has been shipped.",
        "type": "INFO",
        "priority": "NORMAL",
        "isRead": false,
        "data": {
          "orderId": "order-456"
        },
        "createdAt": "2025-10-17T10:00:00Z",
        "readAt": null
      }
    ],
    "pageable": {
      "sort": {
        "sorted": true,
        "unsorted": false,
        "empty": false
      },
      "pageNumber": 0,
      "pageSize": 20,
      "offset": 0,
      "paged": true,
      "unpaged": false
    },
    "totalPages": 1,
    "totalElements": 1,
    "last": true,
    "numberOfElements": 1,
    "first": true,
    "size": 20,
    "number": 0,
    "sort": {
      "sorted": true,
      "unsorted": false,
      "empty": false
    },
    "empty": false
  }
}

Success Response Fields:

Field Description
content Array of unread notifications (same structure as Get My Notifications)
pageable Pagination details
totalPages Total number of pages
totalElements Total number of unread notifications
last Whether this is the last page
numberOfElements Number of elements in this page
first Whether this is the first page
size Page size
number Current page number
sort Sorting details
empty Whether the page is empty

Error Response JSON Sample:

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Invalid pagination parameters",
  "action_time": "2025-10-18T11:32:00Z",
  "data": "Invalid pagination parameters"
}

Standard Error Types:

  • 400 BAD_REQUEST: Invalid pagination parameters
  • 401 UNAUTHORIZED: Invalid or expired token
  • 404 NOT_FOUND: No unread notifications found

3. Get Notification Summary

Purpose: Retrieves a summary of the authenticated user's notification counts (total, unread, read).

Endpoint: GET {base_url}/notifications/summary

Access Level: 🔒 Protected (Authenticated user only)

Authentication: Bearer Token

Request Headers:

Header Type Required Description
Authorization string Yes Bearer token for authentication (Bearer your_token)

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Notification summary retrieved successfully",
  "action_time": "2025-10-18T11:32:00Z",
  "data": {
    "totalCount": 10,
    "unreadCount": 3,
    "readCount": 7
  }
}

Success Response Fields:

Field Description
totalCount Total number of notifications
unreadCount Number of unread notifications
readCount Number of read notifications

Error Response JSON Sample:

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "User ID cannot be null",
  "action_time": "2025-10-18T11:32:00Z",
  "data": "User ID cannot be null"
}

Standard Error Types:

  • 400 BAD_REQUEST: User ID issues
  • 401 UNAUTHORIZED: Invalid or expired token

4. Mark Notification as Read

Purpose: Marks a specific notification as read for the authenticated user.

Endpoint: PATCH {base_url}/notifications/{notificationId}/read

Access Level: 🔒 Protected (Authenticated user only)

Authentication: Bearer Token

Request Headers:

Header Type Required Description
Authorization string Yes Bearer token for authentication (Bearer your_token)

Path Parameters:

Parameter Type Required Description Validation
notificationId UUID Yes Unique identifier of the notification Valid UUID format

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Notification marked as read",
  "action_time": "2025-10-18T11:32:00Z",
  "data": null
}

Success Response Fields:

Field Description
data Null or optional details

Error Response JSON Sample:

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "Notification not found or access denied",
  "action_time": "2025-10-18T11:32:00Z",
  "data": "Notification not found or access denied"
}

Standard Error Types:

  • 400 BAD_REQUEST: Invalid notification ID
  • 401 UNAUTHORIZED: Invalid or expired token
  • 403 FORBIDDEN: Access denied (not user's notification)
  • 404 NOT_FOUND: Notification not found

5. Batch Mark as Read

Purpose: Marks multiple notifications as read for the authenticated user.

Endpoint: PATCH {base_url}/notifications/batch/read

Access Level: 🔒 Protected (Authenticated user only)

Authentication: Bearer Token

Request Headers:

Header Type Required Description
Authorization string Yes Bearer token for authentication (Bearer your_token)

Request JSON Sample:

{
  "notificationIds": [
    "123e4567-e89b-12d3-a456-426614174000",
    "223e4567-e89b-12d3-a456-426614174001"
  ]
}

Request Body Parameters:

Parameter Type Required Description Validation
notificationIds array Yes List of notification IDs to mark as read Non-empty array of valid UUIDs

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "2 notification(s) marked as read",
  "action_time": "2025-10-18T11:32:00Z",
  "data": null
}

Success Response Fields:

Field Description
data Null or optional details

Error Response JSON Sample:

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Notification IDs cannot be empty",
  "action_time": "2025-10-18T11:32:00Z",
  "data": "Notification IDs cannot be empty"
}

Standard Error Types:

  • 400 BAD_REQUEST: Empty or invalid notification IDs
  • 401 UNAUTHORIZED: Invalid or expired token
  • 403 FORBIDDEN: Access denied for some notifications
  • 404 NOT_FOUND: Some notifications not found

6. Mark All as Read

Purpose: Marks all notifications as read for the authenticated user.

Endpoint: PATCH {base_url}/notifications/read

Access Level: 🔒 Protected (Authenticated user only)

Authentication: Bearer Token

Request Headers:

Header Type Required Description
Authorization string Yes Bearer token for authentication (Bearer your_token)

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "All notifications marked as read",
  "action_time": "2025-10-18T11:32:00Z",
  "data": null
}

Success Response Fields:

Field Description
data Null or optional details

Error Response JSON Sample:

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "User not found",
  "action_time": "2025-10-18T11:32:00Z",
  "data": "User not found"
}

Standard Error Types:

  • 401 UNAUTHORIZED: Invalid or expired token
  • 404 NOT_FOUND: User not found

7. Delete Notification

Purpose: Deletes a specific notification for the authenticated user.

Endpoint: DELETE {base_url}/notifications/{notificationId}

Access Level: 🔒 Protected (Authenticated user only)

Authentication: Bearer Token

Request Headers:

Header Type Required Description
Authorization string Yes Bearer token for authentication (Bearer your_token)

Path Parameters:

Parameter Type Required Description Validation
notificationId UUID Yes Unique identifier of the notification Valid UUID format

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Notification deleted successfully",
  "action_time": "2025-10-18T11:32:00Z",
  "data": null
}

Success Response Fields:

Field Description
data Null or optional details

Error Response JSON Sample:

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "Notification not found or access denied",
  "action_time": "2025-10-18T11:32:00Z",
  "data": "Notification not found or access denied"
}

Standard Error Types:

  • 400 BAD_REQUEST: Invalid notification ID
  • 401 UNAUTHORIZED: Invalid or expired token
  • 403 FORBIDDEN: Access denied
  • 404 NOT_FOUND: Notification not found

8. Batch Delete Notifications

Purpose: Deletes multiple notifications for the authenticated user.

Endpoint: DELETE {base_url}/notifications/batch

Access Level: 🔒 Protected (Authenticated user only)

Authentication: Bearer Token

Request Headers:

Header Type Required Description
Authorization string Yes Bearer token for authentication (Bearer your_token)

Request JSON Sample:

{
  "notificationIds": [
    "123e4567-e89b-12d3-a456-426614174000",
    "223e4567-e89b-12d3-a456-426614174001"
  ]
}

Request Body Parameters:

Parameter Type Required Description Validation
notificationIds array Yes List of notification IDs to delete Non-empty array of valid UUIDs

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "2 notification(s) deleted successfully",
  "action_time": "2025-10-18T11:32:00Z",
  "data": null
}

Success Response Fields:

Field Description
data Null or optional details

Error Response JSON Sample:

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Notification IDs cannot be empty",
  "action_time": "2025-10-18T11:32:00Z",
  "data": "Notification IDs cannot be empty"
}

Standard Error Types:

  • 400 BAD_REQUEST: Empty or invalid notification IDs
  • 401 UNAUTHORIZED: Invalid or expired token
  • 403 FORBIDDEN: Access denied for some notifications
  • 404 NOT_FOUND: Some notifications not found

9. Delete All Read Notifications

Purpose: Deletes all read notifications for the authenticated user.

Endpoint: DELETE {base_url}/notifications/read

Access Level: 🔒 Protected (Authenticated user only)

Authentication: Bearer Token

Request Headers:

Header Type Required Description
Authorization string Yes Bearer token for authentication (Bearer your_token)

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "5 read notification(s) deleted successfully",
  "action_time": "2025-10-18T11:32:00Z",
  "data": 5
}

Success Response Fields:

Field Description
data Number of deleted notifications

Error Response JSON Sample:

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "User ID cannot be null",
  "action_time": "2025-10-18T11:32:00Z",
  "data": "User ID cannot be null"
}

Standard Error Types:

  • 400 BAD_REQUEST: User ID issues
  • 401 UNAUTHORIZED: Invalid or expired token

Quick Reference Guide

HTTP Method Badge Code Templates

GET Badge:

<span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span>

POST Badge:

<span style="background-color: #007bff; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">POST</span>

PATCH Badge:

<span style="background-color: #fd7e14; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">PATCH</span>

DELETE Badge:

<span style="background-color: #dc3545; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">DELETE</span>

Common HTTP Status Codes

  • 200 OK: Successful GET/PUT/PATCH request
  • 201 Created: Successful POST request
  • 204 No Content: Successful DELETE request
  • 400 Bad Request: Invalid request data
  • 401 Unauthorized: Authentication required/failed
  • 403 Forbidden: Insufficient permissions
  • 404 Not Found: Resource not found
  • 422 Unprocessable Entity: Validation errors
  • 429 Too Many Requests: Rate limit exceeded
  • 500 Internal Server Error: Server error

Authentication Types

  • Bearer Token: Include Authorization: Bearer your_token in headers

Data Format Standards

  • Dates: Use ISO 8601 format (2025-10-18T11:32:00Z)
  • IDs: UUID format
  • Pagination: Include page, size, total_count, total_pages
Back to top