openapi: 3.0.1
info:
  title: Notification Service API Specification
  description: |
    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:

    ```json
    {
      "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**:

    ```json
    {
      "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
    **](../../../docs/communication/notification/send-notification) 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:

    ```http
    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.
  version: 2.0.23
servers:
- description: ''
  url: https://api.btx.fr.banqup.com/core/notification
- description: ''
  url: https://api.btx.eu.banqup.com/core/notification
paths:
  /v1/notifications:
    post:
      tags:
      - Notification Acceptor
      summary: Sends notification
      description: "<div class='my-preview'><span>Preview: The API is in development
        or testing phases and the interface could still change slightly.</span></div>
        <br/> Sends notifications through defined channels based on specified templates
        <br/> Scope: notification_send<br/> This Endpoint is part of: notification-service"
      operationId: sendNotification
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Notification'
        required: true
      responses:
        '202':
          description: Notification sent successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationResponse'
        '400':
          description: Invalid Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 400
                error: BAD_REQUEST
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27T12:34:50Z
                type: about:blank
                title: Bad Request
                detail: Bad Request message details.
        '401':
          description: Unauthorized Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 401
                error: UNAUTHENTICATED
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27T12:34:50Z
                type: about:blank
                title: Unauthorized
                detail: Access to the requested resource lacks valid authentication
                  credentials.
        '403':
          description: Forbidden Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 403
                error: PERMISSION_DENIED
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27T12:34:50Z
                type: about:blank
                title: Forbidden
                detail: Access to the requested resource was denied.
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 500
                error: INTERNAL
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27T12:34:50Z
                type: about:blank
                title: Internal Server Error
                detail: The server encountered an unexpected error.
      security:
      - oauth2:
        - notification_send
components:
  schemas:
    AppName:
      type: string
      description: The name of the application for push notifications.
      example: Banqup
      enum:
      - Banqup
    ChannelType:
      type: string
      description: The communication channel for the notification.
      example: email
      enum:
      - email
      - sms
      - push-notification
    DeviceType:
      type: string
      description: The type of device for push notifications.
      example: PHONE
      enum:
      - PHONE
      - TABLET
      - WEB
    Notification:
      required:
      - asset
      - channels
      type: object
      properties:
        reference:
          type: string
          description: Optional custom notification reference.
          example: notif_ref_abc_123
        asset:
          minLength: 1
          type: string
          description: Asset name to be used for the notification content. The path
            is used to fetch a template.
          example: asset/iam/onboarding/welcome
        locale:
          type: string
          description: Locale for the notification template (e.g., 'en-GB', 'fr-BE').
          example: en-GB
        data:
          type: object
          additionalProperties:
            type: object
            description: A flexible object of key-value pairs to populate the notification
              template.
            example:
              invoiceNumber: INV-2025-0042
              paymentStatus: Paid
              user:
                nickname: Johnny
          description: A flexible object of key-value pairs to populate the notification
            template.
          example:
            invoiceNumber: INV-2025-0042
            paymentStatus: Paid
            user:
              nickname: Johnny
        space:
          type: string
          description: The space identifier. Used to retrieve brand, space-specific
            settings, and for access checks.
          format: uuid
          example: e0178e47-b067-452f-9e98-3f16f0085b7e
        groupName:
          type: string
          description: Used to narrow down the recipients of this notification.
          example: administrators
        subject:
          type: string
          description: The subject (user) identifier. Used to retrieve recipient details
            from the user store.
          example: 8c66dc06-424d-480e-a827-fb72101d9ea6
        appName:
          $ref: '#/components/schemas/AppName'
        deviceType:
          $ref: '#/components/schemas/DeviceType'
        recipient:
          $ref: '#/components/schemas/Recipient'
        channels:
          $ref: '#/components/schemas/ChannelType'
      description: Request body to send a comprehensive notification.
      example: |
        {
          "reference": "notif_ref_abc_123",
          "asset": "asset/iam/onboarding/welcome",
          "locale": "en-GB",
          "data": {
            "invoiceNumber": "INV-2025-0042",
            "paymentStatus": "Paid",
            "user": {
               "nickname": "Johnny"
             }
          },
          "space": "e0178e47-b067-452f-9e98-3f16f0085b7e",
          "subject": "8c66dc06-424d-480e-a827-fb72101d9ea6",
          "groupName": "administrators"
          "recipient": {
            "firstName": "John",
            "lastName": "Smith",
            "language": "en-GB",
            "email": "john.smith@example.com",
            "mobile": "+32456123456",
            "brand": "Banqup"
          },
          "channels": [
            "email",
            "sms",
            "push-notification"
          ]
        }
    Recipient:
      required:
      - brand
      - firstName
      - language
      - lastName
      type: object
      properties:
        firstName:
          minLength: 1
          type: string
          description: The recipient's first name.
          example: John
        lastName:
          minLength: 1
          type: string
          description: The recipient's last name.
          example: Smith
        language:
          minLength: 1
          type: string
          description: The preferred language of the recipient.
          example: en-GB
        email:
          pattern: "^(.*<([a-zA-Z0-9_!#$%&’*+/=?`{|}~^.-]+@[a-zA-Z0-9.-]+)>)$|^([a-zA-Z0-9_!#$%&’*+/=?`{|}~^.-]+@[a-zA-Z0-9.-]+)$"
          type: string
          description: The recipient's email address. Required for the 'email' channel.
          example: john.smith@example.com
        mobile:
          pattern: \+\d{1,3}\d{4,14}
          type: string
          description: The recipient's mobile number. Required for the 'sms' channel.
          example: '+32456123456'
        brand:
          minLength: 1
          type: string
          description: The brand associated with the recipient.
          example: Banqup
      description: Represents the recipient of the notification.
      example:
        firstName: John
        lastName: Smith
        language: en-GB
        email: john.smith@example.com
        mobile: '+32456123456'
        brand: Banqup
    NotificationResponse:
      required:
      - notificationId
      type: object
      properties:
        notificationId:
          minLength: 1
          type: string
          description: The unique identifier assigned to the notification request.
          example: 8ffebea7-427c-4b5d-b171-5107aa937a3c
      description: Response containing the unique identifier of the accepted notification
        request.
      example:
        notificationId: 8ffebea7-427c-4b5d-b171-5107aa937a3c
    ApiErrorProblemDetail:
      required:
      - error
      - requestId
      - timestamp
      type: object
      properties:
        status:
          type: integer
          format: int32
        error:
          type: string
        requestId:
          type: string
        timestamp:
          type: string
          format: date-time
        type:
          type: string
          format: uri
        title:
          type: string
        detail:
          type: string
        instance:
          type: string
          format: uri
        problems:
          type: array
          items:
            $ref: '#/components/schemas/NestedProblem'
        properties:
          type: object
          additionalProperties:
            type: object
    NestedProblem:
      required:
      - detail
      - error
      - title
      type: object
      properties:
        error:
          type: string
        title:
          type: string
        detail:
          type: string
        type:
          type: string
          format: uri
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.btx.fr.banqup.com/oauth2/client_credential/gettoken
          scopes:
            info: Scopes are endpoint-specific, see each endpoint for required scope.
        authorizationCode:
          authorizationUrl: https://api.btx.fr.banqup.com/oauth2/auth
          tokenUrl: https://api.btx.fr.banqup.com/oauth2/token
          scopes:
            info: Scopes are endpoint-specific, see each endpoint for required scope.
