Skip to main content
Nyota Imara delivers in-app notifications for key account events — logins, team invites, KYB status changes, and more. Use the notifications API to build a notification bell in your interface, track unread counts, and let users acknowledge alerts.

​
Fetch notifications

Retrieve the most recent 50 notifications for the authenticated user alongside an unread count for your notification badge: 
curl https://api.nyotaimara.com/v1/notifications \
  -H "Authorization: Bearer <your_token>"
Response: 
{
  "success": true,
  "data": {
    "notifications": [
      {
        "id": "notif_01jb9xyz",
        "title": "You've been invited to join Savanna Supplies Ltd",
        "message": "Click here to join the team: https://accounts.nyotaimara.com/invites/accept?token=...",
        "type": "team_invite",
        "isRead": false,
        "createdAt": "2025-11-04T09:30:00.000Z",
        "actionUrl": "https://accounts.nyotaimara.com/invites/accept?token=..."
      },
      {
        "id": "notif_01jb8abc",
        "title": "New login to your account",
        "message": "A new login was detected from Nairobi, Kenya.",
        "type": "login_event",
        "isRead": true,
        "createdAt": "2025-11-03T14:12:00.000Z",
        "actionUrl": null
      }
    ],
    "unreadCount": 3
  }
}

​
Notification fields

FieldTypeDescription
idstringUnique notification ID
titlestringShort heading for the notification
messagestringFull notification text
typestringEvent category (see triggers below)
isReadbooleanfalse if the user has not acknowledged it
createdAtstringISO 8601 timestamp
actionUrlstring | nullDeep link the user can follow for the relevant action

​
Mark a notification as read

Mark a single notification as read using its id: 
curl -X PATCH https://api.nyotaimara.com/v1/notifications/notif_01jb9xyz/read \
  -H "Authorization: Bearer <your_token>"
Response: 
{
  "success": true
}

​
Mark all notifications as read

Clear all unread notifications in a single call — useful for a “mark all as read” button in your UI: 
curl -X PATCH https://api.nyotaimara.com/v1/notifications/read-all \
  -H "Authorization: Bearer <your_token>"
Response: 
{
  "success": true
}

​
What triggers a notification

Notifications are generated automatically by platform events. The table below lists the most common triggers:
Eventtype valueDescription
New loginlogin_eventSent when a new session is opened for your account
Team invite receivedteam_inviteSent when another user invites you to their organization
KYB submissionkyb_submissionSent when your business verification is submitted
KYB approved / rejectedkyb_statusSent when your KYB review is complete
The notifications API returns personal context data — notifications belong to the authenticated user, not to an organization. No X-Organization-Id header is required.

​
Endpoint reference

MethodEndpointDescription
GET/v1/notificationsFetch last 50 notifications + unread count
PATCH/v1/notifications/:id/readMark one notification as read
PATCH/v1/notifications/read-allMark all notifications as read