> ## Documentation Index
> Fetch the complete documentation index at: https://handbook.nyotaimara.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Notifications: Fetch, Read, and Track In-App Alerts

> Retrieve your last 50 notifications with unread counts, mark individual items or all notifications as read, and learn what events trigger them.

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:

```bash theme={null}
curl https://api.nyotaimara.com/v1/notifications \
  -H "Authorization: Bearer <your_token>"
```

**Response:**

```json theme={null}
{
  "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

| Field       | Type           | Description                                           |
| ----------- | -------------- | ----------------------------------------------------- |
| `id`        | string         | Unique notification ID                                |
| `title`     | string         | Short heading for the notification                    |
| `message`   | string         | Full notification text                                |
| `type`      | string         | Event category (see triggers below)                   |
| `isRead`    | boolean        | `false` if the user has not acknowledged it           |
| `createdAt` | string         | ISO 8601 timestamp                                    |
| `actionUrl` | string \| null | Deep link the user can follow for the relevant action |

***

## Mark a notification as read

Mark a single notification as read using its `id`:

```bash theme={null}
curl -X PATCH https://api.nyotaimara.com/v1/notifications/notif_01jb9xyz/read \
  -H "Authorization: Bearer <your_token>"
```

**Response:**

```json theme={null}
{
  "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:

```bash theme={null}
curl -X PATCH https://api.nyotaimara.com/v1/notifications/read-all \
  -H "Authorization: Bearer <your_token>"
```

**Response:**

```json theme={null}
{
  "success": true
}
```

***

## What triggers a notification

Notifications are generated automatically by platform events. The table below lists the most common triggers:

| Event                   | `type` value     | Description                                              |
| ----------------------- | ---------------- | -------------------------------------------------------- |
| New login               | `login_event`    | Sent when a new session is opened for your account       |
| Team invite received    | `team_invite`    | Sent when another user invites you to their organization |
| KYB submission          | `kyb_submission` | Sent when your business verification is submitted        |
| KYB approved / rejected | `kyb_status`     | Sent when your KYB review is complete                    |

<Info>
  The notifications API returns personal context data — notifications belong to the authenticated user, not to an organization. No `X-Organization-Id` header is required.
</Info>

***

## Endpoint reference

| Method  | Endpoint                     | Description                                |
| ------- | ---------------------------- | ------------------------------------------ |
| `GET`   | `/v1/notifications`          | Fetch last 50 notifications + unread count |
| `PATCH` | `/v1/notifications/:id/read` | Mark one notification as read              |
| `PATCH` | `/v1/notifications/read-all` | Mark all notifications as read             |