openapi: 3.0.1
info:
  title: Service Engine APIs for Notifications
  description: >-
    Service Engine APIs for all HTM Notifications. These are NOT the CRUD APIs to access raw data in the database.
  version: "1.0"
servers:
  - url: https://services.acc.api.htm.nl/abt/touchpoint/2.0
tags:
  - name: Notification categories
    description: >-
      Service Engine APIs for all HTM Notifications metadata. To build content only.
  - name: Notification subscriptions
    description: >-
      Service Engine APIs for the HTM Notification subscriptions for a user. Contains the subscriptions on category level
  - name: Notification preferences
    description: >-
      //future  Service Engine APIs for the HTM Notification preferences for a category for a user. Contains the discrepancies from the default. or
paths:
  /notificationcategories:
    get:
      tags:
        - Notification categories
      summary: Get notification categories and optins references for that category that a touchpoint can show.
      description: |
        Get notification categories that a touchpoint can show and optins ( eventTypes) and channels (eventType_channels) for the optin for that category
      parameters:
        - name: expand
          in: query
          schema:
            type: string
            enum: [none, eventType, eventTypeChannel]
            default: none
      responses:
        "200":
          description: OK
          content:
            application/json:
              examples:
                getNotifactionCategories?expand=none:
                  summary: Return all the notification categories without nested attributes (expand=none)
                  value:
                    notificationCategories:
                      - notificationCategoryId: 1
                        name: Mijn Reizen
                      - notificationCategoryId: 2
                        name: Nieuwsbrief aanmelding
                      - notificationCategoryId: 3
                        name: Mijn Passen
                getNotifactionCategories?expand=eventType:
                  summary: Return all the notification categories with nested event types (expand=eventType)
                  value:
                    notificationCategories:
                      - notificationCategoryId: 1
                        name: Mijn Reizen
                        eventTypes:
                          - eventTypeId: 2
                            eventOrigin:
                              eventOriginId: 1
                              name: GBO
                            name: ALERTS, TRAVEL_SCHEME
                            subName: CI
                            prettyName: Check In
                            optinRequired: false
                          - eventTypeId: 3
                            eventOrigin:
                              eventOriginId: 1
                              name: GBO
                            name: ALERTS, PAD
                            subName: null
                            prettyName: Profielgegevens op de pas
                            optinRequired: false
                      - notificationCategoryId: 2
                        name: Nieuwsbrief aanmelding
                        eventTypes:
                          - eventTypeId: 1
                            eventOrigin:
                              eventOriginId: 6
                              name: Maileon
                            name: newsletter
                            subName: null
                            prettyName: HTM nieuwsbrief
                            optinRequired: false
                      - notificationCategoryId: 3
                        name: Mijn Passen
                        eventTypes:
                          - eventTypeId: 4
                            eventOrigin:
                              eventOriginId: 1
                              name: GBO
                            name: ALERTS, CARD
                            subName: null
                            prettyName: Mijn passen
                            optinRequired: false
                          - eventTypeId: 5
                            eventOrigin:
                              eventOriginId: 1
                              name: GBO
                            name: ALERTS, PAD
                            subName: null
                            prettyName: Profielgegevens op de pas
                            optinRequired: false
                getNotifactionCategories?expand=eventTypeChannel:
                  summary: Return all the notification categories with all nested attributes (expand=eventTypeChannel)
                  value:
                    notificationCategories:
                      - notificationCategoryId: 1
                        name: Mijn Reizen
                        eventTypes:
                          - eventTypeId: 2
                            eventOrigin:
                              eventOriginId: 1
                              name: GBO
                            name: ALERTS, TRAVEL_SCHEME
                            subName: CI
                            prettyName: Check In
                            optinRequired: false
                            eventTypeChannels:
                              - eventTypeChannelId: ccc8c025-06b5-4928-a632-23e1c55cd173
                                channel:
                                  channelId: 1
                                  name: push
                                isDefault: true
                                isMandatory: false
                              - eventTypeChannelId: da2deb4c-ce77-4b5f-aecc-ddebfd14349d
                                channel:
                                  channelId: 2
                                  name: email
                                isDefault: false
                                isMandatory: false
                          - eventTypeId: 3
                            eventOrigin:
                              eventOriginId: 1
                              name: GBO
                            name: ALERTS, PAD
                            subName: null
                            prettyName: Profielgegevens op de pas
                            optinRequired: false
                            eventTypeChannels:
                              - eventTypeChannelId: 8e7df8f1-7e50-482f-8301-d399e75fd432
                                channel:
                                  channelId: 1
                                  name: push
                                isDefault: true
                                isMandatory: false
                              - eventTypeChannelId: 72960a92-1855-469f-9cfd-5d72f57106f2
                                channel:
                                  channelId: 2
                                  name: email
                                isDefault: false
                                isMandatory: false
                      - notificationCategoryId: 2
                        name: Nieuwsbrief aanmelding
                        eventTypes:
                          - eventTypeId: 1
                            eventOrigin:
                              eventOriginId: 6
                              name: Maileon
                            name: newsletter
                            subName: null
                            prettyName: HTM nieuwsbrief
                            optinRequired: false
                            eventTypeChannels:
                              - eventTypeChannelId: 447a1116-6cd7-4645-8c3d-43237b6186cd
                                channel:
                                  channelId: 2
                                  name: email
                                isDefault: true
                                isMandatory: false
                      - notificationCategoryId: 3
                        name: Mijn Passen
                        eventTypes:
                          - eventTypeId: 4
                            eventOrigin:
                              eventOriginId: 1
                              name: GBO
                            name: ALERTS, CARD
                            subName: null
                            prettyName: Mijn passen
                            optinRequired: false
                            eventTypeChannels:
                              - eventTypeChannelId: be07c7bb-714b-4637-acf5-a67025ad8e60
                                channel:
                                  channelId: 1
                                  name: push
                                isDefault: true
                                isMandatory: false
                              - eventTypeChannelId: 0c797b5a-ed34-494b-8c64-0a832830d392
                                channel:
                                  channelId: 2
                                  name: email
                                isDefault: false
                                isMandatory: false
                          - eventTypeId: 5
                            eventOrigin:
                              eventOriginId: 1
                              name: GBO
                            name: ALERTS, PAD
                            subName: null
                            prettyName: Profielgegevens op de pas
                            optinRequired: false
                            eventTypeChannels:
                              - eventTypeChannelId: b910368f-c045-4e8e-b01d-bcbc78708bac
                                channel:
                                  channelId: 1
                                  name: push
                                isDefault: true
                                isMandatory: false
                              - eventTypeChannelId: 93e773da-ba3b-48da-9a0e-ee478eaa752f
                                channel:
                                  channelId: 2
                                  name: email
                                isDefault: false
                                isMandatory: false
        "404":
          description: No notification category found
          content:
            application/json:
              example:
                {
                  "type": "https://api.integratielaag.nl/abt/touchpoint/2.0/notifications",
                  "title": "Niet gevonden",
                  "detail": "Notificatiecategorie niet gevonden",
                  "instance": "555d00b5-bc3f-4591-949b-479e76d49ea7",
                  "errors":
                    [
                      {
                        "code": "404",
                        "detail": null,
                        "path": null,
                        "parameter": null,
                      },
                    ],
                }
  /notificationsubscriptions:
    get:
      tags:
        - Notification subscriptions
      summary: Get all possible notificationSubscriptions for a customer (account or private).
      description: |
        Get all possible notificationSubscriptions for a customer (account or private), including if they have opted-in for it.
      parameters:
        - name: X-HTM-JWT-AUTH-HEADER
          in: header
          schema:
            type: string
            example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
          required: false
          description: The JWT of a customer in case of touchpoint were customer logs in themselves
        - name: X-HTM-CUSTOMER-PROFILE-ID-HEADER
          in: header
          schema:
            type: string
            example: feaaef83-a551-4283-8419-340b1ada3b55
          required: false
          description: The customerProfileId of a customer in the case of the SMP
        - name: X-HTM-ROLE-HEADER
          in: header
          schema:
            type: string
            example: Customer
          required: false
          description: The role of the HTM employee in the case of the SMP
        - name: emailAddress
          in: query
          schema:
            type: string
            format: email
            example: john.doe@mymailprovider.com
          required: false
          description: The emailadress of the customer in the case of anonymous opt-ins
      responses:
        "200":
          description: OK
          content:
            application/json:
              examples:
                getNotifactionSubscriptionsAll:
                  summary: Return all the notification subscriptions where for each category the client has actively opted in or out - All
                  value:
                    {
                      "notificationSubscriptions":
                        [
                          {
                            "notificationSubscriptionId": "64047471-e0c3-4abc-b4eb-83a12a6de903",
                            "notificationCategory":
                              {
                                "notificationCategoryId": 1,
                                "name": "Mijn reizen",
                              },
                            "isActive": true,
                          },
                          {
                            "notificationSubscriptionId": "571388cd-8903-40d5-89e6-9191cb8d656e",
                            "notificationCategory":
                              {
                                "notificationCategoryId": 2,
                                "name": "Nieuwsbrief aanmelding",
                              },
                            "isActive": true,
                          },
                          {
                            "notificationSubscriptionId": "cf736ff2-2f8f-434e-a3c7-a14064b73c9b",
                            "notificationCategory":
                              {
                                "notificationCategoryId": 3,
                                "name": "Mijn contracten",
                              },
                            "isActive": false,
                          },
                        ],
                    }
                getNotifactionSubscriptionsSome:
                  summary: Return all the notification subscriptions where for each category the client has actively opted in or out - Some
                  value:
                    {
                      "notificationSubscriptions":
                        [
                          {
                            "notificationSubscriptionId": "64047471-e0c3-4abc-b4eb-83a12a6de903",
                            "notificationCategory":
                              {
                                "notificationCategoryId": 1,
                                "name": "Mijn reizen",
                              },
                            "isActive": true,
                          },
                          {
                            "notificationSubscriptionId": "cf736ff2-2f8f-434e-a3c7-a14064b73c9b",
                            "notificationCategory":
                              {
                                "notificationCategoryId": 2,
                                "name": "Nieuwsbrief aanmelding",
                              },
                            "isActive": false,
                          },
                        ],
                    }
        "403":
          description: Forbidden // Als geverifieerd profiel gevonden wordt, maar niet op een geverifieerde manier benaderd wordt
          content:
            application/json:
              example:
                {
                  "type": "https://api.integratielaag.nl/abt/touchpoint/2.0/notifications",
                  "title": "Verboden",
                  "detail": "Niet toegestaan",
                  "instance": "555d00b5-bc3f-4591-949b-479e76d49ea7",
                  "errors":
                    [
                      {
                        "code": "403",
                        "detail": null,
                        "path": null,
                        "parameter": null,
                      },
                    ],
                }
        "404":
          description: No notification subscriptions found
          content:
            application/json:
              example:
                {
                  "type": "https://api.integratielaag.nl/abt/touchpoint/2.0/notifications",
                  "title": "Niet gevonden",
                  "detail": "Notificatie niet gevonden",
                  "instance": "555d00b5-bc3f-4591-949b-479e76d49ea7",
                  "errors":
                    [
                      {
                        "code": "404",
                        "detail": null,
                        "path": null,
                        "parameter": null,
                      },
                    ],
                }
    post:
      tags:
        - Notification subscriptions
      summary: Create a new notificationSubscription for a customer (account or private).
      description: |
        Create a notificationSubscriptions for a customer (account or private), including if they have opted-in for it.
      parameters:
        - name: X-HTM-JWT-AUTH-HEADER
          in: header
          schema:
            type: string
            example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
          required: false
          description: The JWT of a customer in case of touchpoint were customer logs in themselves
        - name: X-HTM-CUSTOMER-PROFILE-ID-HEADER
          in: header
          schema:
            type: string
            example: feaaef83-a551-4283-8419-340b1ada3b55
          required: false
          description: The customerProfileId of a customer in the case of the SMP
        - name: X-HTM-ROLE-HEADER
          in: header
          schema:
            type: string
            example: Customer
          required: false
          description: The role of the HTM employee in the case of the SMP
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/unavailable"
            examples:
              Create notificationSubscription anonymous:
                value:
                  {
                    "emailAddress": "anonymous@mymailprovider.com",
                    "notificationCategoryId": 1
                  }
              Create notificationSubscription account active:
                value: { "notificationCategoryId": 2 }
      responses:
        "201":
          description: Created
          content:
            application/json:
              examples:
                Create notificationSubscription anonymous:
                  summary: Return the created notification for an anonymous user inactive by default.
                  value:
                    {
                      "notificationSubscriptionId": "e112f26e-37fa-4bde-8def-9977cd1d50ae",
                      "notificationCategory":
                        {
                          "notificationCategoryId": 2,
                          "name": "Nieuwsbrief aanmelding",
                        },
                      "isActive": False,
                    }
                Create notificationSubscription account active:
                  summary: Return the created notification for an anonymous user active
                  value:
                    {
                      "notificationSubscriptionId": "6b88eba1-af1f-42fc-82d3-d7202d5f1afe",
                      "notificationCategory":
                        { "notificationCategoryId": 2, "name": "Nieuwsbrief aanmelding" },
                      "isActive": True,
                    }
        "405":
          description: Method not allowed, ook als een notificatie aangemaakt wordt voor een account maar op een anonieme manier benadert wordt.
          content:
            application/json:
              example:
                {
                  "type": "https://api.integratielaag.nl/abt/touchpoint/2.0/notifications",
                  "title": "Methode niet toegestaan",
                  "detail": "",
                  "instance": "555d00b5-bc3f-4591-949b-479e76d49ea7",
                  "errors":
                    [
                      {
                        "code": "405",
                        "detail": null,
                        "path": null,
                        "parameter": null,
                      },
                    ],
                }
  /notificationsubscriptions/{notificationSubscriptionId}:
    patch:
      tags:
        - Notification subscriptions
      summary: Update a notificationSubscription for a customer.
      description: |
        Update a  notificationSubscription for a customer.
      parameters:
        - name: X-HTM-JWT-AUTH-HEADER
          in: header
          schema:
            type: string
            example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
          required: false
          description: The JWT of a customer in case of touchpoint were customer logs in themselves
        - name: X-HTM-CUSTOMER-PROFILE-ID-HEADER
          in: header
          schema:
            type: string
            example: feaaef83-a551-4283-8419-340b1ada3b55
          required: false
          description: The customerProfileId of a customer in the case of the SMP
        - name: X-HTM-ROLE-HEADER
          in: header
          schema:
            type: string
            example: Customer
          required: false
          description: The role of the HTM employee in the case of the SMP
        - name: notificationSubscriptionId
          in: path
          schema:
            type: string
            format: uuid
            example: e112f26e-37fa-4bde-8def-9977cd1d50ae
          required: true
          description: The id of the notificationSubscription you want to update
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/unavailable"
            examples:
              Update a notificationSubscription to inactive:
                value: { "isActive": False }
              Update a notificationSubscription to active:
                value: { "isActive": True }
      responses:
        "200":
          description: OK
          content:
            application/json:
              examples:
                Update a notificationSubscription to inactive:
                  summary: Return the updated inactive notification
                  value:
                    {
                      "notificationSubscriptionId": "e112f26e-37fa-4bde-8def-9977cd1d50ae",
                      "notificationCategory":
                        {
                          "notificationCategoryId": 2,
                          "name": "Nieuwsbrief aanmelding",
                        },
                      "isActive": False,
                    }
                Update a notificationSubscription to active:
                  summary: Return the updated active notification
                  value:
                    {
                      "notificationSubscriptionId": "e112f26e-37fa-4bde-8def-9977cd1d50ae",
                      "notificationCategory":
                        {
                          "notificationCategoryId": 2,
                          "name": "Nieuwsbrief aanmelding",
                        },
                      "isActive": True,
                    }
        "405":
          description: Method not allowed,wanneer het account emailadres niet geverifieerd is.
          content:
            application/json:
              example:
                {
                  "type": "https://api.integratielaag.nl/abt/touchpoint/2.0/notifications",
                  "title": "Methode niet toegestaan",
                  "detail": "",
                  "instance": "555d00b5-bc3f-4591-949b-479e76d49ea7",
                  "errors":
                    [
                      {
                        "code": "405",
                        "detail": null,
                        "path": null,
                        "parameter": null,
                      },
                    ],
                }
components:
  schemas:
    unavailable:
      type: object
