openapi: 3.0.1
info:
  title: Messaging Medallia SMS
  description: The Messaging Medallia SMS API sends outbound SMS messages to specified
    recipients and forwards delivery notifications and inbound SMS messages from existing
    messaging services to Medallia.
  license:
    name: MADAPI
    url: https://developers.mtn.com/
  version: 3.0.0 - Last updated date:2026-09-09 09:06:24
servers:
- url: https://api.mtn.com/v1
  description: Production Server
security:
- OAuth2: []
tags:
- name: Messaging Medallia SMS
paths:
  /messages/medallia/notification:
    post:
      tags:
      - Messaging Medallia SMS
      summary: Forward delivery notification and inbound sms from existing SMS Api
        to Medallia
      description: Forwards SMS delivery notifications and inbound messages from the
        existing MTN messaging API to Medallia for internal processing; this operation
        is not exposed to the Experience Layer.
      operationId: SmsMessaging_post_forwardToMedallia_messagesmedallianoti
      requestBody:
        content:
          application/json:
            schema:
              title: DeliveryReceiptAndInboundMessage
              type: object
              properties:
                messageId:
                  type: string
                senderAddress:
                  type: string
                receiverAddress:
                  type: string
                deliveryStatus:
                  title: DeliveryReceiptState
                  type: object
                  properties:
                    value:
                      type: integer
                      format: int32
                submittedDate:
                  type: string
                  format: date-time
                completedDate:
                  type: string
                  format: date-time
                message:
                  type: string
                clientCorrelator:
                  type: string
                requestId:
                  type: string
                transactionId:
                  type: string
        required: true
      responses:
        "200":
          description: HTTP 200 indicating the request succeeded; the response body
            follows the documented schema for this operation and includes correlation
            identifiers where applicable for traceability across MTN MADAPI Messaging
            Medallia SMS flows.
          content:
            application/json:
              schema:
                title: MedalliaResponse
                type: object
                properties:
                  statusCode:
                    type: string
                  error:
                    type: string
                  message:
                    type: string
                  data:
                    type: array
                    items:
                      title: ResponseData
                      type: object
                      properties:
                        keyword:
                          type: string
                        dataPath:
                          type: string
                        schemaPath:
                          type: string
                        params:
                          title: Params
                          type: object
                          properties:
                            allowedValues:
                              type: array
                              items:
                                type: string
                            message:
                              type: string
        "400":
          description: "Bad request. Invalid request parameters, missing required\
            \ fields, or validation errors."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
              example:
                statusCode: "400"
                statusMessage: "Bad request. Invalid request parameters, missing required\
                  \ fields, or validation errors."
                supportMessage: API_ERROR
                transactionId: "1234567890"
                sequenceNo: "20250115120000001"
                timestamp: 2025-01-15T12:00:00Z
        "401":
          description: "Unauthorized. Invalid or missing authorization credentials,\
            \ insufficient permissions, or authentication failure."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
              example:
                statusCode: "401"
                statusMessage: "Unauthorized. Invalid or missing authorization credentials,\
                  \ insufficient permissions, or authentication failure."
                supportMessage: API_ERROR
                transactionId: "1234567890"
                sequenceNo: "20250115120000001"
                timestamp: 2025-01-15T12:00:00Z
        "403":
          description: Forbidden. Access denied. The request is valid but the server
            refuses to perform it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
              example:
                statusCode: "403"
                statusMessage: Forbidden. Access denied. The request is valid but
                  the server refuses to perform it.
                supportMessage: API_ERROR
                transactionId: "1234567890"
                sequenceNo: "20250115120000001"
                timestamp: 2025-01-15T12:00:00Z
        "404":
          description: Not found. The requested resource was not found or does not
            exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
              example:
                statusCode: "404"
                statusMessage: Not found. The requested resource was not found or
                  does not exist.
                supportMessage: API_ERROR
                transactionId: "1234567890"
                sequenceNo: "20250115120000001"
                timestamp: 2025-01-15T12:00:00Z
        "500":
          description: "Internal server error. Unexpected system failure, database\
            \ connectivity issues, or external service integration problems."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
              example:
                statusCode: "500"
                statusMessage: "Internal server error. Unexpected system failure,\
                  \ database connectivity issues, or external service integration\
                  \ problems."
                supportMessage: API_ERROR
                transactionId: "1234567890"
                sequenceNo: "20250115120000001"
                timestamp: 2025-01-15T12:00:00Z
        "502":
          description: Bad gateway. The server acting as a gateway received an invalid
            response from an upstream server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
              example:
                statusCode: "502"
                statusMessage: Bad gateway. The server acting as a gateway received
                  an invalid response from an upstream server.
                supportMessage: API_ERROR
                transactionId: "1234567890"
                sequenceNo: "20250115120000001"
                timestamp: 2025-01-15T12:00:00Z
        "503":
          description: Service unavailable. The server is temporarily unable to handle
            the request due to maintenance or overload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
              example:
                statusCode: "503"
                statusMessage: Service unavailable. The server is temporarily unable
                  to handle the request due to maintenance or overload.
                supportMessage: API_ERROR
                transactionId: "1234567890"
                sequenceNo: "20250115120000001"
                timestamp: 2025-01-15T12:00:00Z
      deprecated: false
  /messages/medallia/outbound:
    post:
      tags:
      - Messaging Medallia SMS
      summary: Create outgoing SMS request for Medallia
      description: Creates and sends an outbound SMS request to a specified recipient
        through the appropriate MTN messaging service and returns the resulting Medallia
        message identifiers.
      operationId: SmsMessaging_post_outBoundSms_messagesmedalliaoutb
      parameters:
      - name: transactionId
        in: header
        required: false
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              title: MedalliaOutBoundSms
              type: object
              properties:
                recipient:
                  title: Recipient
                  type: object
                  properties:
                    id:
                      type: string
                message:
                  title: Message
                  type: object
                  properties:
                    mid:
                      type: string
                    text:
                      type: string
                notification_type:
                  type: string
        required: true
      responses:
        "200":
          description: HTTP 200 indicating the request succeeded; the response body
            follows the documented schema for this operation and includes correlation
            identifiers where applicable for traceability across MTN MADAPI Messaging
            Medallia SMS flows.
          content:
            application/json:
              schema:
                title: MedalliaOutBoundResponse
                type: object
                properties:
                  message_id:
                    type: string
                  recipient_id:
                    type: string
        "400":
          description: "Bad request. Invalid request parameters, missing required\
            \ fields, or validation errors."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
              example:
                statusCode: "400"
                statusMessage: "Bad request. Invalid request parameters, missing required\
                  \ fields, or validation errors."
                supportMessage: API_ERROR
                transactionId: "1234567890"
                sequenceNo: "20250115120000001"
                timestamp: 2025-01-15T12:00:00Z
        "401":
          description: "Unauthorized. Invalid or missing authorization credentials,\
            \ insufficient permissions, or authentication failure."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
              example:
                statusCode: "401"
                statusMessage: "Unauthorized. Invalid or missing authorization credentials,\
                  \ insufficient permissions, or authentication failure."
                supportMessage: API_ERROR
                transactionId: "1234567890"
                sequenceNo: "20250115120000001"
                timestamp: 2025-01-15T12:00:00Z
        "403":
          description: Forbidden. Access denied. The request is valid but the server
            refuses to perform it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
              example:
                statusCode: "403"
                statusMessage: Forbidden. Access denied. The request is valid but
                  the server refuses to perform it.
                supportMessage: API_ERROR
                transactionId: "1234567890"
                sequenceNo: "20250115120000001"
                timestamp: 2025-01-15T12:00:00Z
        "404":
          description: Not found. The requested resource was not found or does not
            exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
              example:
                statusCode: "404"
                statusMessage: Not found. The requested resource was not found or
                  does not exist.
                supportMessage: API_ERROR
                transactionId: "1234567890"
                sequenceNo: "20250115120000001"
                timestamp: 2025-01-15T12:00:00Z
        "500":
          description: "Internal server error. Unexpected system failure, database\
            \ connectivity issues, or external service integration problems."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
              example:
                statusCode: "500"
                statusMessage: "Internal server error. Unexpected system failure,\
                  \ database connectivity issues, or external service integration\
                  \ problems."
                supportMessage: API_ERROR
                transactionId: "1234567890"
                sequenceNo: "20250115120000001"
                timestamp: 2025-01-15T12:00:00Z
        "502":
          description: Bad gateway. The server acting as a gateway received an invalid
            response from an upstream server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
              example:
                statusCode: "502"
                statusMessage: Bad gateway. The server acting as a gateway received
                  an invalid response from an upstream server.
                supportMessage: API_ERROR
                transactionId: "1234567890"
                sequenceNo: "20250115120000001"
                timestamp: 2025-01-15T12:00:00Z
        "503":
          description: Service unavailable. The server is temporarily unable to handle
            the request due to maintenance or overload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
              example:
                statusCode: "503"
                statusMessage: Service unavailable. The server is temporarily unable
                  to handle the request due to maintenance or overload.
                supportMessage: API_ERROR
                transactionId: "1234567890"
                sequenceNo: "20250115120000001"
                timestamp: 2025-01-15T12:00:00Z
      deprecated: false
components:
  schemas:
    com_mtn_aggregator_models_outBound_Recipient:
      title: Recipient
      type: object
      properties:
        id:
          type: string
    com_mtn_aggregator_models_outBound_Message:
      title: Message
      type: object
      properties:
        mid:
          type: string
        text:
          type: string
    com_mtn_aggregator_models_response_MedalliaOutBoundResponse:
      title: MedalliaOutBoundResponse
      type: object
      properties:
        message_id:
          type: string
        recipient_id:
          type: string
    com_mtn_aggregator_models_response_MedalliaResponse:
      title: MedalliaResponse
      type: object
      properties:
        statusCode:
          type: string
        error:
          type: string
        message:
          type: string
        data:
          type: array
          items:
            title: ResponseData
            type: object
            properties:
              keyword:
                type: string
              dataPath:
                type: string
              schemaPath:
                type: string
              params:
                title: Params
                type: object
                properties:
                  allowedValues:
                    type: array
                    items:
                      type: string
                  message:
                    type: string
    com_mtn_aggregator_models_response_Params:
      title: Params
      type: object
      properties:
        allowedValues:
          type: array
          items:
            type: string
        message:
          type: string
    org_jsmpp_util_DeliveryReceiptState:
      title: DeliveryReceiptState
      type: object
      properties:
        value:
          type: integer
          format: int32
    com_mtn_aggregator_models_response_ResponseData:
      title: ResponseData
      type: object
      properties:
        keyword:
          type: string
        dataPath:
          type: string
        schemaPath:
          type: string
        params:
          title: Params
          type: object
          properties:
            allowedValues:
              type: array
              items:
                type: string
            message:
              type: string
    APIError:
      title: APIError
      required:
      - statusCode
      - statusMessage
      type: object
      properties:
        statusCode:
          type: string
          description: Error status code
        statusMessage:
          type: string
          description: Human-readable error message
        supportMessage:
          type: string
          description: Technical support message or error code for troubleshooting
        transactionId:
          type: string
          description: Transaction identifier for tracking and correlation
        sequenceNo:
          type: string
          description: Sequence number for request tracking
        timestamp:
          type: string
          description: Error timestamp in ISO 8601 format
          format: date-time
        path:
          type: string
          description: API endpoint path where the error occurred
        method:
          type: string
          description: HTTP method of the request that caused the error
        downstreamStatusCode:
          type: string
          description: Downstream service error code if applicable
      description: Generic MADAPI error response structure
    com_mtn_aggregator_models_outBound_MedalliaOutBoundSms:
      title: MedalliaOutBoundSms
      type: object
      properties:
        recipient:
          title: Recipient
          type: object
          properties:
            id:
              type: string
        message:
          title: Message
          type: object
          properties:
            mid:
              type: string
            text:
              type: string
        notification_type:
          type: string
    com_mtn_aggregator_models_outBound_DeliveryReceiptAndInboundMessage:
      title: DeliveryReceiptAndInboundMessage
      type: object
      properties:
        messageId:
          type: string
        senderAddress:
          type: string
        receiverAddress:
          type: string
        deliveryStatus:
          title: DeliveryReceiptState
          type: object
          properties:
            value:
              type: integer
              format: int32
        submittedDate:
          type: string
          format: date-time
        completedDate:
          type: string
          format: date-time
        message:
          type: string
        clientCorrelator:
          type: string
        requestId:
          type: string
        transactionId:
          type: string
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.mtn.com/v1/oauth/access_token
          scopes: {}
    Bearer:
      type: http
      description: Bearer token received from OAuth2.0 authentication with the MADAPI
      scheme: bearer
      bearerFormat: JWT