MTN SIM Verification

swagger: "2.0"
info:
  description:  |-
    This API is used to verify/validate SIM Swap status, SIM Activation status and SIM Recycle status of a customer's msisdn.
   
      - **'/simSwap/verifyStatus'** capability is used to verify sim swap status as true or false.
      - **'/simActivation/verifyStatus'** capability is used to verify sim activation status as true or false.
      - **'/simRecycle/verifyStatus'** capability is used to verify sim recycle status as true or false.
      - **'/simSwap/validateStatus'** capability is used to validate sim swap status as true or false.
      - **'/simActivation/validateStatus'** capability is used to validate sim activation status as true or false.
      - **'/simRecycle/validateStatus'** capability is used to validate sim recycle status as true or false.

  version: "1.0"
  title: MTN Customer SIM Verification API
host: api.mtn.com
basePath: "/v1/simVerification"
schemes:
  - https
consumes:
  - application/json
produces:
  - application/json
securityDefinitions: 
  APIKeyAuth:
    type: apiKey
    name: x-API-Key
    in: header
  OAuth2:
    type: oauth2
    flow: application
    tokenUrl: 'https://api.mtn.com/oauth/clent_credentials/accesstoken'
security:
  - APIKeyAuth: []
  - OAuth2: []

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
        - name: partnerId
          in: header
          description: Unique identifier generated by source channel for tracing purposes. This field is manadory for MTN-Nigeria.
          required: true
          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
        - name: partnerId
          in: header
          description: Unique identifier generated by source channel for tracing purposes. This field is manadory for MTN-Nigeria.
          required: true
          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
        - name: partnerId
          in: header
          description: Unique identifier generated by source channel for tracing purposes. This field is manadory for MTN-Nigeria.
          required: true
          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
        - name: partnerId
          in: header
          description: Unique identifier generated by source channel for tracing purposes. This field is manadory for MTN-Nigeria.
          required: true
          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
        - name: partnerId
          in: header
          description: Unique identifier generated by source channel for tracing purposes. This field is manadory for MTN-Nigeria.
          required: true
          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:
  
  SIMSwapStatus:
    $ref: '#/definitions/Status'
    properties:
     data:
      $ref: '#/definitions/SimSwapStatusData'
  SIMActivationStatus:
    $ref: '#/definitions/Status'
    properties:
      data:
       $ref: '#/definitions/SimActivationStatusData'
  SIMRecycleStatus:
    $ref: '#/definitions/Status'
    properties:
      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'

  Status:
    required:
      - customerId
      - data
      - statusCode
      - statusMessage
    type: object
    properties:
      statusCode:
        type: string
        description: Status code return to 3PP. It returns '0000' , if request verification/validation holds true
        example: '0000'
      statusMessage:
        type: string
        description: Status Message. 
        example: Success
      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
            example: 2022052510001
      customerId:
        type: string
        description: MSISDN of the customer provided in the input as customerId
        example: '256789999781'
  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>"