Akoya Notifications API OpenAPI specification
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
x-stoplight:
id: 3sn2rsa0i1rxu
info:
version: 1.0.2
title: Akoya Notifications API v1.0.2
description: |
v1.0.2 update
- Updated sandbox test event endpoint
v1.0.1 update
- Added sandbox API server
- Added sandbox test event endpoint
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://sandbox-api.akoya.com'
description: Sandbox Notifications API server
- 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> \U0001F4D8 Note\r\n>\r\n> This endpoint is supported in sandbox (`https://sandbox-api.akoya.com`) and production (`https://api.akoya.com`)\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
x-stoplight:
id: v730yvuoyspgh
'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
x-stoplight:
id: qvckj0wfon1j3
get:
summary: List notification subscriptions
operationId: get-notification-subscriptions
tags:
- Event Notifications
description: "List your notification subscriptions.\r\n> \U0001F4D8 Note\r\n>\r\n> This endpoint is supported in sandbox (`https://sandbox-api.akoya.com`) and production (`https://api.akoya.com`)\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
x-stoplight:
id: 3p0qzwefo3is7
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/notificationSubscription'
x-stoplight:
id: qhzqcvls14fak
x-internal: false
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> \U0001F4D8 Note\n>\n> This endpoint is supported in sandbox (`https://sandbox-api.akoya.com`) and production (`https://api.akoya.com`)\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'
x-stoplight:
id: ca6nsjs3p21rx
x-internal: false
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> \U0001F4D8 Note\r\n>\r\n> This endpoint is supported in sandbox (`https://sandbox-api.akoya.com`) and production (`https://api.akoya.com`)\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: false
x-stoplight:
id: v2mfnvonelrf9
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'
x-stoplight:
id: qu9w8kugug7jb
description: "Update the `callbackUrl`, `effectiveDate`, or `callbackEmail` of a notification subscription.\r\n\r\n> \U0001F4D8 Note\r\n>\r\n> This endpoint is supported in sandbox (`https://sandbox-api.akoya.com`) and production (`https://api.akoya.com`)\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: ''
x-internal: false
'/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
x-stoplight:
id: e0gtgfoeb3unb
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> \U0001F4D8 Note\r\n>\r\n> This endpoint is supported in sandbox (`https://sandbox-api.akoya.com`) and production (`https://api.akoya.com`)\r\n\r\n> \U0001F6D1 The *service token* should be used as the bearer token with this call."
'/notifications/{version}/test':
parameters:
- schema:
type: string
name: version
in: path
required: true
description: version of endpoint
post:
summary: Send sandbox test event
tags:
- Event Notifications
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
category:
type: string
type:
type: string
notificationPayload:
type: object
properties:
id:
type: string
idType:
type: string
customFields:
type: array
items:
type: object
properties:
name:
type: string
value:
type: string
url:
type: object
properties:
href:
type: string
action:
type: string
x-examples:
Example 1:
category: CONSENT
type: CONSENT_UPDATED
notificationPayload:
id: 00000000-0000-0000-0001-000000000000
idType: CONSENT
customFields:
- name: INITIATOR
value: INDIVIDUAL
url:
href: 'https://sandbox-api.akoya.com/consents/v1/00000000-0000-0000-0001-000000000000'
action: GET
examples:
OK:
value:
category: CONSENT
type: CONSENT_UPDATED
notificationPayload:
id: 00000000-0000-0000-0001-000000000000
idType: CONSENT
customFields:
- name: INITIATOR
value: INDIVIDUAL
url:
href: 'https://sandbox-api.akoya.com/consents/v1/00000000-0000-0000-0001-000000000000'
action: GET
'400':
description: Input sent by client does not satisfy API specification
content:
application/json:
schema:
type: object
properties:
code:
type: string
message:
type: string
debugMessage:
type: string
x-examples:
Example 1:
code: '401'
message: Invalid Input
debugMessage: Provider custom developer-level error details for troubleshooting
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:
type: object
properties:
code:
type: string
message:
type: string
debugMessage:
type: string
x-examples:
Example 1:
code: '1205'
message: Unauthorized
debugMessage: Provider custom developer-level error details for troubleshooting
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:
type: object
properties:
code:
type: string
message:
type: string
debugMessage:
type: string
x-examples:
Example 1:
code: '1206'
message: Method Not Allowed
debugMessage: Provider custom developer-level error details for troubleshooting
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:
type: object
properties:
code:
type: string
message:
type: string
debugMessage:
type: string
x-examples:
Example 1:
code: '1207'
message: Too Many Requests
debugMessage: Provider custom developer-level error details for troubleshooting
examples:
Too many requests:
value:
code: '1207'
message: Too Many Requests
debugMessage: Provider custom developer-level error details for troubleshooting
'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:
type: object
properties:
code:
type: string
message:
type: string
debugMessage:
type: string
x-examples:
Example 1:
code: '500'
message: Internal server error
debugMessage: Provider custom developer-level error details for troubleshooting
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:
type: object
properties:
code:
type: string
message:
type: string
debugMessage:
type: string
x-examples:
Example 1:
code: '1106'
message: FdxVersion not supported or not implemented
debugMessage: Provider custom developer-level error details for troubleshooting
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:
type: object
properties:
code:
type: string
message:
type: string
debugMessage:
type: string
x-examples:
Example 1:
code: '503'
message: Scheduled Maintenance
debugMessage: Provider custom developer-level error details for troubleshooting
examples:
Scheduled Maintenance:
value:
code: '503'
message: Scheduled Maintenance
debugMessage: Provider custom developer-level error details for troubleshooting
operationId: get-notifications-version-test
x-stoplight:
id: 502j946jpvh4t
description: "Validate that your server can handle incoming webhook payloads from Akoya.\r\n\r\n> \U0001F4D8 Note\r\n>\r\n> This endpoint is only supported in sandbox (`https://sandbox-api.akoya.com`)"
requestBody:
content:
application/json:
schema:
type: object
x-examples:
Example 1:
id: '1234'
required:
- id
properties:
id:
type: string
description: A valid sandbox notification subscription ID. The triggered test event will be pushed to the callback URL associated with this subscription.
servers:
- url: 'https://sandbox-api.akoya.com'
description: Sandbox Notifications API Server
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
x-stoplight:
id: te9vcrnmk3e9p
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
x-stoplight:
id: z2nwgrpvqyq1u
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'
x-stoplight:
id: 0e4mciqcdc43l
notificationSubscription:
title: Notification Subscription entity
type: object
description: Provides the fields of a notification subscription
x-stoplight:
id: ehtyo5w0988s4
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.
x-stoplight:
id: xf6mmka9vkl13
example: 'https://abc.com/notification'
effectiveDate:
description: Effective date of notification
type: string
format: date
maxLength: 10
example: '2021-07-15'
callbackEmail:
type: string
x-stoplight:
id: kylx4d7suajq4
description: 'Optional. Captured for future implementation, which will be in an upcoming release.'
notificationCategory:
type: string
title: Notification Category
enum:
- MAINTENANCE
- CONSENT
description: Category of Notification
x-stoplight:
id: iewdmhw7y4f4q
notificationType:
type: string
title: Notification Type
enum:
- SERVICE
- PLANNED_OUTAGE
- CONSENT_UPDATED
- CONSENT_REVOKED
description: Type of Notification
x-stoplight:
id: zaj5fljlnl533
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.
x-stoplight:
id: m80op7fwepbo0
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
x-stoplight:
id: 8ycw80f6rcmih
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
x-stoplight:
id: iizczds2ey6bh
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
x-internal: true
Change log
Date | Update |
---|---|
2024-Sept-09 | Original |
Need help?
Check out our Developer Community, or visit the Support Center in the Data Recipient Hub.
Looking for provider nuance documentation?
All provider nuance documentation is available in the Data providers section in the Data Recipient Hub.
Still stuck?
For all production issues, submit a support ticket through the Data Recipient Hub. Our support team is standing by 24/7. Questions and non-production issues will be answered during business hours.
Updated about 1 month ago