swagger: "2.0"
info:
  description: |-
    - custom SIM verification functions for MTN 3PPs.
      
  version: "1.0"
  title: MTN Customer SIM Verification API
host: api.mtn.com
basePath: "/v1/simVerification"
schemes:
  - https
consumes:
  - application/json
produces:
  - application/json
security:
- ApiKeyAuth: []
paths:
            
  /customers/{customerId}/simSwap/verifyStatus:
    get:
      tags:
        - Sim Swap
      summary: Verify sim swap status as true or false.
      description: >-
        Retrieve  sim-swap status indicateing whether a sim swap was performed on a particular msisdn .
      parameters:
        - name: customerId
          in: path
          description: >-
            ID of the subscriber is the MSISDN of the subscriber represented as International  ITU-T E.164.
          required: true
          type: string
        - name: senderId
          in: query
          description: >-
           Identifier of the request originating system, e.g. 'IVR', 'My MTN App'etc.
          required: true
          type: string
        - name: extTransactionId
          in: header
          description: Unique transaction id generated by source channel for tracing purposes. This field is manadory for MTN-Nigeria.
          required: false
          type: string
        
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/SIMSwapStatus'
        '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'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/Error'
  /customers/{customerId}/simSwap/validateStatus:
    get:
      tags:
        - Sim Swap
      summary: Validate simswap status as true or false.
      description: >-
        Validate  sim-swap status against the last simswap date supplied by the partner  .
      parameters:
        - name: customerId
          in: path
          description: >-
            ID of the subscriber is the MSISDN of the subscriber represented as International  ITU-T E.164.
          required: true
          type: string
        - name: senderId
          in: query
          description: >-
           Identifier of the request originating system, e.g. 'IVR', 'My MTN App'etc.
          required: true
          type: string
        - name: startDate
          in: query
          description: >-
           Start date and end date will be used by 3pp to supply the date range for sim swap (recent) happened on the customer's msisdn, which will be used by operator to validate against the actual sim swap date
          required: true
          type: string
        - name: endDate
          in: query
          description: >-
           Start date and end date will be used by 3pp to supply the date range for sim swap (recent) happened on the customer's msisdn, which will be used by operator to validate against the actual sim swap date
          required: true
          type: string
        - name: extTransactionId
          in: header
          description: Unique transaction id generated by source channel for tracing purposes. This field is manadory for MTN-Nigeria.
          required: false
          type: string
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/SIMSwapStatus'
        '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'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/Error'
  
  /customers/{customerId}/simActivation/verifyStatus:
    get:
      tags:
        - Sim Activation
      summary: Verify sim activation status as true or false.
      description: >-
        Retrieve  sim-swap status indicateing whether a sim swap was performed on a particular msisdn .
      parameters:
        - name: customerId
          in: path
          description: >-
            ID of the subscriber is the MSISDN of the subscriber represented as International  ITU-T E.164.
          required: true
          type: string
        - name: senderId
          in: query
          description: >-
           Identifier of the request originating system, e.g. 'IVR', 'My MTN App'etc.
          required: true
          type: string
        - name: extTransactionId
          in: header
          description: Unique transaction id generated by source channel for tracing purposes. This field is manadory for MTN-Nigeria.
          required: false
          type: string
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/SIMActivationStatus'
        '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'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/Error'
  /customers/{customerId}/simActivation/validateStatus:
    get:
      tags:
        - Sim Activation
      summary: Validate sim activation status as true or false.
      description: >-
        Validate  sim activation status against the activation  date supplied by the partner  .
      parameters:
        - name: customerId
          in: path
          description: >-
            ID of the subscriber is the MSISDN of the subscriber represented as International  ITU-T E.164.
          required: true
          type: string
        - name: senderId
          in: query
          description: >-
           Identifier of the request originating system, e.g. 'IVR', 'My MTN App'etc.
          required: true
          type: string
        - name: startDate
          in: query
          description: >-
           Start date and end date will be used by 3pp to supply the date range for sim activation (recent) happened on the customer's msisdn, which will be used by operator to validate against the actual sim activation date 
          required: true
          type: string
        - name: endDate
          in: query
          description: >-
           Start date and end date will be used by 3pp to supply the date range for sim activation (recent) happened on the customer's msisdn, which will be used by operator to validate against the actual sim activation date 
          required: true
          type: string
        - name: extTransactionId
          in: header
          description: Unique transaction id generated by source channel for tracing purposes. This field is manadory for MTN-Nigeria.
          required: false
          type: string
        
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/SIMActivationStatus'
        '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'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/Error'
            
  /customers/{customerId}/simRecycle/verifyStatus:
    get:
      tags:
        - Sim Recycle
      summary: Verify sim recycle status as true or false.
      description: >-
        Retrieve  sim recycle status indicateing whether a sim swap was performed on a particular msisdn .
      parameters:
        - name: customerId
          in: path
          description: >-
            ID of the subscriber is the MSISDN of the subscriber represented as International  ITU-T E.164.
          required: true
          type: string
        - name: senderId
          in: query
          description: >-
           Identifier of the request originating system, e.g. 'IVR', 'My MTN App'etc.
          required: true
          type: string
        - name: extTransactionId
          in: header
          description: Unique transaction id generated by source channel for tracing purposes. This field is manadory for MTN-Nigeria.
          required: false
          type: string
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/SIMRecycleStatus'
        '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'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/Error'

definitions:
  registrationStatusResponse:
    type: object
    properties:
      statusCode:
        type: string
        example: "0000"
      statusMessage:
        type: string
        description: For MTN Uganda, for a successful response, this will be the same message string returned from the DCLM system.
        example: "Dear customer, your number 256789999781 has been Successfully uploaded by NIRA using NATIONAL ID number (NIN) ******7*6*7. To update dial *197*3#."
      transactionId:
        type: string
        description: "Client or API generated Id to include for tracing requests"
      data:
        type: array
        items:
          type: object
          required:
            - name
            - status
          properties:
            id:
              type: string
              description: Identifier of an instance of the resource. Required to be unique within the resource type.  Used in URIs as the identifier for specific instances of a type.
              example: "23464618463"
            name:
              type: string
              description: "A string used to give a name to the resource"
              example: "Adeyinka"
            status:
              type: string
              description: 'Tracks the lifecycle status of the resource, such as planning, installing, opereating, retiring and so on.'
              enum:
                - pending
                - enable
                - disable
      _links:
        type: object
        properties:
          self:
            type: object
            properties:
              href:
                type: string
                example: "https://api.mtn.com/v1/<path>"

  simInformationReponse:
    type: object
    properties:
      statusCode:
        type: string
        example: "0000"
      statusMessage:
        type: string
        example: "Request Successful processed"
      transactionId:
        type: string
        description: "Client or API generated Id to include for tracing requests"
      data:
        $ref: '#/definitions/SimDetails'
      _links:
        type: object
        properties:
          self:
            type: object
            properties:
              href:
                type: string
                example: "https://api.mtn.com/v1/customers/256789999781/sim/simDetails"

  SimDetails:
    type: object
    properties:
      SimInformation:
        type: array
        description: "The list of sim card parameters"
        items:
          $ref: '#/definitions/SimDetailsParams'

  SimDetailsParams:
    type: object
    properties:
      code:
        type: "string"
        description: "The name of the sim card feature"
        example: "SIM"
      name:
        description: "The defintion of the sim card feature"
        type: "string"
        example: "SIM number"
      value:
        description: "The value the sim card feature is assigned to"
        type: string
        example: "981300121000031"

  resourcePoolResp:
    type: object
    properties:
      statusCode:
        type: string
        description: 0000 for success
        example: '0000'
      transactionId:
        type: string
        description: Transaction identifier from the backend.
        example: 213321-3253332b3-1223
      data:
        $ref: '#/definitions/resourcePoolData'
      _links:
        type: object
        properties:
          self:
            type: object
            properties:
              href:
                type: string
                example: "https://uganda.api.mtn.com/v1/customers/customerId/sim/resourcePool"

  resourcePoolData:
    type: object
    properties:
      numberOfRec:
        type: integer
        description: Number of resources
        example: 1
      resources:
        type: array
        items:
          properties:
            id:
              type: string
              description: UniqueId of the resource
              example: PN_025330
            resourceType:
              type: string
              description: Type of resource
              enum:
                - MSISDN
                - IMSNo
                - FXLNo
            value:
              type: string
              description: Value of the resource
              example: 256789999101

  simSwapRequest:
    allOf:
      - required:
          - nodeId
          - reasonCode
        properties:
          nodeId:
            type: string
            description: Identifies the source system which is initiating the request.
          relatedParty:
            $ref: '#/definitions/relatedParty'
          oldSimNumber:
            type: string
            description: >-
              Subscriber Identity Module number of the subscriber.Atleast
              oldSimNumber or msisdn need to be provided in the request.
          newMSISDN:
            type: string
            description: New MSISDN of the selected SIM. Atleast newMSISDN or newSimNumber to be provided
          newSimNumber:
            type: string
            description: Subscriber Identity Module of the subscriber.
          reasonCode:
            type: string
            description: Reason Code for the Sim Swap
            example: Lost SIM

  relatedParty:
    allOf:
      - required:
          - id
          - name
          - role
          - referredType
        properties:
          id:
            type: string
            description: Identifies the related party
          name:
            type: string
            description: Role Name
          role:
            type: string
          geographicLocation:
            $ref: '#/definitions/GeographicLocation'
          '@referredType':
            type: string

  GeographicLocation:
    type: object
    required:
      - spatialRef
      - geometry
    properties:
      spatialRef:
        type: string
      geometry:
        $ref: '#/definitions/Geometry'

  Geometry:
    type: object
    required:
      - x
      - y
    properties:
      x:
        type: string
        example: "33.33"
      y:
        type: string
        example: "33.33"
      z:
        type: 'string'
        example: "33.33"

  SimswapStatusResponse:
    allOf:
      - required:
          - statusCode
          - statusMessage
          - transactionId
        properties:
          transactionId:
            type: string
            description: >-
              Unique identifier for every request to SOA. Mapped from input
              request
          statusCode:
            type: string
            description: >-
              Status of the transaction •  0- Success •  Any value other than 0-
              Failure
            example: "0000"
          statusMessage:
            type: string
            description: Indicates status of transaction
          customerId:
            type: string
            description: Original MSISDN of the subscriber
          data:
            $ref: '#/definitions/SimswapStatusDetails'

  simSwapResponse:
    allOf:
      - required:
          - statusCode
          - statusMessage
          - transactionId
          - supportmessage
        properties:
          transactionId:
            type: string
            description: >-
              Unique identifier for every request to SOA. Mapped from input
              request
          statusCode:
            type: string
            description: >-
              Status of the transaction •  0- Success •  Any value other than 0-
              Failure
            example: "0000"
          statusMessage:
            type: string
            description: Indicates status of transaction

  getNextAuthenticationRequest:
    allOf:
      - required:
          - customerId
        properties:
          previousQuestionsAnswer:
            type: object
            $ref: '#/definitions/QuestionsAnswerObject'

  getNextAuthenticationResponse:
    allOf:
      - required:
          - statusCode
          - statusMessage
          - transactionId
        properties:
          transactionId:
            type: string
            description: >-
              Unique identifier for every request to SOA. Mapped from input
              request
          statusCode:
            type: string
            description: >-
              Status of the transaction •  0- Success •  Any value other than 0-
              Failure
            example: "0000"
          statusMessage:
            type: string
            description: Indicates status of transaction
          customerId:
            type: string
            description: MSISDN of the subscriber
          data:
            $ref: '#/definitions/getNextAuthenticationDetails'

  getNextAuthenticationDetails:
    type: object
    properties:
      evaluationResult:
        type: string
        enum:
          - "SUCCESS"
          - "FAIL"
          - "CONTINUE"
          - "ABORT"
        description: Indicates status of evaluation
      question:
        type: object
        $ref: '#/definitions/questionObject'
      answeroptions:
        type: array
        items:
          $ref: '#/definitions/answeroptionsObject'

  questionObject:
    properties:
      questionKey:
        type: integer
        description: >-
          Previous Question Key
      questionText:
        type: string
        description: >-
          Question Text

  answeroptionsObject:
    properties:
      key:
        type: integer
        description: Answer Key
      value:
        type: string
        description: Answer Text

  QuestionsAnswerObject:
    properties:
      questionKey:
        type: integer
        description: >-
          Previous Question Key
      answerKey:
        type: integer
        description: >-
          Previous Answer Key

  SimswapStatusDetails:
    type: object
    properties:
      status:
        type: string
        description: "The Sim Swap Statuses are returned here"
  
  SIMSwapStatus:
    required:
      - customerId
      - data
      - statusCode
      - statusMessage
    type: object
    properties:
      statusCode:
        type: string
        description: HTTP error code extension
        example: '0000'
      statusMessage:
        type: string
        description: Message.
        example: Successful
      extTransactionId:
        type: string
        description: Transaction ID generated by source system of the request.
        example: 232TXYZ-212
      transactionId:
            type: string
            description: >-
              Transaction Id generated by MADapi internally
      customerId:
        type: string
        description: MSISDN of the customer provided in the input as customerId
        example: '256789999781'
      data:
        $ref: '#/definitions/SimSwapStatusData'
  SIMActivationStatus:
    required:
      - customerId
      - data
      - statusCode
      - statusMessage
    type: object
    properties:
      statusCode:
        type: string
        description: HTTP error code extension
        example: '0000'
      statusMessage:
        type: string
        description: Message.
        example: Successful
      extTransactionId:
        type: string
        description: Transaction ID generated by source system of the request.
        example: 232TXYZ-212
      transactionId:
            type: string
            description: >-
              Transaction Id generated by MADapi internally
      customerId:
        type: string
        description: MSISDN of the customer provided in the input as customerId
        example: '256789999781'
      data:
        $ref: '#/definitions/SimActivationStatusData'
  SIMRecycleStatus:
    required:
      - customerId
      - data
      - statusCode
      - statusMessage
    type: object
    properties:
      statusCode:
        type: string
        description: HTTP error code extension
        example: '0000'
      statusMessage:
        type: string
        description: Message.
        example: Successful
      extTransactionId:
        type: string
        description: Transaction ID generated by source system of the request.
        example: 232TXYZ-212
      transactionId:
            type: string
            description: >-
              Transaction Id generated by MADapi internally
      customerId:
        type: string
        description: MSISDN of the customer provided in the input as customerId
        example: '256789999781'
      data:
        $ref: '#/definitions/SimRecycleStatusData'
  SimSwapStatusData:
    type: object
    required:
      - simSwapSatus
    properties:
      simSwapSatus:
        type: string
        description: >-
          Stutus of the swim swap - whether simswap performed (True or False)
        example: 'True'
  SimActivationStatusData:
    type: object
    required:
      - simActivationSatus
    properties:
      simActivationSatus:
        type: string
        description: >-
          Stutus of the swim activation - whether sim activation performed (True or False)
        example: 'True'
  SimRecycleStatusData:
    type: object
    required:
      - simRecycleSatus
    properties:
      simRecycleSatus:
        type: string
        description: >-
          Stutus of the swim activation - whether sim activation performed (True or False)
        example: 'True'

  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: This is the same transactionId that is sent in the request
      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/<path>"