Notifications OpenAPI
By hovering on the code, a clipboard icon will appear on the top right. Use it to copy the code. Then paste into your favorite text or code editor and save as a YAML file.
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
Updated about 2 months ago