MTN SMS V2

AVAILABLE IN

Ghana Nigeria Eswatini South Africa Zambia

Download

Download Postman collection Download Swagger

Available endpoints

POST v2/messages/sms/outbound

Description

This interface is used to send an SMS to the specified address(s).

Header parameters

Content-Type application/json

Auth parameters

oauth2 Authorization

FormData parameters

senderAddress string required
It is the MSISDN or virtual MSIDN of the sender.
receiverAddress array required
This an array of the subscriber MSISDN(s) that the SMS is being sent to. The value is represented as International ITU-T E.164. If more than one address is used the values will be comma separated. Current supported length is one. This means a client may not send an SMS to more than one receiver at a time.
message string required
The message being sent. The standard limit of the size of the message is 160 characters.
clientCorrelator string
It uniquely identifies the request.
201Created
statusCode string
This is the MADAPI Canonical Error Code (it is 4 characters long and it is not the HTTP Status Code which is 3 characters long). Back-end system errors are mapped to specific canonical error codes which are returned. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes'
statusMessage string
More details and corrective actions related to the error which can be shown to a client.
transactionId string
MADAPI generated Id to include for tracing requests
data
requestId string
Unique identifier for the request
clientCorrelator string
field used by client to track
_link
self
href string
{
    "statusCode": [],
    "statusMessage": [],
    "transactionId": [],
    "data": [],
    "_link": []
}
401Unauthorized
statusCode string
This is the MADAPI Canonical Error Code (it is 4 characters long and it is not the HTTP Status Code which is 3 characters long). Back-end system errors are mapped to specific canonical error codes which are returned. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes'
statusMessage string
More details and corrective actions related to the error which can be shown to a client
supportMessage string
Internal message meant for consumers of the API to troubleshoot the error (could possible include the back-end system error code in the message if it would be useful)
transactionId string
MADAPI generated Id to include for tracing requests
timestamp string
Timestamp that the error occurred
path string
The path that caused the error
method string
The HTTP method type that was used
{
    "statusCode": [],
    "statusMessage": [],
    "supportMessage": [],
    "transactionId": [],
    "timestamp": [],
    "path": [],
    "method": []
}
404Not Found
statusCode string
This is the MADAPI Canonical Error Code (it is 4 characters long and it is not the HTTP Status Code which is 3 characters long). Back-end system errors are mapped to specific canonical error codes which are returned. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes'
statusMessage string
More details and corrective actions related to the error which can be shown to a client
supportMessage string
Internal message meant for consumers of the API to troubleshoot the error (could possible include the back-end system error code in the message if it would be useful)
transactionId string
MADAPI generated Id to include for tracing requests
timestamp string
Timestamp that the error occurred
path string
The path that caused the error
method string
The HTTP method type that was used
{
    "statusCode": [],
    "statusMessage": [],
    "supportMessage": [],
    "transactionId": [],
    "timestamp": [],
    "path": [],
    "method": []
}
407Proxy Authentication Required
statusCode string
This is the MADAPI Canonical Error Code (it is 4 characters long and it is not the HTTP Status Code which is 3 characters long). Back-end system errors are mapped to specific canonical error codes which are returned. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes'
statusMessage string
More details and corrective actions related to the error which can be shown to a client
supportMessage string
Internal message meant for consumers of the API to troubleshoot the error (could possible include the back-end system error code in the message if it would be useful)
transactionId string
MADAPI generated Id to include for tracing requests
timestamp string
Timestamp that the error occurred
path string
The path that caused the error
method string
The HTTP method type that was used
{
    "statusCode": [],
    "statusMessage": [],
    "supportMessage": [],
    "transactionId": [],
    "timestamp": [],
    "path": [],
    "method": []
}
500Internal Server Error
statusCode string
This is the MADAPI Canonical Error Code (it is 4 characters long and it is not the HTTP Status Code which is 3 characters long). Back-end system errors are mapped to specific canonical error codes which are returned. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes'
statusMessage string
More details and corrective actions related to the error which can be shown to a client
supportMessage string
Internal message meant for consumers of the API to troubleshoot the error (could possible include the back-end system error code in the message if it would be useful)
transactionId string
MADAPI generated Id to include for tracing requests
timestamp string
Timestamp that the error occurred
path string
The path that caused the error
method string
The HTTP method type that was used
{
    "statusCode": [],
    "statusMessage": [],
    "supportMessage": [],
    "transactionId": [],
    "timestamp": [],
    "path": [],
    "method": []
}
GET v2/messages/sms/outbound/{senderAddress}/{requestId}/deliveryStatus

Description

This interface is used to query the delivery status of an SMS or list of SMSes that were sent in one resquest.

Header parameters

Content-Type application/json

Auth parameters

oauth2 Authorization
200OK
statusCode string
This is the MADAPI Canonical Error Code (it is 4 characters long and it is not the HTTP Status Code which is 3 characters long). Back-end system errors are mapped to specific canonical error codes which are returned. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes'
statusMessage string
More details and corrective actions related to the error which can be shown to a client.
transactionId string
MADAPI generated Id to include for tracing requests
data
requestId string
Identifier used to link the delivery notification to the message sent
clientCorrelator string
Identifier passed by client when sending the message
receiverAddress string
Subscriber MSISDN
deliveryStatus string
DeliveredToTerminal,DeliveryUncertain,DeliveryImpossible,MessageWaiting,DeliveredToNetwork,DeliveryNotificationNotSupported
_link
self
href string
{
    "statusCode": [],
    "statusMessage": [],
    "transactionId": [],
    "data": [],
    "_link": []
}
401Unauthorized
statusCode string
This is the MADAPI Canonical Error Code (it is 4 characters long and it is not the HTTP Status Code which is 3 characters long). Back-end system errors are mapped to specific canonical error codes which are returned. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes'
statusMessage string
More details and corrective actions related to the error which can be shown to a client
supportMessage string
Internal message meant for consumers of the API to troubleshoot the error (could possible include the back-end system error code in the message if it would be useful)
transactionId string
MADAPI generated Id to include for tracing requests
timestamp string
Timestamp that the error occurred
path string
The path that caused the error
method string
The HTTP method type that was used
{
    "statusCode": [],
    "statusMessage": [],
    "supportMessage": [],
    "transactionId": [],
    "timestamp": [],
    "path": [],
    "method": []
}
404Not Found
statusCode string
This is the MADAPI Canonical Error Code (it is 4 characters long and it is not the HTTP Status Code which is 3 characters long). Back-end system errors are mapped to specific canonical error codes which are returned. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes'
statusMessage string
More details and corrective actions related to the error which can be shown to a client
supportMessage string
Internal message meant for consumers of the API to troubleshoot the error (could possible include the back-end system error code in the message if it would be useful)
transactionId string
MADAPI generated Id to include for tracing requests
timestamp string
Timestamp that the error occurred
path string
The path that caused the error
method string
The HTTP method type that was used
{
    "statusCode": [],
    "statusMessage": [],
    "supportMessage": [],
    "transactionId": [],
    "timestamp": [],
    "path": [],
    "method": []
}
407Proxy Authentication Required
statusCode string
This is the MADAPI Canonical Error Code (it is 4 characters long and it is not the HTTP Status Code which is 3 characters long). Back-end system errors are mapped to specific canonical error codes which are returned. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes'
statusMessage string
More details and corrective actions related to the error which can be shown to a client
supportMessage string
Internal message meant for consumers of the API to troubleshoot the error (could possible include the back-end system error code in the message if it would be useful)
transactionId string
MADAPI generated Id to include for tracing requests
timestamp string
Timestamp that the error occurred
path string
The path that caused the error
method string
The HTTP method type that was used
{
    "statusCode": [],
    "statusMessage": [],
    "supportMessage": [],
    "transactionId": [],
    "timestamp": [],
    "path": [],
    "method": []
}
500Internal Server Error
statusCode string
This is the MADAPI Canonical Error Code (it is 4 characters long and it is not the HTTP Status Code which is 3 characters long). Back-end system errors are mapped to specific canonical error codes which are returned. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes'
statusMessage string
More details and corrective actions related to the error which can be shown to a client
supportMessage string
Internal message meant for consumers of the API to troubleshoot the error (could possible include the back-end system error code in the message if it would be useful)
transactionId string
MADAPI generated Id to include for tracing requests
timestamp string
Timestamp that the error occurred
path string
The path that caused the error
method string
The HTTP method type that was used
{
    "statusCode": [],
    "statusMessage": [],
    "supportMessage": [],
    "transactionId": [],
    "timestamp": [],
    "path": [],
    "method": []
}
POST v2/messages/sms/outbound/{senderAddress}/subscription

Description

This interface will start the server to send notifications to third party apps when SMS delivery notifications are received.

Header parameters

Content-Type application/json

Auth parameters

oauth2 Authorization

FormData parameters

notifyUrl string required
targetSystem string required
201Created
statusCode string
This is the MADAPI Canonical Error Code (it is 4 characters long and it is not the HTTP Status Code which is 3 characters long). Back-end system errors are mapped to specific canonical error codes which are returned. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes'
statusMessage string
More details and corrective actions related to the error which can be shown to a client.
transactionId string
MADAPI generated Id to include for tracing requests
data
subscriptionId string
Unique identifier for the subscription
_link
self
href string
{
    "statusCode": [],
    "statusMessage": [],
    "transactionId": [],
    "data": [],
    "_link": []
}
401Unauthorized
statusCode string
This is the MADAPI Canonical Error Code (it is 4 characters long and it is not the HTTP Status Code which is 3 characters long). Back-end system errors are mapped to specific canonical error codes which are returned. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes'
statusMessage string
More details and corrective actions related to the error which can be shown to a client
supportMessage string
Internal message meant for consumers of the API to troubleshoot the error (could possible include the back-end system error code in the message if it would be useful)
transactionId string
MADAPI generated Id to include for tracing requests
timestamp string
Timestamp that the error occurred
path string
The path that caused the error
method string
The HTTP method type that was used
{
    "statusCode": [],
    "statusMessage": [],
    "supportMessage": [],
    "transactionId": [],
    "timestamp": [],
    "path": [],
    "method": []
}
404Not Found
statusCode string
This is the MADAPI Canonical Error Code (it is 4 characters long and it is not the HTTP Status Code which is 3 characters long). Back-end system errors are mapped to specific canonical error codes which are returned. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes'
statusMessage string
More details and corrective actions related to the error which can be shown to a client
supportMessage string
Internal message meant for consumers of the API to troubleshoot the error (could possible include the back-end system error code in the message if it would be useful)
transactionId string
MADAPI generated Id to include for tracing requests
timestamp string
Timestamp that the error occurred
path string
The path that caused the error
method string
The HTTP method type that was used
{
    "statusCode": [],
    "statusMessage": [],
    "supportMessage": [],
    "transactionId": [],
    "timestamp": [],
    "path": [],
    "method": []
}
407Proxy Authentication Required
statusCode string
This is the MADAPI Canonical Error Code (it is 4 characters long and it is not the HTTP Status Code which is 3 characters long). Back-end system errors are mapped to specific canonical error codes which are returned. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes'
statusMessage string
More details and corrective actions related to the error which can be shown to a client
supportMessage string
Internal message meant for consumers of the API to troubleshoot the error (could possible include the back-end system error code in the message if it would be useful)
transactionId string
MADAPI generated Id to include for tracing requests
timestamp string
Timestamp that the error occurred
path string
The path that caused the error
method string
The HTTP method type that was used
{
    "statusCode": [],
    "statusMessage": [],
    "supportMessage": [],
    "transactionId": [],
    "timestamp": [],
    "path": [],
    "method": []
}
500Internal Server Error
statusCode string
This is the MADAPI Canonical Error Code (it is 4 characters long and it is not the HTTP Status Code which is 3 characters long). Back-end system errors are mapped to specific canonical error codes which are returned. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes'
statusMessage string
More details and corrective actions related to the error which can be shown to a client
supportMessage string
Internal message meant for consumers of the API to troubleshoot the error (could possible include the back-end system error code in the message if it would be useful)
transactionId string
MADAPI generated Id to include for tracing requests
timestamp string
Timestamp that the error occurred
path string
The path that caused the error
method string
The HTTP method type that was used
{
    "statusCode": [],
    "statusMessage": [],
    "supportMessage": [],
    "transactionId": [],
    "timestamp": [],
    "path": [],
    "method": []
}
DELETE v2/messages/sms/outbound/{senderAddress}/subscription/{subscriptionId}

Description

This interface will stop the server from sending SMS delivery notifications to third party apps when SMS messages are received by subscribers

Header parameters

Content-Type application/json

Auth parameters

oauth2 Authorization
200OK
statusCode string
This is the MADAPI Canonical Error Code (it is 4 characters long and it is not the HTTP Status Code which is 3 characters long). Back-end system errors are mapped to specific canonical error codes which are returned. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes'
statusMessage string
More details and corrective actions related to the error which can be shown to a client.
transactionId string
MADAPI generated Id to include for tracing requests
data object
_link
self
href string
{
    "statusCode": [],
    "statusMessage": [],
    "transactionId": [],
    "data": [],
    "_link": []
}
401Unauthorized
statusCode string
This is the MADAPI Canonical Error Code (it is 4 characters long and it is not the HTTP Status Code which is 3 characters long). Back-end system errors are mapped to specific canonical error codes which are returned. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes'
statusMessage string
More details and corrective actions related to the error which can be shown to a client
supportMessage string
Internal message meant for consumers of the API to troubleshoot the error (could possible include the back-end system error code in the message if it would be useful)
transactionId string
MADAPI generated Id to include for tracing requests
timestamp string
Timestamp that the error occurred
path string
The path that caused the error
method string
The HTTP method type that was used
{
    "statusCode": [],
    "statusMessage": [],
    "supportMessage": [],
    "transactionId": [],
    "timestamp": [],
    "path": [],
    "method": []
}
404Not Found
statusCode string
This is the MADAPI Canonical Error Code (it is 4 characters long and it is not the HTTP Status Code which is 3 characters long). Back-end system errors are mapped to specific canonical error codes which are returned. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes'
statusMessage string
More details and corrective actions related to the error which can be shown to a client
supportMessage string
Internal message meant for consumers of the API to troubleshoot the error (could possible include the back-end system error code in the message if it would be useful)
transactionId string
MADAPI generated Id to include for tracing requests
timestamp string
Timestamp that the error occurred
path string
The path that caused the error
method string
The HTTP method type that was used
{
    "statusCode": [],
    "statusMessage": [],
    "supportMessage": [],
    "transactionId": [],
    "timestamp": [],
    "path": [],
    "method": []
}
407Proxy Authentication Required
statusCode string
This is the MADAPI Canonical Error Code (it is 4 characters long and it is not the HTTP Status Code which is 3 characters long). Back-end system errors are mapped to specific canonical error codes which are returned. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes'
statusMessage string
More details and corrective actions related to the error which can be shown to a client
supportMessage string
Internal message meant for consumers of the API to troubleshoot the error (could possible include the back-end system error code in the message if it would be useful)
transactionId string
MADAPI generated Id to include for tracing requests
timestamp string
Timestamp that the error occurred
path string
The path that caused the error
method string
The HTTP method type that was used
{
    "statusCode": [],
    "statusMessage": [],
    "supportMessage": [],
    "transactionId": [],
    "timestamp": [],
    "path": [],
    "method": []
}
500Internal Server Error
statusCode string
This is the MADAPI Canonical Error Code (it is 4 characters long and it is not the HTTP Status Code which is 3 characters long). Back-end system errors are mapped to specific canonical error codes which are returned. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes'
statusMessage string
More details and corrective actions related to the error which can be shown to a client
supportMessage string
Internal message meant for consumers of the API to troubleshoot the error (could possible include the back-end system error code in the message if it would be useful)
transactionId string
MADAPI generated Id to include for tracing requests
timestamp string
Timestamp that the error occurred
path string
The path that caused the error
method string
The HTTP method type that was used
{
    "statusCode": [],
    "statusMessage": [],
    "supportMessage": [],
    "transactionId": [],
    "timestamp": [],
    "path": [],
    "method": []
}
GET v2/messages/sms/inbound/registrations/{requestId}/messages

Description

This interface is used to query for received SMS messages on the given requestId

Header parameters

Content-Type application/json

Auth parameters

oauth2 Authorization

Query parameters

maxBatchSize string
It is the maximum number of messages to be retrieved in the request. The actual maximum batch size is also limited by SLA MaxReturnedSMS. System chooses the smaller value from the value of maxBatchSize and MaxReturnedSMS.
200OK
statusCode string
This is the MADAPI Canonical Error Code (it is 4 characters long and it is not the HTTP Status Code which is 3 characters long). Back-end system errors are mapped to specific canonical error codes which are returned. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes'
statusMessage string
More details and corrective actions related to the error which can be shown to a client.
transactionId string
MADAPI generated Id to include for tracing requests
data
numberOfMessagesInThisBatch string
The number of messages in the batch.
totalNumberOfPendingMessages string
Total number of messages in the gateway storage waiting for retrieval at the time of the request
inboundSMSMessage
dateTime string
The time when the message is received.
registrationId string
The number associated with service (for example, an agreed short code)
message string
The SMS message itself
senderAddress string
The MSISDN or Anonymous Customer Reference of the sender
messageID string
Server-generated message identifier
_link
self
href string
{
    "statusCode": [],
    "statusMessage": [],
    "transactionId": [],
    "data": [],
    "_link": []
}
401Unauthorized
statusCode string
This is the MADAPI Canonical Error Code (it is 4 characters long and it is not the HTTP Status Code which is 3 characters long). Back-end system errors are mapped to specific canonical error codes which are returned. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes'
statusMessage string
More details and corrective actions related to the error which can be shown to a client
supportMessage string
Internal message meant for consumers of the API to troubleshoot the error (could possible include the back-end system error code in the message if it would be useful)
transactionId string
MADAPI generated Id to include for tracing requests
timestamp string
Timestamp that the error occurred
path string
The path that caused the error
method string
The HTTP method type that was used
{
    "statusCode": [],
    "statusMessage": [],
    "supportMessage": [],
    "transactionId": [],
    "timestamp": [],
    "path": [],
    "method": []
}
404Not Found
statusCode string
This is the MADAPI Canonical Error Code (it is 4 characters long and it is not the HTTP Status Code which is 3 characters long). Back-end system errors are mapped to specific canonical error codes which are returned. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes'
statusMessage string
More details and corrective actions related to the error which can be shown to a client
supportMessage string
Internal message meant for consumers of the API to troubleshoot the error (could possible include the back-end system error code in the message if it would be useful)
transactionId string
MADAPI generated Id to include for tracing requests
timestamp string
Timestamp that the error occurred
path string
The path that caused the error
method string
The HTTP method type that was used
{
    "statusCode": [],
    "statusMessage": [],
    "supportMessage": [],
    "transactionId": [],
    "timestamp": [],
    "path": [],
    "method": []
}
407Proxy Authentication Required
statusCode string
This is the MADAPI Canonical Error Code (it is 4 characters long and it is not the HTTP Status Code which is 3 characters long). Back-end system errors are mapped to specific canonical error codes which are returned. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes'
statusMessage string
More details and corrective actions related to the error which can be shown to a client
supportMessage string
Internal message meant for consumers of the API to troubleshoot the error (could possible include the back-end system error code in the message if it would be useful)
transactionId string
MADAPI generated Id to include for tracing requests
timestamp string
Timestamp that the error occurred
path string
The path that caused the error
method string
The HTTP method type that was used
{
    "statusCode": [],
    "statusMessage": [],
    "supportMessage": [],
    "transactionId": [],
    "timestamp": [],
    "path": [],
    "method": []
}
500Internal Server Error
statusCode string
This is the MADAPI Canonical Error Code (it is 4 characters long and it is not the HTTP Status Code which is 3 characters long). Back-end system errors are mapped to specific canonical error codes which are returned. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes'
statusMessage string
More details and corrective actions related to the error which can be shown to a client
supportMessage string
Internal message meant for consumers of the API to troubleshoot the error (could possible include the back-end system error code in the message if it would be useful)
transactionId string
MADAPI generated Id to include for tracing requests
timestamp string
Timestamp that the error occurred
path string
The path that caused the error
method string
The HTTP method type that was used
{
    "statusCode": [],
    "statusMessage": [],
    "supportMessage": [],
    "transactionId": [],
    "timestamp": [],
    "path": [],
    "method": []
}