API Reference: Notifications

Overview

Notifications are per-user alerts inside Simply360 — the feed that powers the in-app notification center. Each notification belongs to one user in one team and records what happened (a new conversation, a new message, an assignment, a mention, a system event, or a workflow-generated alert), when it happened, and whether the user has read it.

The Notifications API lets a client render that feed: list and filter the current user's notifications, poll the unread count, mark items read (individually or all at once), delete items, manage per-device notification preferences, and register or deregister mobile push tokens (APNs / FCM).

Authentication and Tier

All ten notification operations are standard tier, but they are user-scoped: they act on the notification feed of the authenticated user, so they require first-party user credentials — a Cognito user session (webapp or mobile sign-in) or a first-party OAuth user access token — with a selected team context.

Team API keys (s360_live_...) and session tokens (s360_sess_...) are not accepted on this surface; they return 403 COGNITO_REQUIRED because an API key does not represent a specific user with a notification feed. The examples below use $S360_ACCESS_TOKEN as a placeholder for a first-party user access token. See Authentication for the full credential model.

• 403 COGNITO_REQUIRED — the caller is not a first-party user (for example, an API key).
• 400 VALIDATION_ERROR — no team context is selected.
• 403 PERMISSION_DENIED — the user is not an active member of the selected team.

Endpoints

Method	Path	Tier	Purpose
GET	/v1/notifications	standard	List the current user's notifications for the selected team.
GET	/v1/notifications/unread-count	standard	Get the current user's unread notification count.
GET	/v1/notifications/{notificationSimplyId}	standard	Get a single notification.
PUT	/v1/notifications/{notificationSimplyId}/read	standard	Mark one notification read.
PUT	/v1/notifications/read-all	standard	Mark all of the user's team notifications read.
DELETE	/v1/notifications/{notificationSimplyId}	standard	Delete a notification.
GET	/v1/notifications/preferences	standard	Get per-category notification preferences for one device.
PUT	/v1/notifications/preferences	standard	Update per-category notification preferences for one device.
POST	/v1/notifications/device-token	standard	Register a push notification token for the current mobile device.
DELETE	/v1/notifications/device-token	standard	Deregister a push notification token.

The Notification Object

Field	Type	Description
simplyId	string	Public notification ID.
notificationType	string	Event type, e.g. NEW_CONVERSATION, NEW_MESSAGE, ASSIGNMENT, MENTION, SYSTEM, TEAM_GENERATED.
title	object | null	Localized title (language code → string).
body	object | null	Localized body text (language code → string).
iconType	string | null	Icon hint for rendering.
actionUrl	string | null	In-app destination to open when the notification is tapped or clicked.
referenceEntityType	string | null	Type of the related entity, when the notification points at one.
referenceEntityId	string | null	Identifier of the related entity.
isRead	boolean	Whether the user has read the notification.
readAt	string | null	ISO 8601 timestamp of when it was marked read.
createdAt / updatedAt	string	ISO 8601 timestamps.

List Notifications

Returns the user's notifications for the selected team, newest first.

TypeScript SDK

const result = await s360.notifications.list({ isRead: false, limit: 25 });

for (const notification of result.data.notifications) {
  console.log(`${notification.createdAt}: ${notification.notificationType}`);
}

cURL

curl -s "https://api.simply360.app/v1/notifications?isRead=false&limit=25" \
  -H "Authorization: Bearer $S360_ACCESS_TOKEN"

Query Parameters

Parameter	Type	Description
limit	integer	Page size. Default 50, maximum 100.
offset	integer	Skip count for pagination. Default 0.
isRead	boolean	Filter to read (true) or unread (false) notifications.
notificationType	string	Filter to a single notification type.
installationId	string	Optional mobile installation ID. When provided, notification categories the user disabled on that device are excluded from the results.

Unread Count

A lightweight endpoint designed for badge counters. Pass installationId to respect that device's category preferences.

const { data } = await s360.notifications.getUnreadCount();
console.log(`Unread: ${data.unreadCount}`);

curl -s "https://api.simply360.app/v1/notifications/unread-count" \
  -H "Authorization: Bearer $S360_ACCESS_TOKEN"

{
  "data": {
    "unreadCount": 4
  }
}

Get a Notification

const notification = await s360.notifications.get('NTFC-1234-ABCD');
console.log(notification.data.actionUrl);

curl -s "https://api.simply360.app/v1/notifications/NTFC-1234-ABCD" \
  -H "Authorization: Bearer $S360_ACCESS_TOKEN"

Mark Read

Mark a single notification read, or mark everything read at once. Read-state changes are also published to the platform's realtime channel, so other signed-in surfaces (webapp, mobile) update their badges immediately.

await s360.notifications.markAsRead('NTFC-1234-ABCD');

// Mark all of the user's team notifications read
const all = await s360.notifications.markAllAsRead();

curl -s -X PUT "https://api.simply360.app/v1/notifications/NTFC-1234-ABCD/read" \
  -H "Authorization: Bearer $S360_ACCESS_TOKEN"

curl -s -X PUT "https://api.simply360.app/v1/notifications/read-all" \
  -H "Authorization: Bearer $S360_ACCESS_TOKEN"

read-all accepts an optional JSON body with installationId; when provided, categories the user disabled on that device are left untouched. The response includes updatedCount, the number of notifications transitioned to read.

Delete a Notification

await s360.notifications.delete('NTFC-1234-ABCD');

curl -s -X DELETE "https://api.simply360.app/v1/notifications/NTFC-1234-ABCD" \
  -H "Authorization: Bearer $S360_ACCESS_TOKEN"

Notification Preferences

Preferences are stored per team user per mobile device and control six categories, all of which default to enabled:

Preference Key	Covers
newConversation	New conversation notifications.
newMessage	New message notifications.
assignment	Record and task assignment notifications.
mention	@-mention notifications.
system	System events, including report snapshots, approval requests, and background-task completion, failure, and partial-success notifications.
workflow	Team-generated (workflow) notifications.

Both preference endpoints identify the device with exactly one of installationId (the mobile app installation ID) or deviceSimplyId (the public mobile device ID). Providing both, or neither, returns 400 INVALID_DEVICE. The device must already be registered for the current user, otherwise the API returns 404 DEVICE_NOT_FOUND.

const prefs = await s360.notifications.getPreferences({ installationId: 'ios-install-01' });

await s360.notifications.updatePreferences({
  installationId: 'ios-install-01',
  newMessage: false,
  system: true,
});

curl -s "https://api.simply360.app/v1/notifications/preferences?installationId=ios-install-01" \
  -H "Authorization: Bearer $S360_ACCESS_TOKEN"

curl -s -X PUT "https://api.simply360.app/v1/notifications/preferences" \
  -H "Authorization: Bearer $S360_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "installationId": "ios-install-01",
    "newMessage": false,
    "system": true
  }'

Both endpoints return the full six-key preference object after applying any updates. The update body is strict: only the device identifier and the six boolean keys are accepted.

Device Tokens (Mobile Push)

Mobile clients register an APNs (iOS) or FCM (Android) push token so the platform can deliver push notifications to that installation. Registration associates the token with the current team user and mobile app installation; the installation must already be a registered mobile device for the user.

const registration = await s360.notifications.registerDeviceToken(
  'abcdef0123456789...', // APNs or FCM token
  'ios',
  'ios-install-01',
);

// Later, e.g. on sign-out:
await s360.notifications.deregisterDeviceToken('abcdef0123456789...');

curl -s -X POST "https://api.simply360.app/v1/notifications/device-token" \
  -H "Authorization: Bearer $S360_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "abcdef0123456789...",
    "platform": "ios",
    "installationId": "ios-install-01"
  }'

• Registering a brand-new token returns 201 with { "deviceTokenSimplyId": "...", "created": true }.
• Re-registering an existing token refreshes it and returns 200 with { "deviceTokenSimplyId": "...", "refreshed": true }. Registration is idempotent by token, so it is safe to call on every app launch.
• DELETE /v1/notifications/device-token takes { "token": "..." } and deactivates the token, returning { "deactivated": true }; an unknown token returns 404 TOKEN_NOT_FOUND.

Integration Patterns

• Badge polling — Poll GET /v1/notifications/unread-count on an interval (or on app foreground) to drive an unread badge; it is much cheaper than listing.
• Inbox rendering — List with isRead=false for the unread tab and no filter for the full history; page with limit/offset.
• Read on open — Call the per-notification read endpoint when the user opens an item, and follow its actionUrl to deep-link into the app.
• Device hygiene — Register the push token on every launch (idempotent) and deregister it on sign-out so a shared device stops receiving the previous user's pushes.

Usage Notes

• Notifications are created by the platform (conversation activity, assignments, mentions, system and workflow events); this API is read-and-manage only — there is no endpoint to create notifications directly.
• All reads and writes are scoped to the authenticated user in the selected team. Users can never see or modify another user's notifications.
• When notificationType is combined with an installationId whose preferences disable that category, the list returns an empty result rather than an error.
• Deleting is a soft delete from the user's feed; deleted notifications no longer appear in lists or counts.
• For conversation-centric integrations, see API Reference: Conversations and API Reference: Messages. For server-to-server event delivery, use Webhooks instead of polling notifications.