{ "info": { "name": "MTN Messaging API", "schema": "https:\/\/schema.getpostman.com\/json\/collection\/v2.1.0\/collection.json" }, "item": [ { "name": "Send SMS", "description": "Send an SMS Message to a single or multiple mobile number\/s.\n", "request": { "auth": { "type": "oauth2", "oauth2": [ { "key": "addTokenTo", "value": "Authorization", "type": "string" } ] }, "method": "Post", "header": [ { "key": "Content-Type", "name": "Content-Type", "value": "application\/json", "type": "application\/json", "description": "" } ], "url": { "raw": "api.mtn.com\/sms", "protocol": "https", "host": [ "api", "mtn", "com" ], "path": [ "v1", "messages", "sms" ] }, "body": { "mode": "formdata", "formdata": [ { "key": "to", "value": "", "description": "Mobile number to send SMS to", "required": 1, "type": "array" }, { "key": "body", "value": "", "description": "text body of the SMS message", "required": 1, "type": "string" }, { "key": "from", "value": "", "description": "Sender identity\/address\/code", "required": 0, "type": "string" }, { "key": "notificationURL", "value": "", "description": "callback URL to send status of the SMS send request", "required": 0, "type": "string" }, { "key": "clientId", "value": "", "description": "Client\/Organizaton name", "required": 1, "type": "string" } ] } }, "response": [ { "code": 201, "status": "Created", "name": "Created", "schema": { "messages": { "to": { "description": "The number the sms is sent to.", "type": "string", "example": "+27832008963" }, "deliveryStatus": { "description": "Indicates whether or not the sms has been accepted for delivery\n", "type": "string", "example": "PENDING" }, "messageId": { "description": "A unique id to check the messages status. Id generated during delivery\n", "type": "string", "example": "d997474900097a1f0000000008d7e18102cc0901" }, "smsStatusURL": { "description": "Currently this url will map to the callback url provided. Please use the messageIds and delivery status endpoint to query delivery status.\n", "type": "string", "example": "https:\/\/api.mtn.com\/v1\/messages\/sms\/d997474900097a1f0000000008d7e18102cc0901\/status\n" } } }, "body": "{\"messages\":{\"to\":\"string\",\"deliveryStatus\":\"string\",\"messageId\":\"string\",\"smsStatusURL\":\"string\"}}", "header": [ { "key": "Content-Type", "value": "application\/json", "description": "Sending as JSON", "type": "string" } ] }, { "code": 400, "status": "Bad Request", "name": "Bad request", "schema": [], "body": "[]", "header": [ { "key": "Content-Type", "value": "application\/json", "description": "Sending as JSON", "type": "string" } ] }, { "code": 401, "status": "Unauthorized", "name": "Invalid access token. Please try with a valid token", "schema": [], "body": "[]", "header": [ { "key": "Content-Type", "value": "application\/json", "description": "Sending as JSON", "type": "string" } ] }, { "code": 403, "status": "Forbidden", "name": "Authorization credentials passed and accepted but account does forbidden to send SMSes\n", "schema": [], "body": "[]", "header": [ { "key": "Content-Type", "value": "application\/json", "description": "Sending as JSON", "type": "string" } ] }, { "code": 404, "status": "Not Found", "name": "Not Found", "schema": [], "body": "[]", "header": [ { "key": "Content-Type", "value": "application\/json", "description": "Sending as JSON", "type": "string" } ] }, { "code": 405, "status": "Method Not Allowed", "name": "The requested resource does not support the supplied verb", "schema": [], "body": "[]", "header": [ { "key": "Content-Type", "value": "application\/json", "description": "Sending as JSON", "type": "string" } ] }, { "code": 415, "status": "Unsupported Media Type", "name": "API does not support the requested content type", "schema": [], "body": "[]", "header": [ { "key": "Content-Type", "value": "application\/json", "description": "Sending as JSON", "type": "string" } ] }, { "code": 500, "status": "Internal Server Error", "name": "Internal Server Error", "schema": [], "body": "[]", "header": [ { "key": "Content-Type", "value": "application\/json", "description": "Sending as JSON", "type": "string" } ] }, { "code": 501, "status": "Not Implemented", "name": "The HTTP method being used has not yet been implemented for\nthe requested resource\n", "schema": [], "body": "[]", "header": [ { "key": "Content-Type", "value": "application\/json", "description": "Sending as JSON", "type": "string" } ] }, { "code": 503, "status": "Service Unavailable", "name": "The service requested is currently unavailable", "schema": [], "body": "[]", "header": [ { "key": "Content-Type", "value": "application\/json", "description": "Sending as JSON", "type": "string" } ] } ] }, { "name": "Receive SMS Responses", "description": "Retrieve SMS messages one by one", "request": { "auth": { "type": "oauth2", "oauth2": [ { "key": "addTokenTo", "value": "Authorization", "type": "string" } ] }, "method": "Get", "header": [ { "key": "Content-Type", "name": "Content-Type", "value": "application\/json", "type": "application\/json", "description": "" } ], "url": { "raw": "api.mtn.com\/sms", "protocol": "https", "host": [ "api", "mtn", "com" ], "path": [ "v1", "messages", "sms" ], "query": [ { "key": "batchSize", "value": "", "required": false, "type": "integer", "description": "" } ] } }, "response": [ { "code": 200, "status": "OK", "name": "OK", "schema": { "batchSize": { "description": "Number of SMSes returned", "type": "integer" }, "messages": { "status": { "description": "message status", "type": "string" }, "to": { "description": "The mobile number (recipient) that the message was sent to (in E.164 format).", "type": "string" }, "from": { "description": "The phone number (sender) that the message was sent from (in E.164 forma).", "type": "string" }, "message": { "description": "Text of the message that was sent", "type": "string" }, "messageId": { "description": "Message Id", "type": "string" }, "sentTimestamp": { "description": "The date and time when the message was sent by recipient.", "type": "string" } } }, "body": "{\"batchSize\":1,\"messages\":{\"status\":\"string\",\"to\":\"string\",\"from\":\"string\",\"message\":\"string\",\"messageId\":\"string\",\"sentTimestamp\":\"string\"}}", "header": [ { "key": "Content-Type", "value": "application\/json", "description": "Sending as JSON", "type": "string" } ] }, { "code": 400, "status": "Bad Request", "name": "Bad Request", "schema": [], "body": "[]", "header": [ { "key": "Content-Type", "value": "application\/json", "description": "Sending as JSON", "type": "string" } ] }, { "code": 401, "status": "Unauthorized", "name": "Invalid access token. Please try with a valid token", "schema": [], "body": "[]", "header": [ { "key": "Content-Type", "value": "application\/json", "description": "Sending as JSON", "type": "string" } ] }, { "code": 403, "status": "Forbidden", "name": "Authorization credentials passed and accepted but account not allowed to send SMS\n", "schema": [], "body": "[]", "header": [ { "key": "Content-Type", "value": "application\/json", "description": "Sending as JSON", "type": "string" } ] }, { "code": 404, "status": "Not Found", "name": "Not Found", "schema": [], "body": "[]", "header": [ { "key": "Content-Type", "value": "application\/json", "description": "Sending as JSON", "type": "string" } ] }, { "code": 405, "status": "Method Not Allowed", "name": "The requested resource does not support the supplied verb", "schema": [], "body": "[]", "header": [ { "key": "Content-Type", "value": "application\/json", "description": "Sending as JSON", "type": "string" } ] }, { "code": 415, "status": "Unsupported Media Type", "name": "API does not support the requested content type", "schema": [], "body": "[]", "header": [ { "key": "Content-Type", "value": "application\/json", "description": "Sending as JSON", "type": "string" } ] }, { "code": 500, "status": "Internal Server Error", "name": "Internal server error", "schema": [], "body": "[]", "header": [ { "key": "Content-Type", "value": "application\/json", "description": "Sending as JSON", "type": "string" } ] }, { "code": 501, "status": "Not Implemented", "name": "Not Implemeted", "schema": [], "body": "[]", "header": [ { "key": "Content-Type", "value": "application\/json", "description": "Sending as JSON", "type": "string" } ] }, { "code": 503, "status": "Service Unavailable", "name": "The service requested is currently unavailable", "schema": [], "body": "[]", "header": [ { "key": "Content-Type", "value": "application\/json", "description": "Sending as JSON", "type": "string" } ] } ] }, { "name": "Delivery status", "description": "Get delivery status", "request": { "auth": { "type": "oauth2", "oauth2": [ { "key": "addTokenTo", "value": "Authorization", "type": "string" } ] }, "method": "Get", "header": [ { "key": "Content-Type", "name": "Content-Type", "value": "application\/json", "type": "application\/json", "description": "" } ], "url": { "raw": "api.mtn.com\/sms\/{messageId}\/status", "protocol": "https", "host": [ "api", "mtn", "com" ], "path": [ "v1", "messages", "sms", "{messageId}", "status" ] } }, "response": [ { "code": 200, "status": "OK", "name": "OK", "schema": { "to": { "description": "The phone number (recipient) the message was sent to (in E.164 format).\n", "type": "string", "example": "+27832008963" }, "sentTimestamp": { "type": "object", "example": [] }, "receivedTimestamp": { "type": "object", "example": [] }, "deliveryStatus": { "type": "string", "default": "", "description": "PENDING,SENT,DELIVERED,EXPIRED,DELETED,UNDELIVERABLE,REJECTED,READ" } }, "body": "{\"to\":\"string\",\"sentTimestamp\":[],\"receivedTimestamp\":[],\"deliveryStatus\":\"string\"}", "header": [ { "key": "Content-Type", "value": "application\/json", "description": "Sending as JSON", "type": "string" } ] }, { "code": 400, "status": "Bad Request", "name": "Bad Request", "schema": [], "body": "[]", "header": [ { "key": "Content-Type", "value": "application\/json", "description": "Sending as JSON", "type": "string" } ] }, { "code": 401, "status": "Unauthorized", "name": "Invalid access token. Please try with a valid token", "schema": [], "body": "[]", "header": [ { "key": "Content-Type", "value": "application\/json", "description": "Sending as JSON", "type": "string" } ] }, { "code": 403, "status": "Forbidden", "name": "Authorization credentials passed and accepted but account does\nnot have permission to make the request", "schema": [], "body": "[]", "header": [ { "key": "Content-Type", "value": "application\/json", "description": "Sending as JSON", "type": "string" } ] }, { "code": 404, "status": "Not Found", "name": "Not Found", "schema": [], "body": "[]", "header": [ { "key": "Content-Type", "value": "application\/json", "description": "Sending as JSON", "type": "string" } ] }, { "code": 405, "status": "Method Not Allowed", "name": "The requested resource does not support the supplied verb", "schema": [], "body": "[]", "header": [ { "key": "Content-Type", "value": "application\/json", "description": "Sending as JSON", "type": "string" } ] }, { "code": 415, "status": "Unsupported Media Type", "name": "API does not support the requested content type", "schema": [], "body": "[]", "header": [ { "key": "Content-Type", "value": "application\/json", "description": "Sending as JSON", "type": "string" } ] }, { "code": 500, "status": "Internal Server Error", "name": "Internal server error", "schema": [], "body": "[]", "header": [ { "key": "Content-Type", "value": "application\/json", "description": "Sending as JSON", "type": "string" } ] }, { "code": 501, "status": "Not Implemented", "name": "Not implemented", "schema": [], "body": "[]", "header": [ { "key": "Content-Type", "value": "application\/json", "description": "Sending as JSON", "type": "string" } ] }, { "code": 503, "status": "Service Unavailable", "name": "The service requested is currently unavailable", "schema": [], "body": "[]", "header": [ { "key": "Content-Type", "value": "application\/json", "description": "Sending as JSON", "type": "string" } ] }, { "code": "default", "status": "An internal error occurred when processing the request", "name": "An internal error occurred when processing the request", "schema": [], "body": "[]", "header": [ { "key": "Content-Type", "value": "application\/json", "description": "Sending as JSON", "type": "string" } ] } ] }, { "name": "Register listener", "description": "Callback endpoint to enable the consuming app to receive smses sent to short code assigned to the app", "request": { "auth": { "type": "oauth2", "oauth2": [ { "key": "addTokenTo", "value": "Authorization", "type": "string" } ] }, "method": "Post", "header": [ { "key": "Content-Type", "name": "Content-Type", "value": "application\/json", "type": "application\/json", "description": "" } ], "url": { "raw": "api.mtn.com\/sms-listeners", "protocol": "https", "host": [ "api", "mtn", "com" ], "path": [ "v1", "messages", "sms-listeners" ] }, "body": { "mode": "formdata", "formdata": [ { "key": "callbackURL", "value": "", "description": "The callback being registered.", "required": 1, "type": "string" }, { "key": "accessCode", "value": "", "description": "Developer assigned short code", "required": 0, "type": "string" }, { "key": "clientId", "value": "", "description": "App ID", "required": 0, "type": "string" } ] } }, "response": [ { "code": 201, "status": "Created", "name": "Created", "schema": { "accessCode": { "type": "string", "description": "Id of the registered callback" }, "callbackUrl": { "type": "string", "description": "The callback being registered." }, "status": { "type": "string", "enum": [ "successful", "unsuccessful" ] }, "message": { "type": "string" } }, "body": "{\"accessCode\":\"string\",\"callbackUrl\":\"string\",\"status\":\"string\",\"message\":\"string\"}", "header": [ { "key": "Content-Type", "value": "application\/json", "description": "Sending as JSON", "type": "string" } ] }, { "code": 400, "status": "Bad Request", "name": "Bad Request", "schema": { "code": { "type": "integer", "description": "Application related code." }, "reason": { "type": "integer", "description": "Text that explains the reason for error." }, "message": { "type": "string", "description": "(optional) Text that provide more details and corrective actions related to the error." } }, "body": "{\"code\":1,\"reason\":1,\"message\":\"string\"}", "header": [ { "key": "Content-Type", "value": "application\/json", "description": "Sending as JSON", "type": "string" } ] }, { "code": 401, "status": "Unauthorized", "name": "Unauthorized", "schema": { "code": { "type": "integer", "description": "Application related code." }, "reason": { "type": "integer", "description": "Text that explains the reason for error." }, "message": { "type": "string", "description": "(optional) Text that provide more details and corrective actions related to the error." } }, "body": "{\"code\":1,\"reason\":1,\"message\":\"string\"}", "header": [ { "key": "Content-Type", "value": "application\/json", "description": "Sending as JSON", "type": "string" } ] }, { "code": 403, "status": "Forbidden", "name": "Forbidden", "schema": { "code": { "type": "integer", "description": "Application related code." }, "reason": { "type": "integer", "description": "Text that explains the reason for error." }, "message": { "type": "string", "description": "(optional) Text that provide more details and corrective actions related to the error." } }, "body": "{\"code\":1,\"reason\":1,\"message\":\"string\"}", "header": [ { "key": "Content-Type", "value": "application\/json", "description": "Sending as JSON", "type": "string" } ] }, { "code": 404, "status": "Not Found", "name": "Not Found", "schema": { "code": { "type": "integer", "description": "Application related code." }, "reason": { "type": "integer", "description": "Text that explains the reason for error." }, "message": { "type": "string", "description": "(optional) Text that provide more details and corrective actions related to the error." } }, "body": "{\"code\":1,\"reason\":1,\"message\":\"string\"}", "header": [ { "key": "Content-Type", "value": "application\/json", "description": "Sending as JSON", "type": "string" } ] }, { "code": 405, "status": "Method Not Allowed", "name": "Method Not allowed", "schema": { "code": { "type": "integer", "description": "Application related code." }, "reason": { "type": "integer", "description": "Text that explains the reason for error." }, "message": { "type": "string", "description": "(optional) Text that provide more details and corrective actions related to the error." } }, "body": "{\"code\":1,\"reason\":1,\"message\":\"string\"}", "header": [ { "key": "Content-Type", "value": "application\/json", "description": "Sending as JSON", "type": "string" } ] }, { "code": 409, "status": "Conflict", "name": "Conflict", "schema": { "code": { "type": "integer", "description": "Application related code." }, "reason": { "type": "integer", "description": "Text that explains the reason for error." }, "message": { "type": "string", "description": "(optional) Text that provide more details and corrective actions related to the error." } }, "body": "{\"code\":1,\"reason\":1,\"message\":\"string\"}", "header": [ { "key": "Content-Type", "value": "application\/json", "description": "Sending as JSON", "type": "string" } ] }, { "code": 500, "status": "Internal Server Error", "name": "Internal Server Error", "schema": { "code": { "type": "integer", "description": "Application related code." }, "reason": { "type": "integer", "description": "Text that explains the reason for error." }, "message": { "type": "string", "description": "(optional) Text that provide more details and corrective actions related to the error." } }, "body": "{\"code\":1,\"reason\":1,\"message\":\"string\"}", "header": [ { "key": "Content-Type", "value": "application\/json", "description": "Sending as JSON", "type": "string" } ] } ] }, { "name": "Remove callback listener", "description": "Remove endpoint used to send SMS notifications", "request": { "auth": { "type": "oauth2", "oauth2": [ { "key": "addTokenTo", "value": "Authorization", "type": "string" } ] }, "method": "Delete", "header": [ { "key": "Content-Type", "name": "Content-Type", "value": "application\/json", "type": "application\/json", "description": "" } ], "url": { "raw": "api.mtn.com\/sms-listeners\/{accessCode}", "protocol": "https", "host": [ "api", "mtn", "com" ], "path": [ "v1", "messages", "sms-listeners", "{accessCode}" ] } }, "response": [ { "code": 204, "status": "No Content", "name": "Callback deleted", "schema": [], "body": "[]", "header": [ { "key": "Content-Type", "value": "application\/json", "description": "Sending as JSON", "type": "string" } ] }, { "code": 400, "status": "Bad Request", "name": "Bad Request", "schema": { "code": { "type": "integer", "description": "Application related code." }, "reason": { "type": "integer", "description": "Text that explains the reason for error." }, "message": { "type": "string", "description": "(optional) Text that provide more details and corrective actions related to the error." } }, "body": "{\"code\":1,\"reason\":1,\"message\":\"string\"}", "header": [ { "key": "Content-Type", "value": "application\/json", "description": "Sending as JSON", "type": "string" } ] }, { "code": 401, "status": "Unauthorized", "name": "Unauthorized", "schema": { "code": { "type": "integer", "description": "Application related code." }, "reason": { "type": "integer", "description": "Text that explains the reason for error." }, "message": { "type": "string", "description": "(optional) Text that provide more details and corrective actions related to the error." } }, "body": "{\"code\":1,\"reason\":1,\"message\":\"string\"}", "header": [ { "key": "Content-Type", "value": "application\/json", "description": "Sending as JSON", "type": "string" } ] }, { "code": 403, "status": "Forbidden", "name": "Forbidden", "schema": { "code": { "type": "integer", "description": "Application related code." }, "reason": { "type": "integer", "description": "Text that explains the reason for error." }, "message": { "type": "string", "description": "(optional) Text that provide more details and corrective actions related to the error." } }, "body": "{\"code\":1,\"reason\":1,\"message\":\"string\"}", "header": [ { "key": "Content-Type", "value": "application\/json", "description": "Sending as JSON", "type": "string" } ] }, { "code": 404, "status": "Not Found", "name": "Not Found", "schema": { "code": { "type": "integer", "description": "Application related code." }, "reason": { "type": "integer", "description": "Text that explains the reason for error." }, "message": { "type": "string", "description": "(optional) Text that provide more details and corrective actions related to the error." } }, "body": "{\"code\":1,\"reason\":1,\"message\":\"string\"}", "header": [ { "key": "Content-Type", "value": "application\/json", "description": "Sending as JSON", "type": "string" } ] }, { "code": 405, "status": "Method Not Allowed", "name": "Method Not allowed", "schema": { "code": { "type": "integer", "description": "Application related code." }, "reason": { "type": "integer", "description": "Text that explains the reason for error." }, "message": { "type": "string", "description": "(optional) Text that provide more details and corrective actions related to the error." } }, "body": "{\"code\":1,\"reason\":1,\"message\":\"string\"}", "header": [ { "key": "Content-Type", "value": "application\/json", "description": "Sending as JSON", "type": "string" } ] }, { "code": 409, "status": "Conflict", "name": "Conflict", "schema": { "code": { "type": "integer", "description": "Application related code." }, "reason": { "type": "integer", "description": "Text that explains the reason for error." }, "message": { "type": "string", "description": "(optional) Text that provide more details and corrective actions related to the error." } }, "body": "{\"code\":1,\"reason\":1,\"message\":\"string\"}", "header": [ { "key": "Content-Type", "value": "application\/json", "description": "Sending as JSON", "type": "string" } ] }, { "code": 500, "status": "Internal Server Error", "name": "Internal Server Error", "schema": { "code": { "type": "integer", "description": "Application related code." }, "reason": { "type": "integer", "description": "Text that explains the reason for error." }, "message": { "type": "string", "description": "(optional) Text that provide more details and corrective actions related to the error." } }, "body": "{\"code\":1,\"reason\":1,\"message\":\"string\"}", "header": [ { "key": "Content-Type", "value": "application\/json", "description": "Sending as JSON", "type": "string" } ] } ] } ] }