swagger: "2.0"
info:
  version: "1.0"
  title: "Short Message Service (SMS) API"
  description: "Provides a Restful API to expose SMS capability for sending of messages , Mobile originating messages and Delivery Receipts."
host: api.mtn.com
basePath: /v3/sms/
schemes:
  - https
consumes:
  - application/json
produces:
  - application/json
securityDefinitions:
  OAuth2:
    type: oauth2
    flow: application
    tokenUrl: "https://api.mtn.com/v1/oauth/access_token/accesstoken?grant_type=client_credentials"
    scopes:
      SEND-SMS: Grants ability to send SMS messages to subscribers.
security:
  - OAuth2: []
paths:
  /messages/sms/outbound:
    post:
      tags:
        - "Sending SMS"
      summary: "This operation is used to send an outbound SMS message to the provided recipients."
      description: "This interface is used to send an SMS to the specified receiverAddress."
      parameters:
        - in: "body"
          name: "body"
          description: "Request body"
          required: true
          schema:
            $ref: "#/definitions/outboundSMSMessageRequest"
      responses:
        200:
          description: "Outbound SMS created"
          schema:
            $ref: "#/definitions/resourceReference"
        401:
          schema:
            $ref: "#/definitions/Error"
          description: "Not authenticated"
        404:
          schema:
            $ref: "#/definitions/Error"
          description: "Not found"
        407:
          schema:
            $ref: "#/definitions/Error"
          description: "Proxy system not authenticated"
        500:
          schema:
            $ref: "#/definitions/Error"
          description: "Internal Server Error"

  /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
          type: string
          required: false
        - in: "body"
          name: "body"
          description: "Request body"
          required: true
          schema:
            $ref: "#/definitions/ShortCodeSubscription"
      responses:
        200:
          description: "Outbound SMS created"
          schema:
            $ref: "#/definitions/subscriptionResponse"
        401:
          schema:
            $ref: "#/definitions/Error"
          description: "Not authenticated"
        403:
          schema:
            $ref: "#/definitions/ForbiddenResponse"
          description: "Forbidden"
        404:
          schema:
            $ref: "#/definitions/Error"
          description: "Not found"
        407:
          schema:
            $ref: "#/definitions/Error"
          description: "Proxy system not authenticated"
        500:
          schema:
            $ref: "#/definitions/Error"
          description: "Internal Server Error"



  /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
          type: string
          required: false
        - in: path
          name: subscriptionId
          type: string
          required: true
          description: This is the subscription Id that was returned on the initial subscription request.
        - in: "body"
          name: "body"
          description: "Request body"
          required: true
          schema:
            $ref: "#/definitions/UpdateSubscriptionRequest"
      responses:
        200:
          description: "Outbound SMS created"
          schema:
            $ref: "#/definitions/subscriptionResponse"
        401:
          schema:
            $ref: "#/definitions/Error"
          description: "Not authenticated"
        404:
          schema:
            $ref: "#/definitions/Error"
          description: "Not found"
        407:
          schema:
            $ref: "#/definitions/Error"
          description: "Proxy system not authenticated"
        500:
          schema:
            $ref: "#/definitions/Error"
          description: "Internal Server Error"

    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
          type: string
          required: false
        - in: "path"
          name: subscriptionId
          type: string
          required: true
          description: "It is the id that is generated at the point of subscription with the messages/sms/subscription   endpoint  "
          x-example: "27831234552920202220"
      responses:
        200:
          description: "SMS notification for Mobile originating and Delivery Receipts has been stopped."
          schema:
            $ref: "#/definitions/outboundSubscriptionDeleteResponse"
        401:
          schema:
            $ref: "#/definitions/Error"
          description: "Not authenticated"
        404:
          schema:
            $ref: "#/definitions/Error"
          description: "Not found"
        407:
          schema:
            $ref: "#/definitions/Error"
          description: "Proxy system not authenticated"
        500:
          schema:
            $ref: "#/definitions/Error"
          description: "Internal Server Error"



definitions:
  outboundSMSMessageRequest:
    type: object
    required:
      - message
      - serviceCode
      - receiverAddress
      - clientCorrelatorId
    properties:
      senderAddress:
        type: string
        description: "This is the sender address the recipients will see on their devices as the sender of the message. This is alphanumeric. This field is optional when it has a value it takes precedence over the serviceCode and is used to send messages rather than using serviceCode."
        example: "MTN"
      receiverAddress:
        description: "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.Thare are no limits to the length of the array but a sizable amount of 20 to 30 is expected for optimal delivery to recipients."
        type: array
        items:
          type: string
        example: ["23423456789","23423456790"]
      message:
        type: string
        description: "The message being sent. The standard limit of the size of the message is 160 for English texts  and about 250 to 300 characters for french related texts."
      clientCorrelatorId:
        type: string
        description: "It uniquely identifies the request.This can be alphanumeric or numeric depending on the consumers id pattern ."
        maxLength: 36
      keyword:
        type: string
        description: The keyword field is used in cases where the partner needs to share the short code and the partner had already subscribed with this keyword for Delivery Receipts via the subscriptions endpoint. The keyword field will then be used to send an outbound request to indicate that this request uses a shared short code and the Delivery receipt will be sent to the endpoint that was registered with this keyword . `Currently this is only used and was requested by the Nigeria opco `
      serviceCode:
        type: string
        description: "This is the short code that is provided by the api consumer and is approved by the opco for sending messages on behalf of a 3pp. This field is mandatory and if a senderAddress is used rather than the serviceCode , then the senderAddress value must be passed as well to this field,this will ensure that the messages are sent using the senderAddress."
        example: "11221 or 131"
      requestDeliveryReceipt:
        type: boolean
        description: This is used to indicate whether the 3pp needs a delivery report or not. By default this is set to false . When set to true the consumer should ensure that they must have subscribed for delivery receipts or mobile originating messages using the subscriptions endpoints below .
        example: false



  resourceReference:
    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: 'Sucessful'
      transactionId:
        type: string
        description: MADAPI generated Id to include for tracing requests
        example: "1365478abcz-fdhsdfh54351"
      data:
        type: object
        required:
          - status
        properties:
          status:
            type: string
            description: "Status of the submitted outbound message(s)"
            example: "PENDING"

  status:
    type: "string"
    title: "Delivery status"
    description: "SMS delivery status."
    example: "DELIVERED"
    enum:
      - "ACCEPTD"
      - "DELETED"
      - "DELIVERED"
      - "ENROUTE"
      - "UNKNOWN"
      - "EXPIRED"
      - "REJECTED"
      - "UNDELIVERED"

  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."


  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

  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"

  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"

  DeliveryNotificationRequest:
    type: object
    description: "This message body highlights the json message that will be sent to a third party endpoint to report the status of a message delivery."
    properties:
      clientCorrelatorId:
        type: string
        description: "Message ID for which the Derivery report is being sent"
        example: "09273682261681"
      deliveryStatus:
        $ref: "#/definitions/status"
      details:
        type: string
      completedDate:
        type: string
        format: datetime
      id:
        type: number
      error:
        type: string
      senderAddress:
        type: string
      receiverAddress:
        type: string
      submittedDate:
        type: string
        format: datetime


  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'

  ErrorPatch:
    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'


  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'