openapi: 3.2.0
info:
  title: SIM Swap Verification SIM Swap API
  version: '0.1'
  description: "The SIM Swap Verification API provides information about an MSISDN's sim-swap details.  \n## Supported Operations \n1. Get last SIM Swap date of a phone Number."
servers:
- url: https://api.mtn.com/v1/mobile/phoneNumbers
security:
- OAuth2: []
tags:
- name: SIM Swap API
paths:
  /{phoneNumber}/simswap-date:
    get:
      tags:
      - SIM Swap API
      summary: Retrieve sim-swap date.
      description: Retrieve last sim-swap date from network operator of phoneNumber as identified by customerId (customer's MSISDN).
      parameters:
      - name: phoneNumber
        in: path
        description: phoneNumber represented as International  ITU-T E.164.
        required: true
        schema:
          type: string
      - name: transactionId
        in: header
        required: true
        description: transactionId
        schema:
          type: string
      - name: partnerId
        in: query
        description: partnerId
        schema:
          type: string
      - name: prefLang
        in: query
        description: prefLang
        schema:
          type: string
      - name: requesterId
        in: query
        description: requesterId
        schema:
          type: string
      responses:
        '200':
          description: Success
          headers:
            transactionId:
              description: Client generated Id to include for tracing requests
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/simswapResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '403':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error403'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404'
        '405':
          description: Method No Allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error405'
        '408':
          description: Time out
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error408'
        '415':
          description: Not acceptable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error415'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
        '503':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
components:
  schemas:
    Error400:
      type: object
      properties:
        statusCode:
          type: string
          description: HTTP error code extension
          example: '5000'
        statusMessage:
          type: string
          description: Invalid Parameters
          example: The input parameters provided are invalid
        SupportMessage:
          type: string
          description: Detailed error Message
          example: Unsupported input, please enter a valid 'msisdn' value
          enum:
          - Unsupported input, please enter a valid 'msisdn' value.
          - Invalid country code
        transactionId:
          type: string
          description: Id for tracing.
          example: fg545f-cf4gg4fd55-fdg85hg6
    Error408:
      type: object
      properties:
        statusCode:
          type: string
          description: HTTP error code extension
          example: '3003'
        statusMessage:
          type: string
          description: The request timed out.
          example: Timeout
        supportMessage:
          type: string
          description: The server took too long to respond.
          example: Request timed out
        transactionId:
          type: string
          description: Id for tracing.
          example: fg545f-cf4gg4fd55-fdg85hg6
    simswapResponse:
      required:
      - customerId
      - data
      - statusCode
      - statusMessage
      type: object
      properties:
        statusCode:
          type: string
          enum:
          - '0000'
          - '1022'
          description: "HTTP error code extension:\n * `0000` - Success Response when sim swap is performed\n * `1022` - When No Simswap is performed\n"
          example: '0000'
        statusMessage:
          type: string
          description: Message.
          example: Successful
        customerId:
          type: string
          description: MSISDN of the customer provided in the input as customerId
          example: '256789999781'
        transactionId:
          type: string
          description: transaction ID From the backend provider system for tracing.
          example: 232TXYZ-212
        data:
          $ref: '#/components/schemas/simswapData'
    Error405:
      type: object
      description: Method not Allowed
      properties:
        statusCode:
          type: string
          description: HTTP error code extension
          example: '4001'
        statusMessage:
          type: string
          example: Not Allowed
        supportMessage:
          type: string
          example: Method Not Allowed
        transactionId:
          type: string
          description: Id for tracing.
          example: fg545f-cf4gg4fd55-fdg85hg6
    Error401:
      type: object
      properties:
        statusCode:
          type: string
          description: HTTP error code extension
          example: '4000'
        statusMessage:
          type: string
          description: Short description of the error
          example: Unauthorised
        supportMessage:
          type: string
          description: Longer description of the error
          example: Please verify token environment or access token or API key
        transactionId:
          type: string
          description: Id for tracing.
          example: fg545f-cf4gg4fd55-fdg85hg6
    Error415:
      type: object
      properties:
        statusCode:
          type: string
          description: HTTP error code extension
          example: '5000'
        statusMessage:
          type: string
          description: Short description of the error
          example: Unsupported Media Type
        supportMessage:
          type: string
          description: Longer description of the error
          example: Unsupported Media Type. It should be application/json
        transactionId:
          type: string
          description: Id for tracing.
          example: fg545f-cf4gg4fd55-fdg85hg6
    simswapData:
      type: object
      properties:
        lastSimSwapDate:
          type: string
          description: The date and time when the last sim swap performed on the SIM of the customerId provided represented as an ISO 8601:2004 [ISO8601 2004] YYYY-MM-DDTHH:MM:SSZ format. If the date cannot be determined, the value will be an empty string
          example: '2020-04-20T15:22:11+03:00'
    Error403:
      type: object
      properties:
        statusCode:
          type: string
          description: HTTP error code extension
          example: '6000'
        statusMessage:
          type: string
          description: Short description of the error
          example: Forbidden
        supportMessage:
          type: string
          description: Longer description of the error
          example: Please verify token environment or access token or API key
        transactionId:
          type: string
          description: Id for tracing.
          example: fg545f-cf4gg4fd55-fdg85hg6
    Error500:
      type: object
      properties:
        statusCode:
          type: string
          description: HTTP error code extension
          example: '3001'
        statusMessage:
          type: string
          description: Internal Server Error
          example: Internal Server Error
        supportMessage:
          type: string
          description: Error
          example: Internal Server Error
        transactionId:
          type: string
          description: Id for tracing.
          example: fg545f-cf4gg4fd55-fdg85hg6
    Error404:
      type: object
      description: phoneNumber not found
      properties:
        statusCode:
          type: string
          description: HTTP error code extension
          example: '1000'
        statusMessage:
          type: string
          example: phoneNumber not found.
        supportMessage:
          type: string
          example: Queried phoneNumber could not be found
        transactionId:
          type: string
          description: Id for tracing.
          example: fg545f-cf4gg4fd55-fdg85hg6
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          scopes: {}
          tokenUrl: https://api.mtn.com/v1/oauth/access_token?grant_type=client_credentials