Subscriptions API

openapi: 3.0.3 info: title: JH-Events Subscription API version: 1.0.0 description: Subscription management API for event routing configuration. contact: name: Team Icarus url: https://www.jackhenry.com/ email: jh-gcp-gbl-icarus-engineering@jackhenry.com servers: - url: https://banno.com description: Production environment - url: https://platform.banno-staging.com description: Staging environment - url: https://platform.banno-development.com description: Development environment tags: - name: Subscriptions description: APIs for managing subscription records paths: /a/api/enterprise-event/v1/{institutionId}/subscriptions: get: summary: Get All Subscriptions description: Retrieves a list of all subscriptions for the specified institution. operationId: subscriptionGetAll tags: - Subscriptions security: - bearerAuth: [] parameters: - $ref: '#/components/parameters/InstitutionIdPathParam' - $ref: '#/components/parameters/NoCacheQueryParam' responses: '200': $ref: '#/components/responses/SubscriptionArrayResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/UnexpectedError' post: summary: Create Subscription description: Creates a new subscription for the specified institution. operationId: subscriptionAdd tags: - Subscriptions security: - bearerAuth: [] parameters: - $ref: '#/components/parameters/InstitutionIdPathParam' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateSubscriptionRequest' responses: '200': $ref: '#/components/responses/SubscriptionResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/UnexpectedError' /a/api/enterprise-event/v1/{institutionId}/subscriptions/{subscriptionId}: get: summary: Get Subscription by ID description: Retrieves a single subscription by its unique ID. operationId: subscriptionGetById tags: - Subscriptions security: - bearerAuth: [] parameters: - $ref: '#/components/parameters/InstitutionIdPathParam' - $ref: '#/components/parameters/SubscriptionIdPathParam' - $ref: '#/components/parameters/NoCacheQueryParam' responses: '200': $ref: '#/components/responses/SubscriptionResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/UnexpectedError' put: summary: Update Subscription (Full Replacement) description: Replaces an existing subscription's entire record with the provided data. operationId: subscriptionUpdate tags: - Subscriptions security: - bearerAuth: [] parameters: - $ref: '#/components/parameters/InstitutionIdPathParam' - $ref: '#/components/parameters/SubscriptionIdPathParam' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateSubscriptionRequest' responses: '200': $ref: '#/components/responses/SubscriptionResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/UnexpectedError' patch: summary: Partially Update Subscription description: Partially updates a single subscription using JSON Merge Patch (RFC 7396). operationId: subscriptionPatch tags: - Subscriptions security: - bearerAuth: [] parameters: - $ref: '#/components/parameters/InstitutionIdPathParam' - $ref: '#/components/parameters/SubscriptionIdPathParam' requestBody: required: true content: application/merge-patch+json: schema: type: object description: JSON object with fields to update responses: '200': $ref: '#/components/responses/SubscriptionResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/UnexpectedError' delete: summary: Delete Subscription description: Deletes a subscription. Ensure no endpoint and filter objects are tied to this subscription before deleting. operationId: subscriptionDelete tags: - Subscriptions security: - bearerAuth: [] parameters: - $ref: '#/components/parameters/InstitutionIdPathParam' - $ref: '#/components/parameters/SubscriptionIdPathParam' responses: '204': description: Subscription deleted successfully. '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/UnexpectedError' components: securitySchemes: bearerAuth: description: OpenIDConnect JWT Token type: http scheme: bearer bearerFormat: JWT parameters: InstitutionIdPathParam: name: institutionId in: path description: Institution unique identifier required: true schema: type: string format: uuid example: 12345678-1234-1234-1234-123456789012 NoCacheQueryParam: name: nocache in: query description: Bypass cache if true required: false schema: type: boolean default: false SubscriptionIdPathParam: name: subscriptionId in: path description: Subscription unique identifier required: true schema: type: string format: uuid example: 87654321-4321-4321-4321-210987654321 schemas: BatchSettings: type: object description: Batch delivery settings properties: batchInterval: type: integer format: int64 description: Interval between batches in seconds example: 300 batchSize: type: integer format: int64 description: Maximum number of events per batch example: 100 HttpSettingsResponse: type: object description: HTTP settings in response (without secrets) properties: url: type: string format: uri description: Target URL for HTTP dispatch example: https://example.com/webhook authType: type: string description: Authentication type example: none usesSecrets: type: boolean description: Whether secrets are used for authentication example: false WcfSettingsResponse: type: object description: WCF settings in response (without credentials) properties: useWcfSecurity: type: boolean description: Whether to use WCF security example: true Subscription: type: object description: Subscription response object properties: id: type: string description: Subscription unique identifier readOnly: true example: c75f7c66-e858-47d6-bb82-7ea5547c800d name: type: string description: Subscription name example: New DirectConnect description: type: string description: Subscription description example: DirectConnect subscription for real-time events aggregateEvents: type: boolean description: Whether to aggregate events into batches example: false contentType: type: string description: Content type for dispatched events example: application/xml dispatchType: type: string description: Dispatch type (https, wcf, or none) enum: - https - wcf - none example: https enabled: type: boolean description: Whether the subscription is enabled example: true internalEndpoint: type: boolean description: Whether this is an internal endpoint example: false eventNumberFilter: type: array description: Filter for specific event numbers items: type: string example: - '1001' - '1002' batchSettings: $ref: '#/components/schemas/BatchSettings' httpSettings: $ref: '#/components/schemas/HttpSettingsResponse' wcfSettings: $ref: '#/components/schemas/WcfSettingsResponse' secretVersion: type: integer format: int64 description: Secret version number readOnly: true example: 1 StandardErrorType: description: A string path which uniquely classifies the domain of the error. type: string nullable: false example: jackhenry/operation-failed StandardErrorTitle: description: A end-user readable string title of the error type. nullable: false type: string StandardErrorDetails: description: An array of end-user readable strings which provide additional details for the error message. type: array nullable: false items: type: string StandardErrorData: type: object description: | Additional data that could be useful to a developer or for handing the error programmatically. The schema for the data in this object is intentionally left undefined. nullable: true StandardError: type: object required: - type - title - details properties: type: $ref: '#/components/schemas/StandardErrorType' title: $ref: '#/components/schemas/StandardErrorTitle' details: $ref: '#/components/schemas/StandardErrorDetails' data: $ref: '#/components/schemas/StandardErrorData' HttpSettings: type: object description: HTTP dispatch settings required: - url - authType - usesSecrets properties: url: type: string format: uri description: Target URL for HTTP dispatch example: https://example.com/webhook authType: type: string description: Authentication type example: none usesSecrets: type: boolean description: Whether secrets are used for authentication example: false secret: type: string description: Secret value (write-only, not returned in responses) writeOnly: true example: secret-value WcfSettings: type: object description: WCF dispatch settings properties: useWcfSecurity: type: boolean description: Whether to use WCF security example: true username: type: string description: WCF username (write-only, not returned in responses) writeOnly: true example: wcf-user password: type: string description: WCF password (write-only, not returned in responses) writeOnly: true example: wcf-password CreateSubscriptionRequest: type: object description: Request to create or update a subscription required: - name - dispatchType - enabled properties: name: type: string description: Subscription name example: New DirectConnect description: type: string description: Subscription description example: DirectConnect subscription for real-time events aggregateEvents: type: boolean description: Whether to aggregate events into batches default: false example: false contentType: type: string description: Content type for dispatched events example: application/xml dispatchType: type: string description: Dispatch type (https, wcf, or none) enum: - https - wcf - none example: https enabled: type: boolean description: Whether the subscription is enabled default: true example: true internalEndpoint: type: boolean description: Whether this is an internal endpoint default: false example: false eventNumberFilter: type: array description: Filter for specific event numbers items: type: string example: - '1001' - '1002' batchSettings: $ref: '#/components/schemas/BatchSettings' httpSettings: $ref: '#/components/schemas/HttpSettings' wcfSettings: $ref: '#/components/schemas/WcfSettings' secretVersion: type: integer format: int64 description: Secret version number example: 1 responses: SubscriptionArrayResponse: description: A list of subscriptions content: application/json: schema: type: array items: $ref: '#/components/schemas/Subscription' BadRequest: description: The server could not understand the request due to an invalid request. content: application/problem+json: schema: $ref: '#/components/schemas/StandardError' Unauthorized: description: Although the HTTP standard specifies "unauthorized", semantically this response means "unauthenticated". That is, the client must authenticate itself to get the requested response. Forbidden: description: The client does not have access rights to the content; that is, it is unauthorized, so the server is refusing to give the requested resource. Unlike 401, the clients identity is known to the server. UnexpectedError: description: An unexpected internal server error occurred while processing the request. content: application/problem+json: schema: $ref: '#/components/schemas/StandardError' examples: internalServerError: summary: Internal server error value: type: general/internal-server-error title: Internal server error details: - Unexpected internal server error SubscriptionResponse: description: A single subscription object content: application/json: schema: $ref: '#/components/schemas/Subscription' NotFound: description: The server can not find the requested resource. In an API, this can also mean that the endpoint is valid but the resource itself does not exist. Servers may also send this response instead of 403 to hide the existence of a resource from an unauthorized client.

Please ignore this field