Notifications OpenAPI

openapi: 3.1.0
info:
  version: '1.0'
  title: Akoya Notifications API
  description: |
    Event notifications.

    To use this API, first subscribe to the category and types of notifications you'd like to receive. Each subscription has an identification number so that you may maintain your subscriptions.
  contact:
    name: Akoya
    url: 'https://www.akoya.com/'
    email: [email protected]
  license:
    name: Akoya Terms of Use
    url: 'https://recipient.ddp.akoya.com/terms-of-use'
servers:
  - url: 'https://api.akoya.com'
    description: Notifications API server
tags:
  - name: Event Notifications
    description: Manage Event Notifications
security:
  - bearerAuth: []
paths:
  '/notifications/{version}/subscriptions':
    post:
      summary: Create notification subscription
      operationId: createNotificationSubscription
      description: "Creates a notification subscription.\r\n\r\n> \U0001F6D1 The *service token* should be used as the bearer token with this call.\r\n\r\n*Coming soon!\r\nAkoya will be requiring MTLS authentication for your callbackURL. This will enhance security for your end-users.*"
      tags:
        - Event Notifications
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/notificationSubscription'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/notificationSubscription'
                  - type: object
                    properties:
                      subscriptionId:
                        type: string
                        description: id
        '400':
          description: Input sent by client does not satisfy API specification
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
              examples:
                Invalid Input:
                  value:
                    code: '401'
                    message: Invalid Input
                    debugMessage: Provider custom developer-level error details for troubleshooting
        '401':
          description: Unauthorized to create a notification subscription
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
              examples:
                Unauthorized:
                  value:
                    code: '1205'
                    message: Unauthorized
                    debugMessage: Provider custom developer-level error details for troubleshooting
        '405':
          description: Method Not Allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
              examples:
                Method Not Allowed:
                  value:
                    code: '1206'
                    message: Method Not Allowed
                    debugMessage: Provider custom developer-level error details for troubleshooting
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
              examples:
                Too Many Requests:
                  value:
                    code: '1207'
                    message: Too Many Requests
                    debugMessage: Provider custom developer-level error details for troubleshooting
        '500':
          $ref: '#/components/responses/500'
        '501':
          $ref: '#/components/responses/501'
        '503':
          $ref: '#/components/responses/503'
      x-internal: false
    get:
      summary: List notification subscriptions
      operationId: get-notification-subscriptions
      tags:
        - Event Notifications
      description: "List your notification subscriptions.\r\n\r\n> \U0001F6D1 The *service token* should be used as the bearer token with this call."
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  notificationSubscriptions:
                    type: array
                    items:
                      allOf:
                        - $ref: '#/components/schemas/notificationSubscription'
                        - type: object
                          properties:
                            subscriptionId:
                              type: string
                              description: id
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/notificationSubscription'
    parameters:
      - $ref: '#/components/parameters/version'
  '/notifications/{version}/subscriptions/{subscriptionId}':
    parameters:
      - $ref: '#/components/parameters/subscriptionIdPath'
      - $ref: '#/components/parameters/version'
    get:
      summary: Get notification subscription by Id
      operationId: getNotificationSubscription
      description: "Call to get notification subscription by Id.\n\n> \U0001F6D1 The *service token* should be used as the bearer token with this call.\n"
      tags:
        - Event Notifications
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/notificationSubscription'
                  - type: object
                    properties:
                      subscriptionId:
                        type: string
                        description: id
              examples:
                Example 1:
                  value:
                    category: MAINTENANCE
                    type: PLANNED_OUTAGE
                    callbackUrl: 'https://example.com/notifications'
                    effectiveDate: '2024-07-15'
                    callbackEmail: [email protected]
                    subscriptionId: 7aeeaa24-4114-11ee-be56-0242ac120002
        '400':
          description: Input sent by client does not satisfy API specification
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
              examples:
                Invalid Input:
                  value:
                    code: '401'
                    message: Invalid Input
                    debugMessage: Provider custom developer-level error details for troubleshooting
        '401':
          description: Unauthorized to create a notification subscription
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
              examples:
                Unauthorized:
                  value:
                    code: '1205'
                    message: Unauthorized
                    debugMessage: Provider custom developer-level error details for troubleshooting
        '405':
          description: Method Not Allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
              examples:
                Method Not Allowed:
                  value:
                    code: '1206'
                    message: Method Not Allowed
                    debugMessage: Provider custom developer-level error details for troubleshooting
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
              examples:
                Too Many Requests:
                  value:
                    code: '1207'
                    message: Too Many Requests
                    debugMessage: Provider custom developer-level error details for troubleshooting
        '500':
          $ref: '#/components/responses/500'
        '501':
          $ref: '#/components/responses/501'
        '503':
          $ref: '#/components/responses/503'
    delete:
      summary: Delete notification subscription
      operationId: deleteNotificationSubscription
      description: "Delete a notification subscription. A \"204 - No Content\" is expected with a successful response.\r\n\r\n> \U0001F6D1 The *service token* should be used as the bearer token with this call."
      tags:
        - Event Notifications
      responses:
        '204':
          description: No Content
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '401':
          description: Unauthorized to create a notification subscription
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
              examples:
                Unauthorized:
                  value:
                    code: '1205'
                    message: Unauthorized
                    debugMessage: Provider custom developer-level error details for troubleshooting
        '405':
          description: Method Not Allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
              examples:
                Method Not Allowed:
                  value:
                    code: '1206'
                    message: Method Not Allowed
                    debugMessage: Provider custom developer-level error details for troubleshooting
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
              examples:
                Too Many Requests:
                  value:
                    code: '1207'
                    message: Too Many Requests
                    debugMessage: Provider custom developer-level error details for troubleshooting
        '500':
          $ref: '#/components/responses/500'
        '501':
          $ref: '#/components/responses/501'
        '503':
          $ref: '#/components/responses/503'
      x-internal: true
    patch:
      summary: Update notification subscription
      operationId: patch-notifications-version-subscriptions-subscriptionId
      tags:
        - Event Notifications
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/notificationSubscription'
                  - type: object
                    properties:
                      subscriptionId:
                        type: string
                        description: id
        '400':
          description: Input sent by client does not satisfy API specification
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
              examples:
                Invalid Input:
                  value:
                    code: '401'
                    message: Invalid Input
                    debugMessage: Provider custom developer-level error details for troubleshooting
        '401':
          description: Unauthorized to create a notification subscription
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
              examples:
                Unauthorized:
                  value:
                    code: '1205'
                    message: Unauthorized
                    debugMessage: Provider custom developer-level error details for troubleshooting
        '405':
          description: Method Not Allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
              examples:
                Method Not Allowed:
                  value:
                    code: '1206'
                    message: Method Not Allowed
                    debugMessage: Provider custom developer-level error details for troubleshooting
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
              examples:
                Too Many Requests:
                  value:
                    code: '1207'
                    message: Too Many Requests
                    debugMessage: Provider custom developer-level error details for troubleshooting
        '500':
          $ref: '#/components/responses/500'
        '501':
          $ref: '#/components/responses/501'
        '503':
          $ref: '#/components/responses/503'
      description: "Update the `callbackUrl`, `effectiveDate`, or `callbackEmail` of a notification subscription.\r\n\r\n> \U0001F6D1 The *service token* should be used as the bearer token with this call."
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                callbackUrl:
                  type: string
                  description: Callback URL. Previous callback URL will be updated with latest.
                  example: 'https://abc.com/notification'
                effectiveDate:
                  description: Effective date of notification
                  type: string
                  format: date
                  maxLength: 10
                  example: '2021-07-15'
                callbackEmail:
                  type: string
                  description: 'Optional. Captured for future implementation, which will be in an upcoming release.'
            examples:
              Example 1:
                value:
                  category: MAINTENANCE
                  type: PLANNED_OUTAGE
                  callbackUrl: 'https://example.com/notifications'
                  effectiveDate: '2024-07-15'
                  callbackEmail: [email protected]
                  subscriptionId: 7aeeaa24-4114-11ee-be56-0242ac120002
        description: ''
  '/notifications/{version}/maintenance/{notificationPayloadId}':
    parameters:
      - $ref: '#/components/parameters/notificationPayloadId'
      - $ref: '#/components/parameters/version'
    get:
      summary: Maintenance notification details
      tags:
        - Event Notifications
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  category:
                    type: string
                  type:
                    type: string
                  institutionId:
                    type: string
                  startTime:
                    type: string
                  endTime:
                    type: string
                  title:
                    type: string
                  message:
                    type: string
                  impactedService:
                    type: array
                    items:
                      type: string
                x-examples:
                  Example 1:
                    id: d1c8260a-edd9-5cd0-9ebf-ad4c3dd29b01
                    category: MAINTENANCE
                    type: PLANNED_OUTAGE
                    institutionId: mikomo
                    startTime: '2000-01-26T00:00:00Z'
                    endTime: '2000-08-20T00:00:00Z'
                    title: Akoya Support - Maintenance Outage
                    message: 'There''s unplanned maintenance scheduled with mikomo for an API you have access to. Mikomo will be performing maintenance on PAYMENTS API in the production environment. The following APIs will be impacted: Payments; Given the nature of this impact, services may unavailable while the maintenance is occurring. Please contact us if you have any questions about this maintenance. To report a production issue with your API integration, log into the Akoya Support Portal to submit a support ticket.'
                    impactedService:
                      - payments
              examples:
                Maintenance notification:
                  value:
                    id: d1c8260a-edd9-5cd0-9ebf-ad4c3dd29b01
                    category: MAINTENANCE
                    type: PLANNED_OUTAGE
                    institutionId: mikomo
                    startTime: '2000-01-26T00:00:00Z'
                    endTime: '2000-08-20T00:00:00Z'
                    title: Akoya Support - Maintenance Outage
                    message: 'There''s unplanned maintenance scheduled with mikomo for an API you have access to. Mikomo will be performing maintenance on PAYMENTS API in the production environment. The following APIs will be impacted: Payments; Given the nature of this impact, services may unavailable while the maintenance is occurring. Please contact us if you have any questions about this maintenance. To report a production issue with your API integration, log into the Akoya Support Portal to submit a support ticket.'
                    impactedService:
                      - payments
      operationId: get-notifications-maintenance
      description: "The maintenance notification details that inform you on impacted service and when it will be resolved.\r\nThe notification payload id is required for this call. This id is returned in the notification sent to your webhook.\r\n\r\n> \U0001F6D1 The *service token* should be used as the bearer token with this call."
components:
  parameters:
    subscriptionIdPath:
      name: subscriptionId
      in: path
      description: ID of notification subscription
      required: true
      schema:
        type: string
        maxLength: 256
    version:
      name: version
      in: path
      required: true
      schema:
        type: string
        default: v1
        enum:
          - v1
      description: version of endpoint
    notificationPayloadId:
      name: notificationPayloadId
      in: path
      required: true
      schema:
        type: string
        default: dfkafd
  schemas:
    notification:
      title: Notification entity
      type: object
      description: Provides the base fields of a notification. Clients will read the `type` property to determine the expected notification payload
      properties:
        category:
          $ref: '#/components/schemas/notificationCategory'
          description: Category of notification
        type:
          $ref: '#/components/schemas/notificationType'
          description: Type of notification
        notificationPayload:
          $ref: '#/components/schemas/notificationPayload'
          description: Notification-specific key-value paired data
      required:
        - category
        - type
        - notificationPayload
    notificationPayload:
      title: Notification Payload entity
      type: object
      description: Custom key-value pairs payload for a notification
      properties:
        id:
          type: string
          description: ID for the origination entity related to the notification
        idType:
          description: Type of entity causing origination of the notification with the given ID
          type: string
          enum:
            - MAINTENANCE
            - CONSENT
        customFields:
          $ref: '#/components/schemas/fiAttribute'
          description: Custom key-value pairs for a notification
        url:
          $ref: '#/components/schemas/hateoasLink'
    notificationSubscription:
      title: Notification Subscription entity
      type: object
      description: Provides the fields of a notification subscription
      required:
        - category
        - type
        - callbackUrl
      properties:
        category:
          $ref: '#/components/schemas/notificationCategory'
          description: Category of notification
        type:
          $ref: '#/components/schemas/notificationType'
          description: Type of notification
        callbackUrl:
          type: string
          description: The URL to receive webhooks from Akoya. Must be HTTPS.
          example: 'https://abc.com/notification'
        effectiveDate:
          description: Effective date of notification
          type: string
          format: date
          maxLength: 10
          example: '2021-07-15'
        callbackEmail:
          type: string
          description: 'Optional. Captured for future implementation, which will be in an upcoming release.'
    notificationCategory:
      type: string
      title: Notification Category
      enum:
        - MAINTENANCE
      description: Category of Notification
    notificationType:
      type: string
      title: Notification Type
      enum:
        - SERVICE
        - PLANNED_OUTAGE
      description: Type of Notification
    error:
      title: Error
      description: An error entity which can be used at the API level for error responses or at the account level to indicate a problem specific to a particular account
      type: object
      properties:
        code:
          type: string
          description: Long term persistent identifier which can be used to trace error condition back to log information
        message:
          type: string
          description: End user displayable information which might help the customer diagnose an error
        debugMessage:
          type: string
          description: Message used to debug the root cause of the error. Contents should not be used in consumer's business logic. Can change at any time and should only be used for consumer to communicate with the data provider about an issue. Provider can include an error GUID in message for their use.
    fiAttribute:
      title: FI Attribute entity
      description: Financial Institution provider-specific attribute
      type: object
      properties:
        name:
          type: string
          description: Name of attribute
        value:
          type: string
          description: Value of attribute
    hateoasLink:
      title: HATEOAS Link
      description: REST application constraint (Hypermedia As The Engine Of Application State)
      type: object
      properties:
        href:
          type: string
          format: uri-reference
          description: URL to invoke the action on the resource
          example: 'https://api.akoya.com/notifications/v1/maintenance/6a402d29-0a72-47e5-af5d-75b1c1c10150'
        action:
          type: string
          enum:
            - GET
            - POST
            - PATCH
            - DELETE
            - PUT
          description: HTTP Method to use for the request
        rel:
          description: 'Relation of this link to its containing entity, as defined by and with many example relation values at [IETF RFC5988](https://datatracker.ietf.org/doc/html/rfc5988)'
          type: string
      required:
        - href
  responses:
    '500':
      description: Catch all exception where request was not processed due to an internal outage/issue. Consider other more specific errors before using this error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
          examples:
            Internal server error:
              value:
                code: '500'
                message: Internal server error
                debugMessage: Provider custom developer-level error details for troubleshooting
    '501':
      description: Error when FdxVersion in Header is not one of those implemented at backend
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
          examples:
            FdxVersion not supported or not implemented:
              value:
                code: '1106'
                message: FdxVersion not supported or not implemented
                debugMessage: Provider custom developer-level error details for troubleshooting
    '503':
      description: System is down for maintenance
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
          examples:
            Scheduled Maintenance:
              value:
                code: '503'
                message: Scheduled Maintenance
                debugMessage: Provider custom developer-level error details for troubleshooting
  securitySchemes:
    bearerAuth:
      description: Your service token should be used in the header of this call.
      type: http
      scheme: bearer
      bearerFormat: JWT