openapi: 3.0.1 info: title: Messaging SMS description: "Messaging SMS : Allows 3PPs to consume MTN's SMS services. MTN Messaging\ \ SMS API allowing developers to include SMS messaging in their applications.\ \ Provides a RESTful API to expose SMS capability" license: name: MADAPI url: https://developers.mtn.com/ version: 3.0.0 - Last updated date:2026-09-10 07:23:36 servers: - url: https://api.mtn.com/v1 description: Production Server security: - OAuth2: [] tags: - name: Messaging SMS paths: /messages/sms/outbound: post: tags: - Messaging SMS summary: Send an outbound SMS message description: Sends an outbound SMS message from the supplied sender address to one or more receiver addresses and returns a request identifier for tracking delivery status. operationId: SmsMessaging_post_outBoundSms_messagessmsoutbound parameters: - name: Content-Type in: header required: false schema: type: string - name: transactionId in: header required: false schema: type: string requestBody: content: application/json: schema: title: OutboundSMSMessageRequest required: - clientCorrelator - message - senderAddress type: object properties: senderAddress: type: string cpAddress: type: string receiverAddress: type: array items: type: string message: type: string clientCorrelator: 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 SMS flows. content: application/json: schema: title: OutboundSMSMessageResponse type: object properties: statusCode: type: string statusMessage: type: string transactionId: type: string data: title: OutboundData type: object properties: requestId: type: string clientCorrelator: type: string planId: type: string serviceId: type: string serviceType: type: string isChargeable: type: string verificationFlagValue: type: string receiverAddress: type: array items: type: string summary: type: object additionalProperties: type: object "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/sms/outbound/{senderAddress}/subscription: post: tags: - Messaging SMS summary: Create an SMS delivery notification subscription description: Creates a subscription that forwards SMS delivery notifications to the specified third-party callback URL when delivery updates are received. operationId: SmsMessaging_post_subscribe_messagessmsoutbounds parameters: - name: senderAddress in: path required: true schema: type: string - name: transactionId in: header required: true schema: type: string - name: x-country-code in: header required: true schema: type: string requestBody: content: application/json: schema: title: DeliveryReceiptSubscription type: object properties: notifyUrl: type: string description: Third-party callback URL to which SMS delivery-status notifications will be sent. targetSystem: 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 SMS flows. content: application/json: schema: title: SubscriptionResponse type: object properties: statusCode: type: string statusMessage: type: string transactionId: type: string data: title: SubscriptionData type: object properties: 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 /messages/sms/outbound/{senderAddress}/subscription/{subscriptionId}: delete: tags: - Messaging SMS summary: Delete an SMS delivery notification subscription description: Deletes an existing SMS delivery notification subscription and stops forwarding subsequent delivery updates to the associated third-party application. operationId: SmsMessaging_delete_unSubscribe_messagessmsoutbounds parameters: - name: senderAddress in: path required: true schema: type: string - name: subscriptionId in: path required: true schema: type: string - name: transactionId in: header required: true schema: type: string - name: x-country-code in: header required: true schema: type: string 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 SMS flows. content: application/json: schema: $ref: '#/components/schemas/com_mtn_aggregator_models_response_SubscriptionResponse' "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/sms/outbound/{senderAddress}/{requestId}/deliveryStatus: get: tags: - Messaging SMS summary: Retrieve outbound SMS delivery status description: Retrieves the delivery status for one or more SMS messages associated with the supplied sender address and outbound request identifier. operationId: SmsMessaging_get_deliveryStatus_messagessmsoutbounds parameters: - name: requestId in: path required: true schema: type: string - name: senderAddress in: path required: true schema: type: string - name: transactionId in: header required: false schema: type: string 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 SMS flows. content: application/json: schema: title: DeliveryStatusResponse type: object properties: statusCode: type: string statusMessage: type: string transactionId: type: string data: title: DeliveryInfo type: object properties: requestId: type: string clientCorrelator: type: string deliveryStatus: type: array items: title: DeliveryStatus type: object properties: receiverAddress: type: string status: 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/sms/subscribedsms/outbound: post: tags: - Messaging SMS summary: Send an outbound SMS through Subscription Manager description: Requests Subscription Manager to send an outbound SMS message from the supplied sender address to one or more specified receiver addresses. operationId: SmsMessaging_post_subscribedSMS_messagessmssubscribe parameters: - name: transactionId in: header required: false schema: type: string requestBody: content: application/json: schema: title: OutboundSubscribedSMSMessageRequest required: - clientCorrelator - message - senderAddress type: object properties: planId: type: string serviceType: type: string serviceNode: type: string startTime: type: string isChargeable: type: boolean isVerificationRequired: type: boolean senderAddress: type: string cpAddress: type: string receiverAddress: type: array items: type: string message: type: string clientCorrelator: 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 SMS flows. content: application/json: schema: $ref: '#/components/schemas/com_mtn_aggregator_models_response_OutboundSMSMessageResponse' "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_delivery_DeliveryInfo: title: DeliveryInfo type: object properties: requestId: type: string clientCorrelator: type: string deliveryStatus: type: array items: title: DeliveryStatus type: object properties: receiverAddress: type: string status: type: string com_mtn_aggregator_models_outBound_DeliveryReceiptSubscription: title: DeliveryReceiptSubscription type: object properties: notifyUrl: type: string description: Third-party callback URL to which SMS delivery-status notifications will be sent. targetSystem: type: string com_mtn_aggregator_models_outBound_OutboundSMSMessageRequest: title: OutboundSMSMessageRequest required: - clientCorrelator - message - senderAddress type: object properties: senderAddress: type: string cpAddress: type: string receiverAddress: type: array items: type: string message: type: string clientCorrelator: type: string com_mtn_aggregator_models_outBound_OutboundSubscribedSMSMessageRequest: title: OutboundSubscribedSMSMessageRequest required: - clientCorrelator - message - senderAddress type: object properties: planId: type: string serviceType: type: string serviceNode: type: string startTime: type: string isChargeable: type: boolean isVerificationRequired: type: boolean senderAddress: type: string cpAddress: type: string receiverAddress: type: array items: type: string message: type: string clientCorrelator: type: string com_mtn_aggregator_models_response_DeliveryStatusResponse: title: DeliveryStatusResponse type: object properties: statusCode: type: string statusMessage: type: string transactionId: type: string data: title: DeliveryInfo type: object properties: requestId: type: string clientCorrelator: type: string deliveryStatus: type: array items: title: DeliveryStatus type: object properties: receiverAddress: type: string status: type: string com_mtn_aggregator_models_outBound_OutboundData: title: OutboundData type: object properties: requestId: type: string clientCorrelator: type: string planId: type: string serviceId: type: string serviceType: type: string isChargeable: type: string verificationFlagValue: type: string receiverAddress: type: array items: type: string com_mtn_aggregator_models_delivery_DeliveryStatus: title: DeliveryStatus type: object properties: receiverAddress: type: string status: type: string com_mtn_aggregator_models_response_OutboundSMSMessageResponse: title: OutboundSMSMessageResponse type: object properties: statusCode: type: string statusMessage: type: string transactionId: type: string data: title: OutboundData type: object properties: requestId: type: string clientCorrelator: type: string planId: type: string serviceId: type: string serviceType: type: string isChargeable: type: string verificationFlagValue: type: string receiverAddress: type: array items: type: string summary: type: object additionalProperties: type: object 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_response_SubscriptionData: title: SubscriptionData type: object properties: id: type: string com_mtn_aggregator_models_response_SubscriptionResponse: title: SubscriptionResponse type: object properties: statusCode: type: string statusMessage: type: string transactionId: type: string data: title: SubscriptionData type: object properties: id: 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