openapi: 3.2.0 info: version: '1.0' title: Short Message Service (SMS) Subscribing for Mobile Originating and Delivery Receipts API description: Provides a Restful API to expose SMS capability for sending of messages , Mobile originating messages and Delivery Receipts. servers: - url: https://api.mtn.com/v3/sms/ security: - OAuth2: [] tags: - name: Subscribing for Mobile Originating and Delivery Receipts paths: /messages/sms/subscription: post: tags: - Subscribing for Mobile Originating and Delivery Receipts summary: Create subscription to register a serviceCode, callback url and a delivery report url for mobile originating and Delivery Receipts. description: This is the interface used to register callbackUrl (For Mobile originating Messages ) and deliveryReportUrl (for Delivery Receipts ) for a shortCode/serviceCode/senderAddress. parameters: - in: header name: transactionId required: false schema: type: string responses: 200: description: Outbound SMS created content: application/json: schema: $ref: '#/components/schemas/subscriptionResponse' 401: description: Not authenticated content: application/json: schema: $ref: '#/components/schemas/Error' 403: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ForbiddenResponse' 404: description: Not found content: application/json: schema: $ref: '#/components/schemas/Error' 407: description: Proxy system not authenticated content: application/json: schema: $ref: '#/components/schemas/Error' 500: description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' requestBody: content: application/json: schema: $ref: '#/components/schemas/ShortCodeSubscription' description: Request body required: true /messages/sms/subscription/{subscriptionId}: patch: tags: - Subscribing for Mobile Originating and Delivery Receipts summary: Update a subscription information based on an already existing subscriptionId. description: Patch or update an existing subscription based on the subscriptionId , The subscriptionId is generated at the point of registering a short code for Mobile originating messages or Delivery Receipts with the /messages/sms/subscription endpoint above. parameters: - in: header name: transactionId required: false schema: type: string - in: path name: subscriptionId required: true description: This is the subscription Id that was returned on the initial subscription request. schema: type: string responses: 200: description: Outbound SMS created content: application/json: schema: $ref: '#/components/schemas/subscriptionResponse' 401: description: Not authenticated content: application/json: schema: $ref: '#/components/schemas/Error' 404: description: Not found content: application/json: schema: $ref: '#/components/schemas/Error' 407: description: Proxy system not authenticated content: application/json: schema: $ref: '#/components/schemas/Error' 500: description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdateSubscriptionRequest' description: Request body required: true delete: tags: - Subscribing for Mobile Originating and Delivery Receipts summary: Delete subscription or registration details based on the provided subscriptionId. description: This interface will stop our systems from sending Mobile originating messages and Delivery status reports to the provided delivery report and callback urls for a configured serviceCode. parameters: - in: header name: transactionId required: false schema: type: string - in: path name: subscriptionId required: true description: 'It is the id that is generated at the point of subscription with the messages/sms/subscription endpoint ' x-example: '27831234552920202220' schema: type: string responses: 200: description: SMS notification for Mobile originating and Delivery Receipts has been stopped. content: application/json: schema: $ref: '#/components/schemas/outboundSubscriptionDeleteResponse' 401: description: Not authenticated content: application/json: schema: $ref: '#/components/schemas/Error' 404: description: Not found content: application/json: schema: $ref: '#/components/schemas/Error' 407: description: Proxy system not authenticated content: application/json: schema: $ref: '#/components/schemas/Error' 500: description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: subscriptionResponse: type: object required: - data - statusCode - statusMessage - transactionId properties: statusCode: type: string description: 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' example: '0000' statusMessage: type: string description: More details and corrective actions related to the error which can be shown to a client. example: Sms Subscriptions successful Please keep the subscription id safely 6328...., if you need to delete it later. transactionId: type: string description: MADAPI generated Id to include for tracing requests example: 1365478abcz-fdhsdfh54351 data: type: object properties: subscriptionId: type: string description: Unique identifier for the subscription example: sub123456 ForbiddenResponse: type: object required: - statusCode - statusMessage - transactionId properties: statusCode: type: string description: 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' example: '4004' statusMessage: type: string description: More details and corrective actions related to the error which can be shown to a client example: Service code has already been registered . supportMessage: type: string description: 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) example: Service code 711 has been used by WEB-ONLINE !. transactionId: type: string description: MADAPI generated Id to include for tracing requests timestamp: type: string format: date-time description: Timestamp that the error occurred example: 2020-08-01T12:34 path: type: string description: The path that caused the error example: https://api.mtn.com/v1/ method: type: string description: The HTTP method type that was used example: POST ShortCodeSubscription: type: object required: - callbackUrl - targetSystem - serviceCode properties: callbackUrl: type: string description: This is the callback URL that will be invoked when a Mobile originating or Delivery Receipt message is sent by a Subscriber to the configured short code . example: https://example.com/12acb41 targetSystem: type: string description: Target system indicates the name of the system that this Mobile originating request will be sent to. example: Golden-Bank deliveryReportUrl: type: string description: This is the URL where the delivery receipts for messages sent with the /messages/sms/outbound endpoint will be sent. The messages will be sent to the deliveryReportUrl if requestDeliveryReceipt is set to true , by default it is false when sending an outbound message. example: https://example.com/delivery-report serviceCode: type: string description: This is the service code that is being registered for Mobile originating and delivery receipt calls outboundSubscriptionDeleteResponse: type: object required: - data - statusCode - statusMessage - transactionId properties: statusCode: type: string description: 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' example: '0000' statusMessage: type: string description: More details and corrective actions related to the error which can be shown to a client. example: Successful transactionId: type: string description: MADAPI generated Id to include for tracing requests example: 1365478abcz-fdhsdfh54351 data: type: object properties: subscriptionId: type: string example: 63284250bde7cd4938630ada UpdateSubscriptionRequest: type: object properties: serviceCode: type: string description: Service code that is being shared callbackUrl: type: string description: This is the callback URL example: http://www.... deliveryReportUrl: type: string description: This is the delivery URL example: http://www.... targetSystem: type: string keywords: type: array items: type: string description: Keywords applies to a shared short code . This is applicable only for the Nigeria opco. Error: type: object required: - statusCode - statusMessage - transactionId properties: statusCode: type: string description: 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' example: '1000' statusMessage: type: string description: More details and corrective actions related to the error which can be shown to a client supportMessage: type: string description: 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: type: string description: MADAPI generated Id to include for tracing requests timestamp: type: string format: date-time description: Timestamp that the error occurred example: 2020-08-01T12:34 path: type: string description: The path that caused the error example: https://api.mtn.com/v1/ method: type: string description: The HTTP method type that was used example: POST securitySchemes: OAuth2: type: oauth2 flows: clientCredentials: scopes: SEND-SMS: Grants ability to send SMS messages to subscribers. tokenUrl: https://api.mtn.com/v1/oauth/access_token/accesstoken?grant_type=client_credentials