---
swagger: "2.0"
info:
  description: The API facilitates product survey with a MTN Customer.
  version: "1.1"
  title: Customer Survey API
host: api.mtn.com
basePath: "/v1/survey"
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: Get Survey Quetions
      description: Fetch Survey Questions and Options.
      parameters:
        - name: "customerId"
          in: path
          description: Source Msisdn. The format must be E.123
          required: true
          type: string
        - name: "surveyId"
          type: string
          in: query
          required: false
          description: The unique ID of a particular survey
        - name: targetSystem
          type: string
          in: query
          enum:
            - CLM
            - DIGISURVEY
            - CLM_REST
        - name: surveyType
          type: string
          in: query
          enum: ['eValidator','SHARENSELL']
      responses:
        "200":
          description: Success
          schema:
            type: object
            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"
              transactionId:
                type: string
                description: "API generated Id to include for tracing requests"
              data:
                $ref: '#/definitions/DataResponse'
              _links:
                type: object
                properties:
                  self:
                    type: string
                    example: "https://api.mtn.com/v1/survey/customers/23464618463"
        "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: Submit Survey and more KYC Answers
      description: Submit a list of questions and answers to survey.
      parameters:
        - name: surveyId
          in: header
          type: string
          description: unique ID generated for each transaction
          required: false
        - name: surveyType
          in: header
          type: string
          description: Survey type
          required: false
        - name: countryCode
          in: header
          type: string
          description: Survey type
          required: false
        - name: "customerId"
          in: path
          description: Source Msisdn. The format must be E.123
          required: true
          type: string
        - name: body
          in: body
          required: true
          schema:
            type: object
            required:
              - answers
            properties:
              hash:
                type: string
                example: "Wk68gjJxucqM4qxTYCNH94TMid0KhIaE"
                description: "The unique hash identifier for submiting a survey answer"
              targetSystem:
                type: string
                example: DIGISURVEY
                enum:
                  - CLM
                  - DIGISURVEY
                  - CLM_REST
                  - GENESIS
              surveyType:
                type: string
                enum: ['SHARENSELL','eValidator']
              servicePlan:
                type: string
                description: This is the service class of the customerId submiting survey answers
              answers:
                type: array
                description: "The list of answered questions"
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                    message:
                      type: string
                    input :
                      type: string
      responses:
        "200":
          description: Success Response
          schema:
            type: object
            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"
              transactionId:
                type: string
                description: "API generated Id to include for tracing requests"
              data:
                $ref: '#/definitions/DataResponse'
              _links:
                type: object
                properties:
                  self:
                    type: string
                    example: "https://api.mtn.com/v1/survey/customers/23464618463"
        "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'
  /customers/surveyOptInByTimeStamp:
    get:
      tags:
        - Customer
      summary: Get Survey Msisdn List in CSV format
      description: Fetch Survey Msisdn List in CSV format.
      parameters:
        - name: startDate
          in: query
          type: string
        - name: endDate
          in: query
          type: string
          description: startDate
          required: true
        - name: targetSystem
          type: string
          in: query
          enum:
            - GENESIS
      responses:
        "200":
          description: Success
          schema:
            type: object
            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"
              transactionId:
                type: string
                description: "API generated Id to include for tracing requests"
              data:
                $ref: '#/definitions/SurveyListResponse'
              _links:
                type: object
                properties:
                  self:
                    type: string
                    example: "https://api.mtn.com/v1/survey/customers/surveyOptInByTimeStamp"
        "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:


  DataResponse:
    type: object
    properties:
      hash:
        type: string
        description: The unique hash identifier attached to a survey
        example: "Wk68gjJxucqM4qxTYCNH94TMid0KhIaE"
      questions:
        type: array
        items:
          type: object
          properties:
            id:
              type: integer
              description: "Unique Question Id"
            type:
              type: string
              description: "Type of the question"
              example: "QuestionScalableDIGI"
            nested_level:
              example: 1
              type: integer
              description: "Questions Current Position"
            language:
              type: object
              description: "The actual Question"
              example: {
                "text": "How would you rate your experience performing this transaction?",
                "error": "Please rate your experience to help us serve you better:"
              }

            options:
              description: "Available options for the question"
              type: object
              example: {
                "render_type": "star rating",
                "required": "1",
                "number": "5",
                "start_from_0": "0"
              }

            answers:
              description: "Expected answers"
              type: object
              example: [
                {
                  "id": "647",
                  "value": "Yes",
                  "name": "Yes"
                },
                {
                  "id": "648",
                  "value": "No",
                  "name": "No"
                }
              ]
      finish:
        type: boolean
        example: false
        description: "Determined the last question"
      state:
        type: string
        example: "Created"
      requiredScore:
        type: string
        example: 15
      actualScore:
        type: string
        example: 20

  SurveyListResponse:
    type: string
    title: SurveyListResponse
    description: msisdn list in csv format
    example: '26876497748,26876497748,26876062635'
  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"
      _links:
        type: object
        properties:
          self:
            type: object
            properties:
              href:
                type: string
                example: "https://api.mtn.com/v1/survey/customers/surveyOptInByTimeStamp"