Notifications — Ngamia Docs

All endpoints on this page require a JWT. The API exposes the in-app notification feed and channel preferences. Automated OTP, low-balance, payment, and API-key messages are delivered by Ngamia; their full delivery content is not fetched through a separate endpoint.

Choose the operation

Need	Endpoint	Method
List notification records	`/v1/notifications`	`GET`
Mark one record as read	`/v1/notifications/{id}/read`	`PATCH`
Read delivery preferences	`/v1/me/notification-preferences`	`GET`
Update delivery preferences	`/v1/me/notification-preferences`	`PATCH`

List notifications

GET/v1/notificationsJWT

Use limit and offset for pagination:

/v1/notifications?limit=20&offset=0

limit defaults to 20 and is capped at 100 for this endpoint.

[
  {
    "id": "...",
    "type": "low_balance",
    "channel": "email",
    "payload": {
      "subject": "Ngamia - Low Balance Alert",
      "message": "<html>...</html>",
      "is_html": true
    },
    "is_read": false,
    "created_at": "2026-07-14T13:00:00Z"
  }
]

Field	Values or meaning
`type`	Common values include `low_balance`, `payment_confirmed`, `payment_failed`, or `api_key_created`; handle future values defensively.
`channel`	`email`, `sms`, or `in_app`.
`is_read`	Whether the authenticated user has marked the record as read.
`payload`	Free-form JSON describing what was sent.
`created_at`	Creation time in ISO 8601 format.

Treat payload as data, not trusted markup. In particular, do not render payload.message as raw HTML in a notification list. Build the notification bell around type, is_read, and created_at, and sanitize any detail view according to your application’s security policy.

Mark a notification as read

PATCH/v1/notifications/{id}/readJWT

The request has no body. A successful response is 200 with {}. If the notification does not belong to the authenticated account, Ngamia returns 404 not_found.

Manage notification preferences

GET/v1/me/notification-preferencesJWT

{
  "email_enabled": true,
  "sms_enabled": true,
  "payment_notifications": true,
  "usage_alerts": true
}

PATCH/v1/me/notification-preferencesJWT

Each field is an independent optional boolean. Send only what changed:

{ "email_enabled": false }

A new account receives all four fields as true when it first reads preferences. It does not need a prior PATCH request.

At present, only email_enabled and sms_enabled actively control delivery. payment_notifications and usage_alerts are stored and returned, but they do not yet suppress notifications. Do not describe those two fields as active delivery controls in your UI.

Payment confirmation or failure messages, and forgot-password or admin second-factor OTP messages, may be attempted over both email and SMS when both channels are available. Each attempt still respects the corresponding email_enabled and sms_enabled setting.

For balance and usage records, see Billing & credits and Activity & analytics.