---
swagger: "2.0"
info:
  description: Mobile Advertisement API
  version: "2.0"
  title: Mobile Advertisement API
host: api.mtn.com
basePath: "/v2/adverts"
schemes:
- https
consumes:
- application/json
produces:
- application/json
securityDefinitions:
  ApiKeyAuth:
    type: "apiKey"
    name: "X-API-Key"
    in: "header"
security:
  - ApiKeyAuth: []

paths:
  /customers/{customerId}:
    get:
      tags:
       - Customer 
      summary: "Ads Request"
      description: Fetch Advertisement.
      parameters:
      - name: "customerId"
        in: path
        description: Source Msisdn. The format must be E.123
        required: true
        type: string
      - name: transactionId
        in: header 
        type: string 
        description: "A unique identifier for tracking all request/response"
        x-example: "88928392389283928"
      - name: "x-country-code"
        in: header
        type: string
        description: "Supplied by Apigee, overwritten if passed"
        x-example:  "NGA, ESW"
        required: false
      responses:
        "200":
          description: "Success"
          schema:
            $ref: "#/definitions/APISuccessResponse"
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/Error'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/Error'
        "403":
          description: Forbidden
          schema:
            $ref: '#/definitions/Error'
        "404":
          description: Not Found
          schema:
            $ref: '#/definitions/Error'
        "405":
          description: Method No Allowed
          schema:
            $ref: '#/definitions/Error'
        "406":
          description: Not acceptable
          schema:
            $ref: '#/definitions/Error'
        "415":
          description: Unsupported media Type
          schema:
            $ref: '#/definitions/Error'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/Error'
    post:
      tags:
      - Customer
      summary: "Ads Request"
      description: Fetch Advertisement.
      parameters:
      - name: "customerId"
        in: path
        description: Source Msisdn. The format must be E.123
        required: true
        type: string
      - name: transactionId
        in: header 
        type: string 
        description: "A unique identifier for tracking all request/response"
        x-example: "88928392389283928"
      - name: "x-country-code"
        in: header
        type: string
        description: "To be passed by APIGee, if not passed, 3PP to pass it"
        x-example:  "NGA, ESW"
        required: false
      - name: body
        in: body
        required: true
        schema: 
          type: object
          required:
            - hash
            - answers
          properties:
            notificationType:
              description: Type of notication to be sent to user. e.g SMS or USSD
              type: string
              example: SMS
              enum:
                - SMS
                - USSD
                - WEB
            portalId:
              description: The 3PP unique portal Id
              type: string
              example: MyMTNApp
            preMessage:
              description: Initial message coming from the caller. This message will be prepended to the advertisement message that will be send to user.
              type: string
              example: Your total call cost is 512.00 Naira... 
            
      responses:
        "200":
          description: "Success"
          schema:
            $ref: "#/definitions/APISuccessResponse"
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/Error'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/Error'
        "403":
          description: Forbidden
          schema:
            $ref: '#/definitions/Error'
        "404":
          description: Not Found
          schema:
            $ref: '#/definitions/Error'
        "405":
          description: Method No Allowed
          schema:
            $ref: '#/definitions/Error'
        "406":
          description: Not acceptable
          schema:
            $ref: '#/definitions/Error'
        "415":
          description: Unsupported media Type
          schema:
            $ref: '#/definitions/Error'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/Error'
    
definitions:
 
  RelatedPartyItem:
    type: object
    properties:
      id:
        type: string
        description: A unique identifier 
      value:
       type: string
       description: "A value associated with the unique identifier"

  APISuccessResponse:
        type: object
        description: Success
        properties:
              statusCode:
                type: string
                description: "This is the MADAPI Canonical response Code (it is 4 characters long and it is not the HTTP Status Code which is 3 characters long). Back-end system response are mapped to specific canonical response codes which are returned. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes'"
              statusMessage: 
                type: string
                description: "Status Message"
              sequenceNo:
                type: string
                description: A unique identifier generated internally by MADAPI for tracking all requests
              transactionId:
                type: string
                description: "API generated Id to include for tracing requests"
              data:
                type: object
                properties:
                  name:
                    type: string
                  imageUrl:
                    type: string
                  text:
                    type: string
                  title:
                    type: string
                  clickUrl:
                    type: string
                  callbackUrl:
                    type: string
                    description: Callback url
                  key: 
                    type: string
                    description: "Key"
                  adValid:
                    type: string
                  adId:
                    type: string
                  relatedParty:
                    type: array
                    items: 
                       $ref: "#/definitions/RelatedPartyItem"
                
              _links:
                type: object
                properties:
                  self:
                    type: string
                    example: "https://api.mtn.com/v1/adverts/customers/2348064618463"

  Error:
    type: object
    required:
      - "statusCode"
      - "statusMessage"
    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: API generated Id to include for tracing requests
      timestamp:
        type: string
        format: date-time
        description: Timestamp of the error
        example: "2019-08-23T07:29:25.593+0000"
      sequenceNo:
        type: string
        description: "A unique identifier for tracking madapi req/res"
      _links:
        type: object
        properties:
          self:
            type: object
            properties:
              href:
                type: string
                example: "https://api.mtn.com/v1/adverts/customers/23464618463"