Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/hotosm/tasking-manager/llms.txt

Use this file to discover all available pages before exploring further.

The Notifications API surfaces in-app messages delivered to a user’s inbox. Messages are created by system events (task validations, invalidations, project broadcasts, team invitations, and more) and can also be sent directly by project managers or team managers. All endpoints require an authenticated session — each user can only read and manage their own messages.

​
Notification Resources

​
List Notifications


GET /api/v2/notifications/ Returns a paginated list of messages for the authenticated user. Supports filtering by message type, sender, project, task, and read status, as well as configurable sort order. Authentication: Required Query Parameters
​
messageType
string
Filter by message type integer. Accepted values:
ValueType
1System
2Broadcast
3Mention
4Validation
5Invalidation
6Request team
7Invitation
8Task comment
9Project chat
10Project Activity
11Team broadcast
​
from
string
Filter messages sent from a specific username.
​
project
string
Filter messages associated with a specific project (by project ID or name).
​
taskId
integer
Filter messages associated with a specific task ID.
​
status
string
Filter by read status. Accepted values: read or unread.
​
sortBy
string
default:"date"
Field to sort results by. Options: date, read, project_id, message_type.
​
sortDirection
string
default:"desc"
Sort direction: asc or desc.
​
page
integer
default:"1"
Page number.
​
pageSize
integer
default:"10"
Number of results per page.
Response 200 OK 
{
  "userMessages": [
    {
      "messageId": 1021,
      "subject": "Task 47 was validated",
      "message": "Your mapping of task 47 in project 312 has been validated. Great work!",
      "fromUserId": 88,
      "fromUsername": "validator_jane",
      "displayPictureUrl": "https://example.com/avatar.jpg",
      "projectId": 312,
      "projectTitle": "West Africa Flood Response",
      "taskId": 47,
      "messageType": "Validation",
      "sentDate": "2024-03-12T14:22:00Z",
      "read": false
    }
  ],
  "pagination": {
    "page": 1,
    "perPage": 10,
    "total": 34,
    "pages": 4
  }
}

curl -X GET "https://tasking-manager-api.example.com/api/v2/notifications/?status=unread&sortBy=date&sortDirection=desc" \
  -H "Authorization: Token YOUR_SESSION_TOKEN"

​
Get a Single Notification


GET /api/v2/notifications/{message_id}/ Retrieves a single message by its ID. The message must belong to the authenticated user. Authentication: Required Path Parameters
​
message_id
integer
required
The unique numeric message ID.
Response 200 OK 
{
  "messageId": 1021,
  "subject": "Task 47 was validated",
  "message": "Your mapping of task 47 in project 312 has been validated. Great work!",
  "fromUserId": 88,
  "fromUsername": "validator_jane",
  "displayPictureUrl": "https://example.com/avatar.jpg",
  "projectId": 312,
  "projectTitle": "West Africa Flood Response",
  "taskId": 47,
  "messageType": "Validation",
  "sentDate": "2024-03-12T14:22:00Z",
  "read": false
}
Error Responses
StatusMeaning
403Message does not belong to the authenticated user
404Message not found

​
Delete a Notification


DELETE /api/v2/notifications/{message_id}/ Permanently deletes a single message. The message must belong to the authenticated user. Authentication: Required Path Parameters
​
message_id
integer
required
The unique numeric message ID.
Response 200 OK 
{ "Success": "Message deleted" }
Error Responses
StatusMeaning
403Message does not belong to the authenticated user
404Message not found

​
Notification Actions

​
Count Unread Notifications


GET /api/v2/notifications/queries/own/count-unread/ Returns the number of unread messages for the authenticated user since their last notification check. This is the lightweight endpoint intended for polling notification badges in the UI. Authentication: Required Response 200 OK 
{ "newMessages": 5 }

​
Update Notification Timestamp


POST /api/v2/notifications/queries/own/post-unread/ Updates the notification checkpoint datetime for the authenticated user, effectively resetting the unread counter baseline. Call this endpoint after the user opens their notification inbox. Authentication: Required Response 200 OK — returns the updated notification record.

​
Bulk Delete Notifications


DELETE /api/v2/notifications/delete-multiple/ Deletes a specified set of messages for the authenticated user in a single transactional operation. Only messages owned by the requesting user are deleted. Authentication: Required Request Body
​
messageIds
array
required
Array of integer message IDs to delete.
{ "messageIds": [1021, 1022, 1045] }
Response 200 OK 
{ "Success": "Messages deleted" }
If messageIds is empty the request succeeds immediately without modifying any data.

​
Delete All Notifications


DELETE /api/v2/notifications/delete-all/ Deletes all messages for the authenticated user. An optional messageType filter can be supplied to delete only messages of a specific type. Authentication: Required Query Parameters
​
messageType
string
Optional message-type integer. When supplied, only messages of that type are deleted. Omit to delete all messages.
Response 200 OK 
{ "Success": "Messages deleted" }

​
Mark All Notifications as Read


POST /api/v2/notifications/mark-as-read-all/ Marks all messages for the authenticated user as read. An optional messageType filter limits the operation to a specific message type. Authentication: Required Query Parameters
​
messageType
string
Optional message-type integer. When supplied, only messages of that type are marked as read.
Response 200 OK 
{ "Success": "Messages marked as read" }

​
Mark Multiple Notifications as Read


POST /api/v2/notifications/mark-as-read-multiple/ Marks a specific set of messages as read for the authenticated user. Authentication: Required Request Body
​
messageIds
array
required
Array of integer message IDs to mark as read.
{ "messageIds": [1021, 1022, 1045] }
Response 200 OK 
{ "Success": "Messages marked as read" }

​
Data Models

​
messageId
integer
Unique numeric identifier for the message.
​
subject
string
Subject line of the notification.
​
message
string
Full body text of the notification.
​
fromUserId
integer
User ID of the sender.
​
fromUsername
string
Username of the sender.
​
displayPictureUrl
string
Avatar URL of the sender.
​
projectId
integer
ID of the related project, if applicable.
​
projectTitle
string
Title of the related project, if applicable.
​
taskId
integer
ID of the related task, if applicable.
​
messageType
string
Human-readable message type label (e.g. Validation, Broadcast, Invitation).
​
sentDate
string
ISO 8601 timestamp indicating when the message was sent.
​
read
boolean
Whether the authenticated user has read the message.
Poll GET /api/v2/notifications/queries/own/count-unread/ at a low frequency (e.g. every 30–60 seconds) to drive notification badges. Use POST /api/v2/notifications/queries/own/post-unread/ when the user opens the inbox to reset the unread count baseline.

Build docs developers (and LLMs) love

Get started for freeTalk to us