{ "openapi" : "3.0.0", "info" : { "version" : "0.0.5", "title" : "Notification Subscription API", "description" : "To receive notifications, an event notification subscriptions must be completed by providing the details of the events a subscriber want to be notified about. This API allows institutions subscribe to events they would like to receive for the BIC8s participating in the notification service. ** You must proceed with Domain Registration first before subscribing to the event notification.", "contact" : { "name" : "Developer Hub", "url" : "https://developer.swift.com", "email" : "developer-support@swift.com" }, "license" : { "name" : "API Restricted License", "url" : "https://developer.swift.com/api-license" } }, "servers" : [ { "description" : "SwaggerHub API Auto Mocking", "url" : "https://virtserver.swaggerhub.com/SWIFT-API/Notification-Subscription/0.0.5" }, { "description" : "URL for Pilot.", "url" : "https://api-test.swiftnet.sipn.swift.com/notification-service/v1" }, { "description" : "URL for Live.", "url" : "https://api.swiftnet.sipn.swift.com/notification-service/v1" }, { "description" : "URL for Sandbox Environment.", "url" : "https://sandbox.swift.com/notification-service/v1" } ], "security" : [ { "oauthBearerToken" : [ ] } ], "tags" : [ { "name" : "Subscriptions" } ], "paths" : { "/subscriptions" : { "post" : { "tags" : [ "Subscriptions" ], "summary" : "Create Subscription.", "description" : "Register or subscribe to specific event of interest in the context of an API Service.", "operationId" : "createSubscription", "requestBody" : { "required" : true, "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Subscription" }, "examples" : { "POSTSubscriptionRequest" : { "$ref" : "#/components/examples/SubscriptionRequest" } } } } }, "responses" : { "201" : { "description" : "Created.", "headers" : { "X-Request-ID" : { "$ref" : "#/components/headers/X-Request-ID" } }, "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/SubscriptionResponse" }, "examples" : { "GetSubscriptionResponse" : { "$ref" : "#/components/examples/GetSubscriptionResponse" } } } } }, "400" : { "$ref" : "#/components/responses/400-BadRequest" }, "401" : { "$ref" : "#/components/responses/401-Unauthorized" }, "403" : { "$ref" : "#/components/responses/403-Forbidden" }, "406" : { "$ref" : "#/components/responses/406-NotAcceptable" }, "413" : { "$ref" : "#/components/responses/413-PayloadTooLarge" }, "415" : { "$ref" : "#/components/responses/415-UnsupportedMediaType" }, "429" : { "$ref" : "#/components/responses/429-TooManyRequests" }, "503" : { "$ref" : "#/components/responses/503-ServiceUnavailable" }, "504" : { "$ref" : "#/components/responses/504-GatewayTimeout" }, "default" : { "$ref" : "#/components/responses/503-ServiceUnavailable" } } }, "get" : { "tags" : [ "Subscriptions" ], "summary" : "Retrieve Subscriptions.", "description" : "Retrieve the event subscriptions created on the API service for the calling institution.", "operationId" : "getSubscriptions", "responses" : { "200" : { "description" : "OK", "headers" : { "X-Request-ID" : { "$ref" : "#/components/headers/X-Request-ID" } }, "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Subscriptions" } } } }, "400" : { "$ref" : "#/components/responses/400-BadRequest" }, "401" : { "$ref" : "#/components/responses/401-Unauthorized" }, "403" : { "$ref" : "#/components/responses/403-Forbidden" }, "406" : { "$ref" : "#/components/responses/406-NotAcceptable" }, "429" : { "$ref" : "#/components/responses/429-TooManyRequests" }, "503" : { "$ref" : "#/components/responses/503-ServiceUnavailable" }, "504" : { "$ref" : "#/components/responses/504-GatewayTimeout" }, "default" : { "$ref" : "#/components/responses/503-ServiceUnavailable" } } } }, "/subscriptions/{subscription-id}" : { "get" : { "tags" : [ "Subscriptions" ], "summary" : "Retrieve a Subscription.", "description" : "Retrieve a notification subscription identified by subscription-id.", "operationId" : "getSubscriptionById", "parameters" : [ { "$ref" : "#/components/parameters/subscription-id" } ], "responses" : { "200" : { "description" : "OK", "headers" : { "X-Request-ID" : { "$ref" : "#/components/headers/X-Request-ID" } }, "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/SubscriptionResponse" }, "examples" : { "GetSubscriptionResponse" : { "$ref" : "#/components/examples/GetSubscriptionResponse" } } } } }, "400" : { "$ref" : "#/components/responses/400-BadRequest" }, "401" : { "$ref" : "#/components/responses/401-Unauthorized" }, "403" : { "$ref" : "#/components/responses/403-Forbidden" }, "404" : { "$ref" : "#/components/responses/404-NotFound" }, "406" : { "$ref" : "#/components/responses/406-NotAcceptable" }, "429" : { "$ref" : "#/components/responses/429-TooManyRequests" }, "503" : { "$ref" : "#/components/responses/503-ServiceUnavailable" }, "504" : { "$ref" : "#/components/responses/504-GatewayTimeout" }, "default" : { "$ref" : "#/components/responses/503-ServiceUnavailable" } } }, "put" : { "tags" : [ "Subscriptions" ], "summary" : "Modify a Subscription.", "description" : "Modify an existing notification subscription identified by subscription-id.", "operationId" : "modifySubscriptionById", "parameters" : [ { "$ref" : "#/components/parameters/subscription-id" } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Subscription" } } } }, "responses" : { "204" : { "description" : "No Content", "headers" : { "X-Request-ID" : { "$ref" : "#/components/headers/X-Request-ID" } } }, "400" : { "$ref" : "#/components/responses/400-BadRequest" }, "401" : { "$ref" : "#/components/responses/401-Unauthorized" }, "403" : { "$ref" : "#/components/responses/403-Forbidden" }, "404" : { "$ref" : "#/components/responses/404-NotFound" }, "413" : { "$ref" : "#/components/responses/413-PayloadTooLarge" }, "415" : { "$ref" : "#/components/responses/415-UnsupportedMediaType" }, "429" : { "$ref" : "#/components/responses/429-TooManyRequests" }, "503" : { "$ref" : "#/components/responses/503-ServiceUnavailable" }, "504" : { "$ref" : "#/components/responses/504-GatewayTimeout" }, "default" : { "$ref" : "#/components/responses/503-ServiceUnavailable" } } }, "delete" : { "tags" : [ "Subscriptions" ], "summary" : "Delete a Subscription.", "description" : "Delete an existing notification subscription identified by subscription-id.", "operationId" : "deleteSubscriptionById", "parameters" : [ { "$ref" : "#/components/parameters/subscription-id" } ], "responses" : { "204" : { "description" : "No Content", "headers" : { "X-Request-ID" : { "$ref" : "#/components/headers/X-Request-ID" } } }, "400" : { "$ref" : "#/components/responses/400-BadRequest" }, "401" : { "$ref" : "#/components/responses/401-Unauthorized" }, "403" : { "$ref" : "#/components/responses/403-Forbidden" }, "404" : { "$ref" : "#/components/responses/404-NotFound" }, "429" : { "$ref" : "#/components/responses/429-TooManyRequests" }, "503" : { "$ref" : "#/components/responses/503-ServiceUnavailable" }, "504" : { "$ref" : "#/components/responses/504-GatewayTimeout" }, "default" : { "$ref" : "#/components/responses/503-ServiceUnavailable" } } } } }, "components" : { "schemas" : { "Subscriptions" : { "type" : "array", "description" : "Subscriptions.", "additionalProperties" : false, "items" : { "properties" : { "subscription_id" : { "type" : "string", "format" : "uuid", "description" : "An unique identifier of the subscription.", "example" : "41d69890-54d0-41ef-bcfd-b083ad4c6475" }, "service_name" : { "maxLength" : 100, "minLength" : 1, "type" : "string", "description" : "Name of the API service.", "example" : "gss.screening.api" }, "event_types" : { "description" : "Identifies the event type.", "type" : "array", "items" : { "type" : "string", "pattern" : "^[a-zA-Z0-9._-]*$" }, "example" : [ "com.gss.screening.result-success", "com.gss.screening.result-failure" ] }, "mechanism" : { "description" : "Event delivery mechanism. Default this value to \"webhooks\". This field is meant for supporting other delivery channels in the future.", "type" : "string", "pattern" : "^[a-zA-Z0-9._-]*$", "example" : "webhooks" }, "subscriber_bics" : { "description" : "Filter events subscription per BIC8.", "type" : "array", "items" : { "type" : "string", "pattern" : "^[a-z]{6,6}[a-z2-9][a-np-z0-9]$" }, "example" : [ "swhqbebb", "swhetxxx" ] }, "endpoint" : { "description" : "Endpoint for receiving service specific events notifications. The endpoint must be defined with https scheme. The domain name used must be a pre-registered routable domain. Please refer to Domain Registration API for more details.", "type" : "string", "format" : "uri", "pattern" : "^https:\\/\\/[^\\s\\/$.?#].[^\\s]*$", "maxLength" : 1024, "example" : "https://51d57890-54d0-41ef-bcfd-b983ad4c6475.hooks.swiftnet.sipn.swift.com/api-tracker-events" } }, "required" : [ "subscription_id", "service_name", "event_types", "mechanism", "subscriber_bics" ] } }, "Subscription" : { "type" : "object", "description" : "Register / Create an event subscription.", "additionalProperties" : false, "required" : [ "service_name", "event_types", "mechanism", "subscriber_bics" ], "properties" : { "service_name" : { "maxLength" : 100, "minLength" : 1, "type" : "string", "description" : "Name of the API service.", "example" : "gss.screening.api" }, "event_types" : { "description" : "Identifies the event type.", "type" : "array", "items" : { "type" : "string", "pattern" : "^[a-zA-Z0-9._-]*$" }, "example" : [ "com.gss.screening.result-success", "com.gss.screening.result-failure" ] }, "mechanism" : { "description" : "Event Delivery mechanism", "type" : "string", "pattern" : "^[a-zA-Z0-9._-]*$", "example" : "webhooks" }, "subscriber_bics" : { "description" : "Filter events subscription per BIC8.", "type" : "array", "items" : { "type" : "string", "pattern" : "^[a-z]{6,6}[a-z2-9][a-np-z0-9]$" }, "example" : [ "swhqbebb", "swhetxxx" ] }, "endpoint" : { "description" : "Endpoint for receiving service specific events notifications. The endpoint must be defined with https scheme. The domain name used must be a pre-registered routable domain. Please refer to Domain Registration API for more details.", "type" : "string", "format" : "uri", "pattern" : "^https:\\/\\/[^\\s\\/$.?#].[^\\s]*$", "maxLength" : 1024, "example" : "https://51d57890-54d0-41ef-bcfd-b983ad4c6475.hooks.swiftnet.sipn.swift.com/api-tracker-events" } } }, "SubscriptionResponse" : { "type" : "object", "description" : "Retrieve a event subscription identified by subscription-id.", "additionalProperties" : false, "properties" : { "subscription_id" : { "type" : "string", "format" : "uuid" }, "service_name" : { "maxLength" : 100, "minLength" : 1, "type" : "string", "description" : "Name of the API Service.", "example" : "gss.screening.api" }, "event_types" : { "description" : "Identifies the event type.", "type" : "array", "items" : { "type" : "string", "pattern" : "^[a-zA-Z0-9._-]*$" } }, "mechanism" : { "description" : "Event delivery mechanism.", "type" : "string", "pattern" : "^[a-zA-Z0-9._-]*$", "example" : "webhooks" }, "subscriber_bics" : { "description" : "The BIC(s) to which the events must be delivered when an event occurs. The BIC must be a subscriber of the service related to the events.", "type" : "array", "items" : { "type" : "string", "pattern" : "^[a-z]{6,6}[a-z2-9][a-np-z0-9]$" } }, "endpoint" : { "description" : "Endpoint for receiving service specific events notifications. The endpoint must be defined with https scheme. The domain name used must be a pre-registered routable domain. Please refer to Domain Registration API for more details.", "type" : "string", "format" : "uri", "pattern" : "^https:\\/\\/[^\\s\\/$.?#].[^\\s]*$", "maxLength" : 1024, "example" : "https://51d57890-54d0-41ef-bcfd-b983ad4c6475.test.hooks.swiftnet.sipn.swift.com/api-tracker-events" } }, "required" : [ "subscription_id", "service_name", "event_types", "mechanism", "subscriber_bics" ] }, "Errors" : { "description" : "Container to return multiple ErrorMessage object. Collection of error can be useful when API needs to return multiple errors, for example validation errors. When the response code conveys application-specific functional semantics and consumer can parse machine-readable error code, this block can be useful. The error response must contain at least one error object.", "type" : "object", "additionalProperties" : false, "required" : [ "code", "severity", "text" ], "properties" : { "severity" : { "description" : "Specifies the severity of the error.", "type" : "string", "enum" : [ "Fatal", "Transient", "Logic" ] }, "code" : { "description" : "Specifies the custom error code as defined by the service provider.", "type" : "string", "minLength" : 3, "maxLength" : 70 }, "text" : { "description" : "Specifies the detail error message identifying the cause of the error.", "type" : "string", "minLength" : 1, "maxLength" : 255 } } } }, "headers" : { "X-Request-ID" : { "description" : "Specify an unique end to end tracking request ID. The element will be populated by the SWIFT API gateway", "schema" : { "type" : "string" } } }, "parameters" : { "X-Request-ID" : { "description" : "Specify an unique end to end tracking request ID. The element will be populated by the SWIFT API gateway.", "name" : "X-Request-ID", "in" : "header", "schema" : { "type" : "string" } }, "subscription-id" : { "name" : "subscription-id", "in" : "path", "description" : "Identifier of a specific subscription.", "required" : true, "schema" : { "type" : "string", "format" : "uuid" }, "example" : "41d69890-54d0-41ef-bcfd-b083ad4c6475" } }, "responses" : { "400-BadRequest" : { "description" : "Bad Request", "headers" : { "X-Request-ID" : { "$ref" : "#/components/headers/X-Request-ID" } }, "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Errors" } } } }, "401-Unauthorized" : { "description" : "Unauthorized", "headers" : { "X-Request-ID" : { "$ref" : "#/components/headers/X-Request-ID" } }, "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Errors" } } } }, "403-Forbidden" : { "description" : "Forbidden", "headers" : { "X-Request-ID" : { "$ref" : "#/components/headers/X-Request-ID" } }, "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Errors" } } } }, "404-NotFound" : { "description" : "Not Found", "headers" : { "X-Request-ID" : { "$ref" : "#/components/headers/X-Request-ID" } }, "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Errors" } } } }, "405-MethodNotAllowed" : { "description" : "Method Not Allowed", "headers" : { "X-Request-ID" : { "$ref" : "#/components/headers/X-Request-ID" } }, "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Errors" } } } }, "406-NotAcceptable" : { "description" : "Not Acceptable", "headers" : { "X-Request-ID" : { "$ref" : "#/components/headers/X-Request-ID" } }, "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Errors" } } } }, "407-ProxyAuthenticationRequired" : { "description" : "Proxy Authentication Required", "headers" : { "X-Request-ID" : { "$ref" : "#/components/headers/X-Request-ID" } }, "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Errors" } } } }, "409-Conflict" : { "description" : "Conflict", "headers" : { "X-Request-ID" : { "$ref" : "#/components/headers/X-Request-ID" } }, "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Errors" } } } }, "410-Gone" : { "description" : "Gone", "headers" : { "X-Request-ID" : { "$ref" : "#/components/headers/X-Request-ID" } }, "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Errors" } } } }, "412-PreconditionFailed" : { "description" : "Precondition Failed", "headers" : { "X-Request-ID" : { "$ref" : "#/components/headers/X-Request-ID" } }, "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Errors" } } } }, "413-PayloadTooLarge" : { "description" : "Payload Too Large", "headers" : { "X-Request-ID" : { "$ref" : "#/components/headers/X-Request-ID" } }, "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Errors" } } } }, "415-UnsupportedMediaType" : { "description" : "Unsupported Media Type", "headers" : { "X-Request-ID" : { "$ref" : "#/components/headers/X-Request-ID" } }, "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Errors" } } } }, "429-TooManyRequests" : { "description" : "Too Many Requests", "headers" : { "X-Request-ID" : { "$ref" : "#/components/headers/X-Request-ID" } }, "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Errors" } } } }, "500-InternalServerError" : { "description" : "Internal Server Error", "headers" : { "X-Request-ID" : { "$ref" : "#/components/headers/X-Request-ID" } }, "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Errors" } } } }, "502-BadGateway" : { "description" : "Bad Gateway", "headers" : { "X-Request-ID" : { "$ref" : "#/components/headers/X-Request-ID" } }, "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Errors" } } } }, "503-ServiceUnavailable" : { "description" : "Service Unavailable", "headers" : { "X-Request-ID" : { "$ref" : "#/components/headers/X-Request-ID" } }, "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Errors" } } } }, "504-GatewayTimeout" : { "description" : "Gateway Timeout", "headers" : { "X-Request-ID" : { "$ref" : "#/components/headers/X-Request-ID" } }, "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Errors" } } } } }, "securitySchemes" : { "oauthBearerToken" : { "type" : "http", "scheme" : "bearer", "bearerFormat" : "opaque OAuth 2.0", "description" : "The access token obtained as a result of OAuth 2.0 flows. SWIFT supports two OAuth grant types for consumption depending on the environment where the API is exposed. \n\n* MV-SIPN - jwt-bearer grant type [RFC 7523](https://tools.ietf.org/html/rfc7523) with Signed JWT assertion\n* Internet - Password grant type with license credentials.\n\nThis API uses JWT-Bearer grant type.\n\nPlease visit [SWIFT OAuth Token API](https://developer.swift.com/swift-oauth-token-api) page for more information and examples on how to generate an OAuth token.\n\nIn this declaration only the basic security element to transport the bearer token of an OAuth2 process is declared.\n \n" } }, "examples" : { "SubscriptionRequest" : { "summary" : "Create a subscription", "value" : { "service_name" : "gss.screening.api", "event_types" : [ "com.gss.screening.result-success", "com.gss.screening.result-failure" ], "mechanism" : "webhooks", "subscriber_bics" : [ "swhqbebb", "swhetxxx" ], "endpoint" : "https://51d57890-54d0-41ef-bcfd-b983ad4c6475.hooks.swiftnet.sipn.swift.com/api-tracker-events" } }, "GetSubscriptionResponse" : { "summary" : "Get all subscription response", "value" : { "subscription_id" : "41d69890-54d0-41ef-bcfd-b083ad4c6475", "service_name" : "gss.screening.api", "event_types" : [ "com.gss.screening.result-success", "com.gss.screening.result-failure" ], "mechanism" : "webhooks", "subscriber_bics" : [ "swhqbebb", "swhetxxx" ], "endpoint" : "https://51d57890-54d0-41ef-bcfd-b983ad4c6475.hooks.swiftnet.sipn.swift.com/api-tracker-events" } } } } }