swagger: "2.0"
info:
  description: |-
    - Retrieve and validate SIM information of a customer's MSISDN. Such as PUK, IMSI, SIM No., Registration status.
    - Retrieve and Reserve available MSISDN's. A customer who needs a new connection can pick a desired number from the returned list.

    **Change log:**
    **11-Mar-21: Change Id: 2099216440**
      - Added **/resourcePool** to retrieve and reserve available MSISDNs.
      - Added **/validate** POST to check if the MSISDN+SIM No. match

    **20-Aug-21:**
      - Added /customers/{customerId}/simSwap/status to get SIM Swap status
      - Added /customers/{customerId}/simSwap to initiate SIM Swap process
      - Added /customers/{customerId}/simSwap/nextAuthentication to get next Q&A

  version: "1.1"
  title: MTN Customer SIM Management API
host: api.mtn.com
basePath: "/v1/simManagement"
schemes:
  - https
consumes:
  - application/json
produces:
  - application/json

paths:
  /customers/{customerId}/sim/registrationStatus:
    get:
      tags:
        - Customer Registration Status
      summary: Provides the subscriber with a summary of the status of their sim registration
      description: Retrieve notification on sim registration status
      parameters:
        - name: customerId
          in: path
          description: ID of the customer. It could be MSISDN, email address, or any other customer identifier. if customerId is msisdn, then the format must be E.123
          required: true
          type: string
        - name: transactionId
          in: header
          type: string
          description: Client generated Id to include for tracing requests, so that the API can easily trace the HTTP request all the way from a client to MTNs backend processes (via our proxies). Each time a request is made to an MTN API the client should include a unique request reference in the HTTP Header. The value must be between 5 and 20 characters, and consist of ASCII letters, digits, or the characters +, /, =, and -. Invalid or blank IDs will be ignored and replaced with generated ones. MTN may use this to detect duplicate transactions from the client, but this functionality is not always guaranteed, so clients must make their own efforts to prevent duplicate transactions. MTN will also log the transactionId in order to assist with debugging and to correlate transactions processed by the API to requests from the client.
          required: false
      responses:
        "200":
          description: Success
          schema:
            $ref: '#/definitions/registrationStatusResponse'
        "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: Unsopported media Type
          schema:
            $ref: '#/definitions/Error'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/Error'

  /customers/{customerId}/sim/simDetails:
    get:
      tags:
        - SIM Card Information
      summary: Provides additional information about the sim card linked to an msisdn.
      description: Returns the SIM Number, PIN1, PIN2, PUK1, PUK2, TransportKey, KI, IMSI, KIT and VIP Flag associated with the sim card linked to an msisdn.
      parameters:
        - name: customerId
          in: path
          description: ID of the customer. It should be an MSISDN with E.123 format
          required: true
          type: string
        - name: x-country-code
          in: header
          description: Country ISO Code
          required: true
          type: string
        - name: requestorId
          in: query
          description: The requestor Id (mandatory for Nigeria)
          required: false
          type: string
        - name: channel
          in: query
          description: The Channel
          required: false
          type: string
        - name: transactionId
          in: header
          type: string
          description: Client generated Id to include for tracing requests, so that the API can easily trace the HTTP request all the way from a client to MTNs backend processes (via our proxies). Each time a request is made to an MTN API the client should include a unique request reference in the HTTP Header. The value must be between 5 and 20 characters, and consist of ASCII letters, digits, or the characters +, /, =, and -. Invalid or blank IDs will be ignored and replaced with generated ones. MTN may use this to detect duplicate transactions from the client, but this functionality is not always guaranteed, so clients must make their own efforts to prevent duplicate transactions. MTN will also log the transactionId in order to assist with debugging and to correlate transactions processed by the API to requests from the client.
          required: false
        - name: targetSystem
          in: header
          description: The target backend system name (mandatory for Nigeria)
          required: false
          type: string
        - name: operation
          in: query
          description: SIM operation
          required: false
          type: string
          default: SIM_INFORMATION
          enum:
            - SIM_INFORMATION
            - MOBILE_INFORMATION
      responses:
        "200":
          description: Success
          schema:
            $ref: '#/definitions/simInformationReponse'
        "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: Unsopported media Type
          schema:
            $ref: '#/definitions/Error'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/Error'

  /customers/{customerId}/sim/simDetails/validate:
    post:
      tags:
        - SIM Card Information
      summary: validate SIM information
      description:  validate if the SIM information provided is attached to the customerId (MSISDN)
      parameters:
        - name: customerId
          in: path
          type: string
          description: Identifier for the customer. e.g. an MSISDN.
          required: true
          x-example: 256789999695
        - name: transactionId
          in: header
          type: string
          description: External transaction Identifier
          required: false
          x-example: 14336423232ABCD
        - in: body
          name: simDetails
          description: "SIM card information"
          required: true
          schema:
            $ref: "#/definitions/SimDetails"
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/simInformationReponse'
        "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: Unsopported media Type
          schema:
            $ref: '#/definitions/Error'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/Error'

  /customers/sim/resourcePool:
    get:
      tags:
        - Resource Pool
      summary: Retrieve available MSISDN's.
      description: Retrieve available MSISDN's. A customer who needs a new connection can pick a desired number from the returned list.
      parameters:
        # - name: customerId
        #   in: path
        #   type: string
        #   description: ID of the customer. e.g. the MSISDN
        #   required: true
        #   x-example: customerId
        - name: transactionId
          in: header
          type: string
          description: External transaction Identifier
          required: false
          x-example: 14336423232ABCD
        - name: resourceType
          in: query
          type: string
          description: Type of resource to be retrieved
          enum:
            - MSISDN
            - IMSNo
            - FXLNo
          x-example: MSISDN
        - name: pattern
          in: query
          type: string
          description: Desired pattern of the resources to be retrieved. This should be a regular expression. For more, refer to https://swagger.io/docs/specification/data-models/data-types/
          x-example: "/^(074)([0-9]8)$/g"
        - name: numberOfRec
          in: query
          type: integer
          description: Number or resources to be returned
          x-example: 5
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/resourcePoolResp'
        "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: Unsopported media Type
          schema:
            $ref: '#/definitions/Error'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/Error'

  /customers/{customerId}/sim/resourcePool/reserve:
    post:
      tags:
        - Resource Pool
      summary: Reserve a resource such as an MSISDN
      description:  Reserve a resource such as an MSISDN so that it cannot be retrieved in the operation for retrieving available resources (MSISDN's)
      parameters:
        - name: customerId
          in: path
          type: string
          description: ID of the customer. e.g. an MSISDN.
          required: true
          x-example: customerId
        - name: transactionId
          in: header
          type: string
          description: External transaction Identifier
          required: false
          x-example: 14336423232ABCD
        - in: body
          name: resourcePoolReserve
          description: "Fetches Free MSISDN from the resource pool"
          required: true
          schema:
            $ref: "#/definitions/resourcePoolData"
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/resourcePoolResp'
        "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: Unsopported media Type
          schema:
            $ref: '#/definitions/Error'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/Error'

  /customers/{customerId}/simSwap/status:
    get:
      tags:
        - Sim Swap
      summary: Get Sim Swap status
      description: Gets the status of the Sim Swap activity
      parameters:
        - name: customerId
          in: path
          required: true
          type: string
          description: ID of the customer. It should be an MSISDN with E.123 format
        - name: transactionId
          in: header
          required: false
          type: string
          description: Client generated Id to include for tracing requests, so that the API can easily trace the HTTP request all the way from a client to MTNs backend processes (via our proxies).
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/SimswapStatusResponse'

        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 Not allowed"
          schema:
            $ref: "#/definitions/Error"
        500:
          description: "Internal Server Error"
          schema:
            $ref: "#/definitions/Error"

  /customers/{customerId}/simSwap:
    put:
      tags:
        - Sim Swap
      summary: Initiate the SIM swap process
      description: Initiates the SIM swap process which validates and generates Q&A for the Customer
      parameters:
        - name: customerId
          in: path
          required: true
          type: string
          description: ID of the customer. It should be an MSISDN with E.123 format
        - name: transactionId
          in: header
          type: string
          description: Unique identifier of the transaction.
        - name: requestBody
          in: body
          required: true
          schema:
            $ref: '#/definitions/simSwapRequest'
        - name: x-country-code
          in: header
          description: Country ISO Code
          required: true
          type: string
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/simSwapResponse'

        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 Not allowed"
          schema:
            $ref: "#/definitions/Error"
        500:
          description: "Internal Server Error"
          schema:
            $ref: "#/definitions/Error"

  /customers/{customerId}/simSwap/nextAuthentication:
    post:
      tags:
        - Sim Swap
      summary: Get next Authentication (Q&A)
      description: Perform a Q&A based Sim Swap (Sim swap process done via digital channels by Customer manually)
      parameters:
        - name: customerId
          type: string
          in: path
          required: true
        - name: transactionId
          type: string
          in: header
        - name: requestBody
          in: body
          required: true
          schema:
            $ref: '#/definitions/getNextAuthenticationRequest'
      responses:
        201:
          description: OK
          schema:
            $ref: '#/definitions/getNextAuthenticationResponse'

        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 Not allowed"
          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"

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