SWIFT Distributions API

openapi: 3.2.0
info:
  title: Swift Messaging Distributions API
  description: 'The Swift Messaging API enables your Back office applications to communicate with any SWIFT counterparty through Alliance Cloud by embedding SWIFT messages inside API calls, which offers easy and direct integration with Alliance Cloud via standard RESTful connectivity.


    The Swift Messaging API is the brand new connectivity feature designed for our Alliance Cloud customers and provides bidirectional flows for Back Offices to exchange messages (including copy of messages, transmission reports, delivery reports, delivery notifications) with Alliance Cloud, via RESTful APIs. So now you can use APIs to leverage the wide range of messaging services available on SWIFT – including all the FIN, InterAct, and FileAct services supported by Alliance Cloud. Upload and download endpoints are available per SWIFT service (FIN, InterAct, FileAct), while retrieving the list of available messages to be downloaded is available agnostically for all services.


    The Swift Messaging API supports batching for both sending and receiving messages (FIN and InterAct only).


    Release Notes


    Changes made since version 1.1.0:


    * Version in URLs updated to v2 (instead of v1)


    * Two new values for ''distribution_type'' available: ''archive'' and ''export''


    * Add ''export_content'' and ''export_format'' properties for a distribution, available when the distribution_type is ''export''


    * Introduce endpoints for downloading archive distributions


    * Introduce endpoints for downloading distributions of message exports


    * ''version'' field available for received FIN, InterAct, and FileAct message and companion_info objects


    * ''syntax_version'' field available for received FIN messages, inside the network_info object


    * Update FileAct transmission report and delivery report objects ''message'' property to ''companion_info''


    * Update ''mirs_balance_checkpoint_date_time'', ''local_output_time'', and ''message_input_time'' FIN fields type from date-time to plain string (14 characters). These fields carry local time information set by FIN for which the exact used time zone cannot be known. Format: ''yyyyMMddHHmmss'', example value: ''20230725105547''


    * Rename ''distributionId'' query parameter to ''distribution-id''


    * 404 error responses now carry the same JSON format (instead of plain text ''Not found'') as other error responses


    * Update FileAct upload transfer initiation endpoint URL from ''POST /fileact/messages'' to ''POST /fileact/transfers''


    * Update FileAct upload transfer ACK endpoint URL from ''/fileact/messages/{transfer-id}/acks'' to ''/fileact/transfers/{transfer-id}/acks'''
  contact:
    name: Standards & Developer Hub
    url: https://developer.swift.com
    email: developer-support@swift.com
  license:
    name: API Restricted License
    url: https://www.swift.com/file/56776/download?token=8w8DC4eF
  version: 2.0.0
servers:
- url: https://virtserver.swaggerhub.com/SWIFT-API/Swift-Messaging/2.0.0
  description: SwaggerHub API Auto Mocking
- url: https://api-test.swiftnet.sipn.swift.com/alliancecloud-test/v2
  description: Test environment
- url: https://api.swiftnet.sipn.swift.com/alliancecloud/v2
  description: Production environment
- url: https://sandbox.swift.com/alliancecloud/v2
  description: Sandbox environment
security:
- oauthBearerToken: []
tags:
- name: distributions
paths:
  /distributions:
    get:
      tags:
      - distributions
      summary: Retrieve the list of available distributions from Alliance Cloud
      description: This operation enables retrieving the list of available distributions for download from Alliance Cloud. The DN used to perform the OAuth process with SWIFT API Gateway is the one used to link the request to an application channel in Alliance Cloud.
      operationId: listDistributions
      parameters:
      - name: limit
        in: query
        description: Number of distributions to be returned. If the provided value is out of range or is not a parsable integer, the default value will be used for the request
        required: false
        style: form
        explode: true
        schema:
          type: integer
          default: 50
          minimum: 1
          maximum: 200
      - name: offset
        in: query
        description: Number of distributions to skip before returning results. If the provided value is out of range or is not a parsable integer, the default value will be used for the request
        required: false
        style: form
        explode: true
        schema:
          type: integer
          default: 0
          minimum: 0
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListDistributionsResponse'
              examples:
                List Distribution Statuses for all services:
                  $ref: '#/components/examples/ListAllDistributionsResponse'
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        default:
          $ref: '#/components/responses/UnexpectedError'
    patch:
      tags:
      - distributions
      summary: Update the status of multiple distributions in Alliance Cloud
      description: This operation enables updating the status of several distributions in a single API call. Updates to the status for each distribution can either be 'Ack' or 'Nak'. In case of a 'Nak', an optional message describing the reason for the NAK can be specified. If specified in an 'Ack' status update, the message will be ignored
      operationId: updateDistributions
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DistributionsUpdate'
            examples:
              Distributions Update Example:
                $ref: '#/components/examples/DistributionsUpdateRequest'
        required: true
      responses:
        '200':
          description: The request has been processed successfully. Each individual distribution update result is present in the response body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DistributionsUpdateResponse'
              examples:
                NAK Example:
                  $ref: '#/components/examples/DistributionsUpdateResponse'
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        default:
          $ref: '#/components/responses/UnexpectedError'
  /distributions/{id}:
    get:
      tags:
      - distributions
      summary: Retrieve a single available distribution from Alliance Cloud
      description: This operations enables retrieving a single available distribution from Alliance Cloud, providing its id. The DN used to perform the OAuth process with SWIFT API Gateway is the one used to link the request to an application channel in Alliance Cloud.
      operationId: getDistribution
      parameters:
      - name: id
        in: path
        description: The id of the distribution to retrieve
        required: true
        style: simple
        explode: false
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Distribution'
              examples:
                List single distribution status:
                  $ref: '#/components/examples/GetDistributionResponse'
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        default:
          $ref: '#/components/responses/UnexpectedError'
  /distributions/{id}/acks:
    post:
      tags:
      - distributions
      summary: ACK a distribution
      description: Send a ACK information about a distribution. A valid ACK on a distribution will remove the distribution from the list of available distributions, and mark the distribution as 'distributed' in Alliance Cloud. The request body include properties that will be used for non-repudiation reasons
      operationId: ackDistribution
      parameters:
      - name: id
        in: path
        description: The id of the distribution to ACK
        required: true
        style: simple
        explode: false
        schema:
          type: integer
          format: int64
      requestBody:
        content:
          application/json:
            example: null
            schema: {}
      responses:
        '204':
          description: No Content
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        default:
          $ref: '#/components/responses/UnexpectedError'
  /distributions/{id}/naks:
    post:
      tags:
      - distributions
      summary: NAK a distribution
      description: Send a NAK information about a distribution. A valid NAK on a distribution will remove the distribution from the list of available distributions, and mark the distribution as 'failed to be distributed' in Alliance Cloud.
      operationId: nakDistribution
      parameters:
      - name: id
        in: path
        description: The id of the distribution to NAK
        required: true
        style: simple
        explode: false
        schema:
          type: integer
          format: int64
        example: 732489498
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Nak'
            examples:
              NAK Example:
                $ref: '#/components/examples/NakExampleRequest'
        required: true
      responses:
        '204':
          description: No Content
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        default:
          $ref: '#/components/responses/UnexpectedError'
components:
  schemas:
    ListDistributionsResponse:
      title: ListDistributionsResponse
      description: Information about distributions available for download from Alliance Cloud
      type: object
      additionalProperties: true
      properties:
        distributions:
          description: Array of distributions that are available for download
          type: array
          items:
            $ref: '#/components/schemas/Distribution'
        links:
          $ref: '#/components/schemas/Links'
    DistributionsUpdateResponse:
      title: DistributionsUpdateResponse
      type: array
      items:
        $ref: '#/components/schemas/DistributionUpdateResponse'
      description: A collection distribution update results following an update request.
    DistributionUpdate:
      title: DistributionUpdate
      type: object
      additionalProperties: false
      required:
      - id
      - status
      properties:
        id:
          description: The id of the distribution to update.
          type: integer
          format: int64
        status:
          description: The desired status to have for this distribution.
          type:
          - string
          - 'null'
          enum:
          - Ack
          - Nak
          - null
        status_update_message:
          description: An message linked to this update. Only useful when the desired status is 'Nak'
          type: string
          maxLength: 255
      description: A single distribution update information.
    Links:
      type: array
      items:
        description: A single link describing a possible API action
        type: object
        additionalProperties: true
        required:
        - href
        - rel
        - type
        properties:
          href:
            type: string
            maxLength: 256
            format: uri
            description: The URI of the target resource
          rel:
            type: string
            maxLength: 30
            description: How the current resource is linked to the target resource
          type:
            type: string
            enum:
            - POST
            - GET
            - PUT
            - PATCH
            - HEAD
            - DELETE
            description: The HTTP verb to perform the action on the target resource
      description: An array of links describing the possible API actions that can be done for the distribution
    Distribution:
      title: Distribution
      description: An Alliance Cloud distribution
      type: object
      additionalProperties: true
      properties:
        id:
          description: The unique distribution identifier
          type: integer
          format: int64
        service:
          description: The service / protocol for the distribution
          type: string
          enum:
          - fin
          - interAct
          - fileAct
        type:
          description: The distribution type
          type: string
          enum:
          - message
          - deliveryReport
          - deliveryNotification
          - transmissionReport
          - archive
          - export
        distribution_tag:
          description: The tag associated to the distribution
          type: string
          maxLength: 256
        transmission_possible_duplicate:
          description: Whether the distribution has already been tentatively downloaded at least once
          type: boolean
          default: false
        copy:
          description: Whether the distribution is about a copy or an original message
          type: boolean
        message_cloud_reference:
          description: The unique identifier of the message linked to the distribution. For deliveryReport and transmissionReport types, it will be the one of the sent message
          type: string
          format: uuid
        export_content:
          description: Identifies the contents of the export. Currently only 'message' exports are supported by Alliance Cloud
          type: string
          maxLength: 50
        export_format:
          description: Identifies the format of the export. Currently only 'pdf' format is supported by Alliance Cloud
          type: string
          maxLength: 50
        links:
          $ref: '#/components/schemas/Links'
    DistributionsUpdate:
      title: DistributionsUpdate
      type: array
      items:
        $ref: '#/components/schemas/DistributionUpdate'
      description: A collection of distribution update information.
    DistributionUpdateResponse:
      title: DistributionUpdateResponse
      type: object
      additionalProperties: true
      required:
      - id
      - result
      properties:
        id:
          description: The id of the updated distribution.
          type: integer
          format: int64
        result:
          description: The update result. 'OK' indicates that the desired state was reached. The other possible resumt is 'NotFound', if the provided distribution id could not be linked to an existing distribution.
          type: string
          enum:
          - OK
          - NotFound
      description: The result of an update on a distribution.
    Nak:
      title: NAK
      type: object
      additionalProperties: false
      properties:
        reason:
          description: A textual description of the reason for the NAK.
          type: string
          maxLength: 255
      description: Distribution NAK
    ErrorMessage:
      title: Error Message
      description: Structure holding all error messages coming back from Alliance Cloud
      required:
      - code
      - severity
      - text
      type: object
      additionalProperties: true
      properties:
        code:
          description: Identifier of the error
          type: string
        severity:
          description: Severity of the error. Example values are "Fatal", "Transient"
          type: string
        text:
          description: Textual description of the error
          type: string
        user_message:
          description: If applicable, additional message for the application user
          type: string
        more_info:
          description: If applicable, contains a link for more information about the error
          type: string
      example: "{\n  \"code\": \"AC-500\",\n  \"severity\": \"fatal\",\n  \"text\": \"An error occured.\",\n  \"user_message\": \"Message to be passed to the app user, if applicable.\",\n  \"more_info\": \"https://developer.swift.com/AC-500\"\n}"
  examples:
    GetDistributionResponse:
      summary: Get single distributions response
      description: Contents for a single distribution get response
      value:
        id: 44984189500
        service: fin
        type: message
        copy: false
        message_cloud_reference: 6c6cf8b9-9c9c-4ef4-be70-da426c1d19dd
        links:
        - href: https://api.swiftnet.sipn.swift.com/alliancecloud/v2/distributions/44984189500
          rel: self
          type: GET
        - href: https://api.swiftnet.sipn.swift.com/alliancecloud/v2/fin/messages/44984189500
          rel: download
          type: GET
    ListAllDistributionsResponse:
      summary: List Distributions response
      description: Contents for a distribution list response, that can contain multiple entries
      value:
        distributions:
        - id: 44984189498
          service: fin
          type: transmissionReport
          copy: false
          message_cloud_reference: 68f78910-6484-4c20-b73f-8424a20b8e23
          links:
          - href: https://api.swiftnet.sipn.swift.com/alliancecloud/v2/distributions/44984189498
            rel: self
            type: GET
          - href: https://api.swiftnet.sipn.swift.com/alliancecloud/v2/fin/transmission-reports/44984189498
            rel: download
            type: GET
        - id: 44984189500
          service: fin
          type: message
          distribution_tag: fin-high-amount
          copy: false
          transmission_possible_duplicate: true
          message_cloud_reference: 6c6cf8b9-9c9c-4ef4-be70-da426c1d19dd
          links:
          - href: https://api.swiftnet.sipn.swift.com/alliancecloud/v2/distributions/44984189500
            rel: self
            type: GET
          - href: https://api.swiftnet.sipn.swift.com/alliancecloud/v2/fin/messages/44984189500
            rel: download
            type: GET
        - id: 44984189502
          service: interAct
          type: export
          export_content: message
          export_format: pdf
          distribution_tag: printing
          copy: false
          transmission_possible_duplicate: false
          message_cloud_reference: db8a3c28-3f5e-45a6-806a-d6e66f25f164
          links:
          - href: https://api.swiftnet.sipn.swift.com/alliancecloud/v2/distributions/44984189502
            rel: self
            type: GET
          - href: https://api.swiftnet.sipn.swift.com/alliancecloud/v2/interact/exports/44984189502
            rel: download
            type: GET
        links:
        - href: https://api.swiftnet.sipn.swift.com/alliancecloud/v2/distributions?limit=50,offset=100
          rel: self
          type: GET
        - href: https://api.swiftnet.sipn.swift.com/alliancecloud/v2/distributions?limit=50,offset=0
          rel: first
          type: GET
        - href: https://api.swiftnet.sipn.swift.com/alliancecloud/v2/distributions?limit=50,offset=150
          rel: next
          type: GET
        - href: https://api.swiftnet.sipn.swift.com/alliancecloud/v2/distributions?limit=50,offset=50
          rel: previous
          type: GET
        - href: https://api.swiftnet.sipn.swift.com/alliancecloud/v2/distributions?limit=50,offset=950
          rel: last
          type: GET
    DistributionsUpdateResponse:
      summary: Batch distributions update response
      description: Contents for a response following a batch distribution update request. Each valid distribution present in the request has its own result in the response
      value:
      - id: 44984189498
        result: OK
      - id: 44984189499
        result: OK
      - id: 44984189500
        result: NotFound
    NakExampleRequest:
      summary: Nak request
      description: Contents for a single distribution Nak request
      value:
        reason: Unable to contact storage system.
    DistributionsUpdateRequest:
      summary: Batch distributions update request
      description: Contents for a request to update the status for multiple distributions
      value:
      - id: 44984189498
        status: Ack
      - id: 44984189499
        status: Ack
      - id: 44984189500
        status: Nak
        status_update_message: Could not contact storage
    UnexpectedError:
      summary: Unexpected server error
      description: Contents for an unexpected server error response. The 'text' property usually contains a more complete description of what happened
      value:
        code: AC-500
        severity: Fatal
        text: Unexpected error occurred. Try again later and if the problem persists contact SWIFT support
    InvalidRequest:
      summary: Invalid request
      description: Contents for an invalid request error response. The 'text' property contains details about what made the request invalid
      value:
        code: AC-400
        severity: Fatal
        text: The request is invalid. Either a mandatory header is missing or invalid values are provided
    NotFound:
      summary: Not Found
      description: The requested resource cannot be found.
      value:
        code: AC-404
        severity: Fatal
        text: The specified resource was not found
    Forbidden:
      summary: Forbidden
      description: Contents for a forbidden error response. The 'text' property contains details about why the requested action was considered forbidden
      value:
        code: AC-403
        severity: Fatal
        text: The request cannot be processed. There is either no application channel linked to the provided DN or the corresponding application channel is inactive
  responses:
    NotFound:
      description: The specified resource was not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
          examples:
            notFoundError:
              $ref: '#/components/examples/NotFound'
    UnexpectedError:
      description: Unexpected Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
          examples:
            unexpectedError:
              $ref: '#/components/examples/UnexpectedError'
    Forbidden:
      description: Authentication is valid but the corresponding application channel is not active or started
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
          examples:
            forbiddenError:
              $ref: '#/components/examples/Forbidden'
    InvalidRequest:
      description: The request is invalid (missing mandatory header, invalid payload...)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
          examples:
            clientError:
              $ref: '#/components/examples/InvalidRequest'
  securitySchemes:
    oauthBearerToken:
      type: http
      description: "\nThe access token obtained as a result of OAuth 2.0 flows. SWIFT supports two OAuth grant types depending on the API service.\n* JWT-Bearer grant type [RFC 7523](https://tools.ietf.org/html/rfc7523)\n* Password grant type\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."
      scheme: bearer
      bearerFormat: opaque OAuth 2.0