openapi: 3.0.3
info:
  title: Appian Adapter for Swift API
  description: |
    The Appian Adapter for Swift API enables integration with the Appian Adapter for Swift
    for processing inbound and outbound Swift MT and MX messages and managing Swift Case Manager
    investigations.

    All endpoints require API key authentication via the `appian-api-key` header.
  version: 1.0.0
  contact:
    name: Appian Support
    url: https://forum.appian.com/suite/sites/myappian/page/support
    email: support@appian.com

servers:
  - url: https://{environment}.appiancloud.com/suite
    description: Appian Cloud environment
    variables:
      environment:
        default: your-environment
        description: Your Appian Cloud environment subdomain

security:
  - ApiKeyAuth: []

tags:
  - name: Inbound Messages
    description: Receive and process inbound Swift MT and MX messages
  - name: Outbound Messages
    description: Convert structured data to Swift messages and send outbound
  - name: Swift Case Management
    description: Create, update, and query Swift Case Manager investigations

paths:
  /webapi/inbound-messages:
    post:
      operationId: receiveInboundMessage
      summary: Receive an inbound Swift message
      description: |
        Receives a raw Swift MT or MX message for validation, parsing, and conversion
        into a structured Appian data object. The message is processed asynchronously.
        Use the returned `messageId` to poll for processing status.
      tags:
        - Inbound Messages
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InboundMessageRequest'
            example:
              content: "{1:F01BANKUS33XXXX0000000000}{2:O1030911241224BANKUS33XXXX00000000002412240411N}{3:{121:c9ea53ee-24a2-4394-95d2-d2f75910e0b6}}{4:\\n:20:IE24122335167549\\n:23B:CRED\\n:32A:241227CAD50,00\\n:50K:/12345678\\nJOHN DOE\\n:59:/1234567\\nJANE DOE\\n:71A:SHA\\n-}{5:{CHK:5ABEA653B919}}"
              timestamp: "2026-05-22T22:51:00.000Z"
              source: "upstream-system"
              sourceFields:
                caseId: "CASE-12345"
                priority: "high"
              validateBic: true
      responses:
        '200':
          description: Message received and queued for processing.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InboundMessageResponse'
        '400':
          description: Bad request. The payload is empty or malformed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized. Invalid or missing API key.
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /webapi/outbound-messages:
    post:
      operationId: sendOutboundMessage
      summary: Send an outbound Swift message
      description: |
        Receives a structured Appian data object, converts it to a valid Swift MT or MX
        message, validates the message, and sends it to the configured upstream channel.
        The `content` field contains the message-type-specific payload structured as JSON.
      tags:
        - Outbound Messages
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OutboundMessageRequest'
            example:
              content:
                messageType: "camt.057.001.06"
                content:
                  groupHeader:
                    messageId: "CAMT057-MSG-001"
                    creationDateTime: "2026-01-29T09:00:00Z"
                    messageSender:
                      agent:
                        bic: "BANKUS33XXX"
                  notification:
                    id: "NTFCTN-2026-001"
                    totalAmount:
                      currency: "USD"
                      amount: "25000.00"
              swiftVersion: "2025"
              source: "downstream-app"
              destination: "target-system"
              ignoreValidation: false
              validateBic: true
      responses:
        '200':
          description: Message created, validated, and sent successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OutboundMessageResponse'
        '400':
          description: Bad request. Validation failed or payload is malformed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized. Invalid or missing API key.
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /webapi/transform-and-validate:
    post:
      operationId: transformAndValidateMessage
      summary: Transform and validate an outbound Swift message
      description: |
        Works like the Outbound Messages API, but instead of sending the message
        to a destination, it transforms the structured data into a Swift message,
        validates it, and returns the result to the caller. Use this endpoint to
        verify whether a payload produces a valid Swift message before sending.
      tags:
        - Outbound Messages
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransformAndValidateRequest'
            example:
              content:
                messageType: "pacs.008.001.08"
                content:
                  groupHeader:
                    messageId: "PACS008-MSG-001"
                    creationDateTime: "2026-01-29T09:00:00Z"
              swiftVersion: "2025"
              source: "downstream-app"
              validateBic: true
      responses:
        '200':
          description: Message is valid. Returns the generated Swift message.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransformAndValidateResponse'
        '400':
          description: Content field is empty.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransformAndValidateErrorResponse'
        '401':
          description: Unauthorized. Invalid or missing API key.
        '422':
          description: Transformation error, validation error, or message is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransformAndValidateErrorResponse'

  /webapi/case-manager-requests:
    post:
      operationId: submitCaseManagerRequest
      summary: Submit a Swift Case Manager request
      description: |
        Creates, updates, or queries a Swift Case Manager investigation case.
        Supported case types: CCNR (Claim Non-Receipt, also covers CONR),
        UTAP (Unable to Apply), GSRP (GPI Stop and Recall),
        RQFI UTEX (Request for Information), and INV_ACTION (Request Action).
      tags:
        - Swift Case Management
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CaseManagerRequest'
            example:
              source: "EPI"
              caseType: "CCNR"
              caseAction: "CREATE"
              content:
                from: "BANKUS33"
                sendersReference: "MessageID1"
                requestorInvestigationId: "ReqInvID1"
                investigationType: "CCNR"
                underlyingInstrument: "XBCT"
                underlying:
                  interbank:
                    originalMessageId: "OrigMessageID1"
                    originalMessageNameId: "pacs.008.001.08"
                    originalCreationDateTime: "2024-01-21T04:48:10.0+01:00"
                    originalUETR: "20ebf92f-4e95-4359-9bc0-3bb9f9507605"
                    originalSettlementAmount:
                      currency: "USD"
                      amount: "100000"
                    originalSettlementDate: "2024-01-21"
                requestor: "BANKUS33"
                responder: "BANKFRPP"
                investigationReason: "CCNR"
              validateBic: false
      responses:
        '200':
          description: Case Manager request processed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CaseManagerResponse'
        '400':
          description: Bad request. Validation failed or payload is malformed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized. Invalid or missing API key.
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: appian-api-key
      description: API key for authenticating requests to the Appian Adapter for Swift.

  schemas:
    # ============================================================
    # INBOUND MESSAGE SCHEMAS
    # ============================================================
    InboundMessageRequest:
      type: object
      required:
        - content
        - timestamp
        - source
        - sourceFields
      properties:
        content:
          type: string
          description: |
            The raw Swift message content. For MT messages, this is the full FIN message
            string including all blocks (1-5). For MX messages, this is the XML content.
          example: "{1:F01BANKUS33XXXX...}{4:\\n:20:REF123\\n...}"
        timestamp:
          type: string
          format: date-time
          description: ISO 8601 timestamp of when the message was sent by the source system.
          example: "2026-05-22T22:51:00.000Z"
        source:
          type: string
          description: Identifier of the source system sending the message.
          example: "IBM-MQ-Gateway"
        sourceFields:
          type: array
          items:
            type: object
            additionalProperties:
              type: string
          description: |
            Additional metadata key-value pairs from the source system.
            Must not be empty.
          example:
            caseId: "CASE-12345"
            priority: "high"
        validateBic:
          type: boolean
          description: |
            Whether to validate BIC codes in the message against the BIC reference database.
            Set to `false` if BIC validation is not required or BIC data has not been ingested.
          default: false

    InboundMessageResponse:
      type: object
      properties:
        messageId:
          type: string
          format: uuid
          description: The unique identifier assigned to the received message.
          example: "550e8400-e29b-41d4-a716-446655440000"
        status:
          type: string
          description: |
            The status of the message upon receipt. Possible values:
            - `INBD_STTS_RCVD`: Message received successfully.
            - `INBD_STTS_ERR-001`: Error persisting message or starting processing.
            - `INBD_STTS_ERR-004`: Request body was empty.
          enum:
            - INBD_STTS_RCVD
            - INBD_STTS_ERR-001
            - INBD_STTS_ERR-004
          example: "INBD_STTS_RCVD"

    # ============================================================
    # OUTBOUND MESSAGE SCHEMAS
    # ============================================================
    OutboundMessageRequest:
      type: object
      required:
        - content
        - source
      properties:
        content:
          type: object
          required:
            - messageType
            - content
          description: |
            The structured message payload. Contains the message type identifier and
            the message-type-specific content as a nested JSON object.
          properties:
            messageType:
              type: string
              description: |
                The Swift message type identifier. For MX messages, use the ISO 20022
                message identifier (e.g., `pacs.008.001.08`, `camt.057.001.06`).
                For MT messages, use the MT type number (e.g., `MT103`, `MT202`).
              example: "camt.057.001.06"
            content:
              type: object
              description: |
                The message-type-specific content. The structure of this object varies
                by message type. See the companion file `message-type-schemas.yaml` for
                the full field definitions of each supported message type.
              additionalProperties: true
        swiftVersion:
          type: string
          description: |
            The Swift standards version to use for message generation and validation.
            Determines which Prowide library version is applied.
          # NOTE: Update this enum each year to align with the latest Swift Standards Release.
          enum:
            - "2025"
            - "2026"
          default: "2025"
          example: "2025"
        source:
          type: string
          description: Identifier of the system sending the outbound request.
          example: "payment-investigation-app"
        destination:
          type: string
          description: |
            The target system or channel for the outbound message.
            This is a free-form string; any value can be passed through this field.
          example: "swift-network"
        destinationFields:
          type: array
          items:
            type: object
            additionalProperties:
              type: string
          description: Additional metadata key-value pairs for the destination.
        ignoreValidation:
          type: boolean
          description: |
            If `true`, skips Swift message validation before sending.
            Use with caution — invalid messages may be rejected by the Swift network.
          default: false
        validateBic:
          type: boolean
          description: |
            Whether to validate BIC codes in the outbound message against the
            BIC reference database.
          default: false

    OutboundMessageResponse:
      type: object
      description: Response returned when an outbound message is processed.
      properties:
        messageId:
          type: string
          format: uuid
          description: The unique identifier assigned to the outbound message.
        status:
          type: string
          description: The processing status of the outbound message.
          enum:
            - RCVD
            - ERR-001
            - ERR-002
          example: "RCVD"
        error:
          type: string
          nullable: true
          description: Error message, or null on success.
        content:
          type: object
          nullable: true
          description: Additional content returned by the service, or null.

    # ============================================================
    # TRANSFORM AND VALIDATE SCHEMAS
    # ============================================================
    TransformAndValidateRequest:
      type: object
      required:
        - content
      properties:
        content:
          type: object
          required:
            - messageType
            - content
          description: |
            Same structure as the Outbound Messages API content field.
            Contains the message type identifier and the message-type-specific payload.
            See the companion file `message-type-schemas.yaml` for the full field
            definitions of each supported message type.
          properties:
            messageType:
              type: string
              description: The Swift message type identifier.
              example: "pacs.008.001.08"
            content:
              type: object
              description: The message-type-specific content.
              additionalProperties: true
        source:
          type: string
          description: Identifier of the calling system.
          example: "downstream-app"
        swiftVersion:
          type: string
          description: |
            The Swift standards version to use.
          # NOTE: Update this enum each year to align with the latest Swift Standards Release.
          enum:
            - "2025"
            - "2026"
          default: "2025"
        validateBic:
          type: boolean
          description: Whether to validate BIC codes against the BIC reference database.
          default: false

    TransformAndValidateResponse:
      type: object
      description: Successful response when the message is valid.
      properties:
        errorOccurred:
          type: boolean
          description: Whether an error occurred during processing.
          example: false
        isValid:
          type: boolean
          description: Whether the generated Swift message passed validation.
          example: true
        error:
          type: string
          nullable: true
          description: Error message, or null on success.
        transformationResult:
          type: object
          properties:
            Result:
              type: string
              description: The generated Swift message string.
            errorOccurred:
              type: boolean
        validationResult:
          type: object
          properties:
            isValid:
              type: boolean
            errorOccurred:
              type: boolean
        swiftMessage:
          type: string
          description: The final validated Swift message string.

    TransformAndValidateErrorResponse:
      type: object
      description: Error response for 400 or 422 status codes.
      properties:
        errorOccurred:
          type: boolean
          description: Whether an error occurred during processing.
        isValid:
          type: boolean
          description: Always false for error responses.
          example: false
        error:
          type: string
          nullable: true
          description: Error message describing the failure.
        transformationResult:
          type: object
          nullable: true
          properties:
            Result:
              type: string
              nullable: true
            errorOccurred:
              type: boolean
        validationResult:
          type: object
          nullable: true
          properties:
            isValid:
              type: boolean
            errorOccurred:
              type: boolean
            Error:
              type: string
              nullable: true
            validationProblems:
              type: array
              nullable: true
              items:
                type: object
                properties:
                  errorKey:
                    type: string
                  Message:
                    type: string
                  jsonField:
                    type: string
        swiftMessage:
          type: string
          nullable: true
          description: Always null for error responses.

    # ============================================================
    # CASE MANAGEMENT SCHEMAS
    # ============================================================
    CaseManagerRequest:
      type: object
      required:
        - source
      description: |
        Supports two usage patterns:
        1. Flat mode: Provide `caseType`, `caseAction`, and `content` separately.
        2. MX mode: Provide `mxContent` with the normalized MX message structure.
           When using `mxContent`, the module determines the case type and action
           automatically from the message type. The `content`, `caseType`, and
           `caseAction` fields can be empty or omitted.
      properties:
        source:
          type: string
          description: The source system initiating the case request.
          example: "EPI"
        caseType:
          type: string
          description: |
            The type of Swift Case Manager investigation.
            Required when using flat mode. Omit when using `mxContent`.
          enum:
            - CCNR
            - UTAP
            - GSRP
            - RQFI
            - INV_ACTION
          example: "CCNR"
        caseAction:
          type: string
          description: |
            The action to perform on the case.
            Required when using flat mode. Omit when using `mxContent`.
          enum:
            - CREATE
            - UPDATE
            - QUERY
            - CANCELLATION_STATUS
            - CHANGED_CANCELLATIONS
            - PARTIES
            - CANCELLATION
          example: "CREATE"
        content:
          type: object
          nullable: true
          description: |
            The case-type-specific content payload. Structure varies by case type and action.
            See the companion file `scm-content-schemas.yaml` for the full field definitions
            of each caseType/caseAction combination.
            Required when using flat mode. Set to null when using `mxContent`.
          additionalProperties: true
        mxContent:
          type: object
          nullable: true
          description: |
            Alternative to `content` + `caseType` + `caseAction`. Provides the normalized
            MX message structure directly. The module determines the case type and action
            from the message type. Supported message types: `camt.110.001.01`,
            `camt.111.001.02`, `camt.029.001.09`, `camt.056.001.08`.
            See `scm-content-schemas.yaml` for the full structure of each message type.
          properties:
            messageType:
              type: string
              description: |
                The ISO 20022 message type identifier that determines the case type
                and action. Supported values: `camt.110.001.01` (investigation request),
                `camt.111.001.02` (investigation response), `camt.029.001.09`
                (resolution of investigation), `camt.056.001.08` (cancellation request).
              enum:
                - "camt.110.001.01"
                - "camt.111.001.02"
                - "camt.029.001.09"
                - "camt.056.001.08"
              example: "camt.110.001.01"
            content:
              type: object
              description: |
                The normalized MX message content. Structure varies by message type.
                See the `ScmRequest_*` schemas in `scm-content-schemas.yaml`.
              additionalProperties: true
        validateBic:
          type: boolean
          default: false

    CaseManagerResponse:
      type: object
      description: Response returned when a Case Manager request is processed successfully.
      properties:
        messageId:
          type: string
          format: uuid
          description: The unique identifier assigned to the request.
        status:
          type: string
          description: Status of the case operation.
          example: "SUCCESS"
        error:
          type: string
          nullable: true
          description: Error message, or null on success.
        content:
          type: object
          nullable: true
          description: Dictionary of results from the service, varies by caseType and caseAction.

    # SHARED SCHEMAS
    # ============================================================
    CurrencyAmount:
      type: object
      properties:
        currency:
          type: string
          description: ISO 4217 currency code.
          pattern: "^[A-Z]{3}$"
          example: "USD"
        amount:
          type: string
          description: Amount as a decimal string.
          example: "25000.00"

    ErrorResponse:
      type: object
      properties:
        messageId:
          type: string
          format: uuid
          description: The message ID if one was assigned before the error occurred.
        status:
          type: string
          description: Error status indicator.
          example: "error"
        error:
          type: string
          description: Human-readable error message.
          example: "The content of the Swift message cannot be empty."
        errorCode:
          type: string
          description: |
            Machine-readable error code. See Error Codes and Troubleshooting
            for the full list of error codes.
          example: "ERR-002"

    # ============================================================
    # CUSTOMER-BUILT API SCHEMAS
    # These APIs are not provided by the adapter. Customers must implement
    # them so that the adapter can deliver processed messages.
    # ============================================================
    CustomerInboundMessageRequest:
      type: object
      description: |
        Request body that the adapter sends to the customer's inbound message endpoint.
        The customer must build an API that accepts this structure.
      required:
        - ssmUuid
        - issueOccured
        - issueCount
        - messageType
        - content
        - swiftMessage
      properties:
        ssmUuid:
          type: string
          format: uuid
          description: UUID for the message in the adapter.
        issueOccured:
          type: boolean
          description: True if there were any issues in validation or transformation.
        issueCount:
          type: integer
          description: The number of issues encountered.
        issues:
          type: array
          description: List of issues encountered during processing.
          items:
            type: object
            properties:
              type:
                type: string
                enum:
                  - ERROR
                  - PROBLEM
                description: The severity of the issue.
              category:
                type: string
                enum:
                  - VALIDATION
                  - CONVERSION
                  - TRANSFORMATION
                description: Where the issue occurred in processing.
              message:
                type: string
                description: Detailed error message.
        messageType:
          type: string
          description: The MT or MX message type.
          example: "pacs.008.001.08"
        messageVersion:
          type: string
          description: The version of the Swift message.
          example: "2025"
        content:
          type: object
          description: |
            The structured message. See `message-type-schemas.yaml` for the
            full field definitions of each supported message type.
          additionalProperties: true
        source:
          type: string
          description: The source system.
        sourceFields:
          type: array
          items:
            type: object
            additionalProperties:
              type: string
          description: Additional metadata key-value pairs.
        swiftMessage:
          type: string
          description: The original Swift message.

    CustomerOutboundMessageRequest:
      type: object
      description: |
        Request body that the adapter sends to the customer's outbound message endpoint.
        The customer must build an API that accepts this structure.
      required:
        - ssmUuid
        - content
      properties:
        ssmUuid:
          type: string
          format: uuid
          description: UUID for the message in the adapter.
        content:
          type: string
          description: The generated Swift message.
        destination:
          type: string
          description: Target system or channel.
        destinationMetadata:
          type: array
          items:
            type: object
            additionalProperties:
              type: string
          description: Additional metadata key-value pairs.

    CustomerOutboundMessageResponse:
      type: object
      description: |
        Expected response body from the customer's outbound message endpoint.
      properties:
        confirmationUuid:
          type: string
          format: uuid
          description: UUID from the upstream system to confirm the message was received.
        errorMessage:
          type: string
          nullable: true
          description: If there was an error, return the error message in this field.