MTN Group Sim Swap API

openapi: 3.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.\n\n  - **'/simSwap/verifyStatus'** capability is used to verify sim swap status as true or false.\n  - **'/simActivation/verifyStatus'** capability is used to verify sim activation status as true or false.\n  - **'/simRecycle/verifyStatus'** capability is used to verify sim recycle status as true or false.\n  - **'/simSwap/validateStatus'** capability is used to validate sim swap status as true or false.\n  - **'/simActivation/validateStatus'** capability is used to validate sim activation status as true or false.\n  - **'/simRecycle/validateStatus'** capability is used to validate sim recycle status as true or false."
  version: '1.0'
  title: MTN Customer SIM Verification Sim Swap API
servers:
- url: https://api.mtn.com/v1/simVerification
security:
- APIKeyAuth: []
- OAuth2: []
tags:
- name: Sim Swap
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
        schema:
          type: string
      - name: senderId
        in: query
        description: Identifier of the request originating system, e.g. 'IVR', 'My MTN App'etc.
        required: true
        schema:
          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
        schema:
          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
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SIMSwapStatus'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '405':
          description: Method No Allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '406':
          description: Not acceptable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/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
        schema:
          type: string
      - name: senderId
        in: query
        description: Identifier of the request originating system, e.g. 'IVR', 'My MTN App'etc.
        required: true
        schema:
          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
        schema:
          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
        schema:
          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
        schema:
          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
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SIMSwapStatus'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '405':
          description: Method No Allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '406':
          description: Not acceptable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    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>
    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'
    SimSwapStatusData:
      type: object
      required:
      - simSwapSatus
      properties:
        simSwapSatus:
          type: string
          description: Stutus of the swim swap - whether simswap performed (True or False)
          example: 'True'
    SIMSwapStatus:
      $ref: '#/components/schemas/Status'
      properties:
        data:
          $ref: '#/components/schemas/SimSwapStatusData'
  securitySchemes:
    APIKeyAuth:
      type: apiKey
      name: x-API-Key
      in: header
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          scopes: {}
          tokenUrl: https://api.mtn.com/oauth/clent_credentials/accesstoken