MTN Group Subscribing for Mobile Originating and Delivery Receipts API

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