# Notifications

In-app notifications (transaction alerts, security events, marketing) are served from a separate host. Notifications are fetched in pages and can be bulk-marked as read.

The polling service runs in the background and posts an Android system notification for each unseen item (`service/NotificationPollingService.kt:64`).

---

## Base URL

```
https://app.bankofmaldives.com.mv/api/v2
```

Distinct from the main `internetbanking/api/mobile` host, but uses the same Bearer token.

---

## Prerequisites

- Valid `access_token` from [OAuth Token Exchange](03-oauth-token.md)

---

## Fetch Notifications

```
GET https://app.bankofmaldives.com.mv/api/v2/notifications?group={group}&page={page}
```

### Query Parameters

| Parameter | Type | Description |
|---|---|---|
| `group` | `string` | Filter by group — `ALL` (default), or a specific group (e.g. `ALERTS`) |
| `page` | `int` | 1-based page number |

### Headers

| Header | Value |
|---|---|
| `Authorization` | `Bearer <access_token>` |
| `User-Agent` | `bml-mobile-banking/348 ({manufacturer}; Android {version}; {model})` |
| `x-app-version` | `2.1.44.348` |

```bash
curl --request GET \
  --url 'https://app.bankofmaldives.com.mv/api/v2/notifications?group=ALL&page=1' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'User-Agent: bml-mobile-banking/348 ({manufacturer}; Android {version}; {model})' \
  --header 'x-app-version: 2.1.44.348'
```

### Response

```json
{
  "success": true,
  "total": 137,
  "payload": [
    {
      "id": "abc123",
      "group": "ALERTS",
      "type": "TRANSACTION",
      "title": "Transaction Alert",
      "message": "MVR 100.00 debited from 7730000000001",
      "created_at": "2026-05-16T15:10:25",
      "is_read": false,
      "data": {
        "account_number": "7730000000001",
        "amount": "100.00",
        "currency": "MVR",
        "reference": "FT20260516123456"
      }
    }
  ]
}
```

### Top-level Fields

| Field | Type | Description |
|---|---|---|
| `success` | `bool` | `true` on success |
| `total` | `int` | Total notification count across all pages |
| `payload` | `array` | List of notifications for this page |

### Notification Object

| Field | Type | Description |
|---|---|---|
| `id` | `string` | Unique notification ID |
| `group` | `string` | Logical grouping (e.g. `ALERTS`) — also the value passed back to the `group` filter |
| `type` | `string` | Sub-type within the group (e.g. `TRANSACTION`) |
| `title` | `string` | Short headline |
| `message` | `string` | Body text |
| `created_at` | `string` | Timestamp — `yyyy-MM-dd'T'HH:mm:ss` (no timezone) |
| `is_read` | `bool` | Read state |
| `data` | `object?` | Optional structured detail payload — fields vary by type |

### `data` Field Flattening

Where present, the `data` object is flattened into the notification's detail view as key-value rows. The client transforms each `data` key with underscore → space and title-case (`BmlNotificationsClient.kt:93-94`):

```
"account_number" → "Account Number"
"reference"      → "Reference"
```

Three synthetic rows are prepended:

| Row | Value |
|---|---|
| `Bank` | `BML` |
| `Group` | from `group` field |
| `Type` | from `type` field |

---

## Mark All Read

```
PUT https://app.bankofmaldives.com.mv/api/v2/notifications/read
```

### Headers

| Header | Value |
|---|---|
| `Authorization` | `Bearer <access_token>` |
| `User-Agent` | `bml-mobile-banking/348 ({manufacturer}; Android {version}; {model})` |
| `x-app-version` | `2.1.44.348` |
| `accept` | `application/json` |
| `Content-Type` | `application/json` |

### Request Body

```json
{
  "all": true
}
```

```bash
curl --request PUT \
  --url 'https://app.bankofmaldives.com.mv/api/v2/notifications/read' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'User-Agent: bml-mobile-banking/348 ({manufacturer}; Android {version}; {model})' \
  --header 'x-app-version: 2.1.44.348' \
  --header 'accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"all":true}'
```

### Response

The client treats any 2xx response as success — the response body is discarded.

---

## Polling

`service/NotificationPollingService.kt:64` polls page 1 of every active BML session at a fixed interval, diffs the result against a local cache, and posts an Android system notification for each new item.

---

&nbsp;

---

[← QR Payment](13-qr-payment.md) &nbsp;&nbsp;&nbsp; **Next →** [Card Freeze](15-card-freeze.md)