openapi: 3.0.3
info:
  description: |
    API to check the ownership of the MSISDN (Mobile Number). 

    # Introduction

    This API lets API Consumers to check the ownership of the number.

    # API resources 
    
    # Further info and support

    (FAQs will be added in a later version of the documentation)
  version: 1.0.0
  title: Mobile Number ownership inquiry API
  termsOfService: https://api.omantel.om/docs/terms/
  contact:
    email: MiddlewareESB@omantel.om
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
externalDocs:
  description: Product documentation at https://developer.omantel.om/
  url: https://developer.omantel.om/
servers:
  - url: https://apigw.omantel.om
    variables:
      apiRoot:
        default: https://apigw.omantel.om
        description: API root
      basePath:
        default: /msisdn-ownership-inquiry/v1
        description: Base path for the ownership inquiry API
tags:
  - name: Ownership inquiry
    description: Operations to check the ownership inquiry of the mobile number
paths:
  /msisdn-ownership-inquiry/v1/check-ownership:
    get:
      security:
        - oAuth2ClientCredentials: []
      tags:
        - Ownership inquiry
      summary: Check Ownership of the number 
      operationId: getOwnershipStatus
      description: Returns Ownership status of the specified number 
      parameters:
        - name: mobileNumber
          in: query
          description: Mobile number of Omantel customer with or without country code.
          example: 9250xxxx
          required: true
          schema:
            type: string
        - name: customerId
          in: query
          description: Civil ID or Resident ID or Passport number of the customer owning the number.
          example: 1234567
          required: true
          schema:
            type: string
        - name: customerIdType
          in: query
          description: |
            Customer Id Type of the customer like 'civilId', 'residentId', or 'passportNo'.
          example: civilId
          required: true
          schema:
            type: string
            enum:
              - civilId
              - residentId
              - passportNo


      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  is-owner:
                    type: boolean
                    example: true
                    description: |
                     Returns `true` if the specified customer owns the specified mobile number, `false` otherwise.
        401:
          $ref: "#/components/responses/Generic401"
        403:
          $ref: "#/components/responses/Generic403"
        404:
          $ref: "#/components/responses/Generic404"
        500:
          $ref: "#/components/responses/Generic500"
        503:
          $ref: "#/components/responses/Generic503"
        504:
          $ref: "#/components/responses/Generic504"
components:
  schemas:
    ErrorInfo:
      type: object
      required:
        - code
        - message
        - status
      properties:
        code:
          type: string
          description: Code given to this error
        status:
          type: string
          description: HTTP response status code
        message:
          type: string
          description: Detailed error description
  responses:
    Generic400:
      description: Invalid input
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          example:
            code: INVALID_ARGUMENT
            status: 400
            message: "Schema validation failed at  ..."
    Generic401:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          example:
            code: UNAUTHORIZED
            status: 401
            message: "Authorization failed: ..."
    Generic403:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          example:
            code: FORBIDDEN
            status: 403
            message: "Operation not allowed: ..."
    Generic404:
      description: Customer Not Found - check if specified mobile number is a valid Omantel customer
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          example:
            code: NOT_FOUND
            status: 404
            message: "The specified mobile number is not found"
    Generic500:
      description: Server error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          example:
            code: SERVER_ERROR
            status: 500
            message: "Server Error"
    Generic503:
      description: Service unavailable
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          example:
            code: SERVICE_UNAVAILABLE
            status: 503
            message: "Service unavailable"
    Generic504:
      description: Request timeout exceeded
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          example:
            code: REQUEST_TIMEOUT_EXCEEDED
            status: 504
            message: "Request timeout exceeded"
  securitySchemes:
    oAuth2ClientCredentials:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://apigw.omantel.om/oauth2/accesstoken
          scopes: {}