Skip to main content
Version: 1.0.143

Notification Service API Specification

This page describes how to integrate with the Notification Service on a technical level.

REST Resources​

The Notification Service provides a single, powerful resource for creating and dispatching notifications to one or more channels.

The Notification Resource​

A notification is a request to send a notification to a user. It combines several key pieces of information:

  • recipient: Details about the end-user, such as their name, email, and mobile number.
  • asset: A reference to a content template (e.g., for an email body or SMS message).
  • data: A flexible JSON object containing key-value pairs to populate the template.
  • channels: An array specifying which channels the notification should be sent through (e.g., email, sms).

An example of a notification request in JSON format:

{
  "reference": "notif_ref_abc_123",
  "asset": "asset/iam/onboarding/welcome",
  "locale": "en-GB",
  "data": {
    "invoiceNumber": "INV-2025-0042",
    "user": {
      "nickname": "Johnny"
    }
  },
  "space": "e0178e47-b067-452f-9e98-3f16f0085b7e",
  "subject": "8c66dc06-424d-4b0e-a827-fb72101d9ea6",
  "recipient": {
    "firstName": "John",
    "lastName": "Smith",
    "language": "en-GB",
    "email": "john.smith@example.com",
    "mobile": "+32456123456",
    "brand": "Banqup"
  },
  "channels": [
    "email",
    "sms"
  ]
}

When this notification request is accepted, the service returns a unique notificationId:

{
  "notificationId": "8ffebea7-427c-4b5d-b171-5107aa937a3c"
}

This ID confirms that the notification has been accepted for processing.

Sending a Notification​

To send a new notification, you'll perform a POST request to the **/core/notification/v1/notifications ** endpoint, providing the full notification object in the request body.

The service acts as an acceptor and router. Based on the channels array, it will forward the request to the appropriate downstream service (e.g., Email Service, SMS Service) for delivery.

For example, to send a notification via email and SMS:

POST /v1/notifications
Content-Type: application/json

{
  "reference": "notif_ref_abc_123",
  "asset": "asset/iam/onboarding/welcome",
  "recipient": {
    "firstName": "John",
    "lastName": "Smith",
    "email": "john.smith@example.com",
    "mobile": "+32456123456",
    "language": "en-GB",
    "brand": "Banqup"
  },
  "data": {
    "invoiceNumber": "INV-2025-0042"
  },
  "channels": [
    "email",
    "sms"
  ]
}

A successful response (HTTP 202 Accepted) will return the notificationId.

Multi-Channel Delivery​

The channels array is a powerful feature that allows you to target multiple communication methods in a single API call. The service supports the following channels:

  • email
  • sms
  • push-notification

You must provide the necessary recipient details for each channel you specify (e.g., recipient.email for the email channel).

Security​

Access to send notifications is controlled by the notification_send security scope. All requests to the Notification API must be authenticated using an OAuth security scheme and include a token with the required scope.

Authentication​

Security Scheme Type:

oauth2

OAuth Flow (clientCredentials):

Scopes:

  • info: Scopes are endpoint-specific, see each endpoint for required scope.

OAuth Flow (authorizationCode):

Scopes:

  • info: Scopes are endpoint-specific, see each endpoint for required scope.