openapi: 3.0.1
info:
  title: platform_notification API
  description: Merged OpenAPI spec for platform_notification domain
  version: 1.0.0
servers:
- url: https://api.cve.btx.eu.banqup.com/platform/notification
paths:
  /v1/notifications:
    post:
      tags:
      - Notification Acceptor
      summary: Sends notification
      description: Sends notifications through defined channels based on specified
        templates
      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-27 12:34:50+00:00
                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-27 12:34:50+00:00
                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-27 12:34:50+00:00
                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-27 12:34:50+00:00
                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:
          minItems: 1
          type: array
          description: A list of channels where the notification should be sent.
          items:
            $ref: '#/components/schemas/ChannelType'
      description: Request body to send a comprehensive notification.
      example: "{\n  \"reference\": \"notif_ref_abc_123\",\n  \"asset\": \"asset/iam/onboarding/welcome\"\
        ,\n  \"locale\": \"en-GB\",\n  \"data\": {\n    \"invoiceNumber\": \"INV-2025-0042\"\
        ,\n    \"paymentStatus\": \"Paid\",\n    \"user\": {\n       \"nickname\"\
        : \"Johnny\"\n     }\n  },\n  \"space\": \"e0178e47-b067-452f-9e98-3f16f0085b7e\"\
        ,\n  \"subject\": \"8c66dc06-424d-480e-a827-fb72101d9ea6\",\n  \"groupName\"\
        : \"administrators\"\n  \"recipient\": {\n    \"firstName\": \"John\",\n \
        \   \"lastName\": \"Smith\",\n    \"language\": \"en-GB\",\n    \"email\"\
        : \"john.smith@example.com\",\n    \"mobile\": \"+32456123456\",\n    \"brand\"\
        : \"Banqup\"\n  },\n  \"channels\": [\n    \"email\",\n    \"sms\",\n    \"\
        push-notification\"\n  ]\n}\n"
    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.cve.btx.eu.banqup.com/oauth2/client_credential/gettoken
          scopes:
            info: Scopes are endpoint-specific, see each endpoint for required scope.
        authorizationCode:
          authorizationUrl: https://api.cve.btx.eu.banqup.com/oauth2/auth
          tokenUrl: https://api.cve.btx.eu.banqup.com/oauth2/token
          scopes:
            info: Scopes are endpoint-specific, see each endpoint for required scope.
tags: []
