openapi: 3.0.3
info:
  title: Number Verification
  description: |
    Service Enabling Network Function API to verify that the provided **mobile phone number** is the one used in the device. It verifies that the user is using a device with the same mobile phone number as it is declared.
    It also makes it possible for a Service provider to verify the number itself by returning the phone number associated to the authenticated user's access token.

    NOTE: This portal page is wired to the sandbox (stub) endpoints for testing purposes only. Verification succeeds only for predefined dummy test numbers, one per certified OPCO (see the Phone Number Verify operation).

  version: 1.0.0
servers:
  - url: https://api.ooredoo.com
    description: Ooredoo API gateway

paths:
  /oauth/v4/token:
    post:
      summary: Generate Access Token
      description: Token generation endpoint (client_id & client_secret in headers, grant_type & scope in body)
      parameters:
        - name: client_id
          in: header
          required: true
          description: Client ID of onboarded client.
          schema:
            type: string
            format: password
            default: YVdpCHljK7k1e7BHu2w2vfOXX45Aw22jbCTmAi9EAhD2fyYY
        - name: client_secret
          in: header
          required: true
          description: Client secret of onboarded client.
          schema:
            type: string
            format: password
            default: 5KWqHpiMakslkxnSQZAIQcVsdp2OtimqQBmGCaHpV22UIG7h3TXPS2sl7zsx1GSU
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                grant_type:
                  type: string
                  default: client_credentials
                  description: OAuth grant type
              required:
                - grant_type
      responses:
        '200':
          description: Successful token response
          content:
            application/json:
              schema:
                type: object
                properties:
                  access_token:
                    type: string
                  token_type:
                    type: string
                  expires_in:
                    type: integer
                  consented_on:
                    type: string
                  created_At:
                    type: string
                  expired_At:
                    type: string
        '401':
          $ref: "#/components/responses/Generic401"

  /number-verification/v4/verify:
    post:
      summary: Phone Number Verify
      description: |
        Verifies the specified phone number and returns true/false .

        Sandbox / simulator endpoint — for testing only. Returns "devicePhoneNumberVerified": true ONLY for the predefined dummy test numbers (one per certified OPCO): Algeria +213556031036, Qatar +97433106036, Kuwait +96550310036, Palestine +970599031036. Any other number returns false.
      operationId: phoneNumberVerify
      parameters:
        - in: header
          name: x-correlator
          required: false
          description: Correlation id for the different services
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NumberVerificationRequestBody'
        required: true
      responses:
        '200':
          description: OK
          headers:
            x-correlator:
              description: Correlation id for the different services
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NumberVerificationMatchResponse'
        '400':
          $ref: '#/components/responses/Generic400'
        '401':
          $ref: '#/components/responses/Generic401'
        '403':
          $ref: '#/components/responses/PhoneNumberVerificationPermissionDenied403'
        '500':
          $ref: '#/components/responses/Generic500'
        '503':
          $ref: '#/components/responses/Generic503'
        '504':
          $ref: '#/components/responses/Generic504'
      security:
        - BearerAuth: []
            
  /number-verification/v4/device-phone-number:
    get:
      summary: Returns The Phone Number
      description: |
        Returns the phone number so the API clients can verify the number themselves.
      operationId: phoneNumberShare
      parameters:
        - in: header
          name: x-correlator
          required: false
          description: Correlation id for the different services
          schema:
            type: string
      responses:
        '200':
          description: OK
          headers:
            x-correlator:
              description: Correlation id for the different services
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NumberVerificationShareResponse'
        '400':
          $ref: '#/components/responses/Generic400'
        '401':
          $ref: '#/components/responses/Generic401'
        '403':
          $ref: '#/components/responses/PhoneNumberVerificationPermissionDenied403'
        '500':
          $ref: '#/components/responses/Generic500'
        '503':
          $ref: '#/components/responses/Generic503'
        '504':
          $ref: '#/components/responses/Generic504'
      security:
        - BearerAuth: []
            
components:
  securitySchemes:
    BearerAuth:
      type: http
      name: Authorization
      in: header
      scheme: bearer
      bearerFormat: JWT

  headers:
    x-correlator:
      description: Correlation id for the different services
      schema:
        type: string
  schemas:
    NumberVerificationRequestBody:
      type: object
      description: Payload to verify the phone number.
      minProperties: 1
      maxProperties: 1
      properties:
        phoneNumber:
          type: string
          pattern: '^\+[1-9][0-9]{4,14}$'
          default: '+97433106036'
          description: MSISDN in order to be globally unique it has to be formatted in international format, according to E.164 standard, prefixed with '+'ex. +97433106036
        hashedPhoneNumber:
          description: Hashed phone number. SHA-256 of the mobile phone number in **E.164 format (starting with country code)**. Prefixed with '+'.
          type: string
          default: 32f67ab4e4312618b09cd23ed8ce41b13e095fe52b73b2e8da8ef49830e50dba
    NumberVerificationMatchResponse:
      type: object
      description: Number verification result
      required:
        - devicePhoneNumberVerified
      properties:
        devicePhoneNumberVerified:
          $ref: '#/components/schemas/DevicePhoneNumberVerified'
    NumberVerificationShareResponse:
      type: object
      description: Number verification share result
      required:
        - devicePhoneNumber
      properties:
        devicePhoneNumber:
          $ref: '#/components/schemas/DevicePhoneNumber'
    DevicePhoneNumber:
      type: string
      pattern: '^\+[1-9][0-9]{4,14}$'
      default: '+97433106036'
      description: MSISDN in order to be globally unique it has to be formatted in international format, according to E.164 standard, prefixed with '+'.
    DevicePhoneNumberVerified:
      description: Number verification. True, if it matches
      type: boolean
    ErrorInfo:
      type: object
      required:
        - status
        - code
        - message
      properties:
        status:
          type: integer
          description: HTTP response status code
        code:
          type: string
          description: Code given to this error
        message:
          type: string
          description: Detailed error description
  responses:
    Generic400:
      description: Problem with the client request
      headers:
        x-correlator:
          $ref: "#/components/headers/x-correlator"
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            status: 400
            code: INVALID_ARGUMENT
            message: Client specified an invalid argument, request body or query param
    Generic401:
      description: Unauthorized
      headers:
        x-correlator:
          $ref: "#/components/headers/x-correlator"
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          examples:
            GENERIC_401_UNAUTHENTICATED:
              description: Request cannot be authenticated
              value:
                status: 401
                code: UNAUTHENTICATED
                message: Request not authenticated due to missing, invalid, or expired credentials.
            GENERIC_401_AUTHENTICATION_REQUIRED:
              description: New authentication is needed, authentication is no longer valid
              value:
                status: 401
                code: AUTHENTICATION_REQUIRED
                message: New authentication is required.
    PhoneNumberVerificationPermissionDenied403:
      description: |
        Client does not have sufficient permission.
        In addition to regular scenario of `PERMISSION_DENIED`, other scenarios may exist:
          - Client authentication was not via mobile network.(`{"code": "NUMBER_VERIFICATION.USER_NOT_AUTHENTICATED_BY_MOBILE_NETWORK","message": "Client must authenticate via the mobile network to use this service"}`)
          - Phone number cannot be deducted from access token context.(`{"code": "INVALID_TOKEN_CONTEXT","message": "Phone number cannot be deducted from access token context"}`)
      headers:
        x-correlator:
          $ref: "#/components/headers/x-correlator"
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          examples:
            GENERIC_403_PERMISSION_DENIED:
              description: Permission denied. 
              value:
                status: 403
                code: PERMISSION_DENIED
                message: Client does not have sufficient permissions to perform this action.
            GENERIC_403_USER_NOT_AUTHENTICATED_BY_MOBILE_NETWORK:
              value:
                status: 403
                code: NUMBER_VERIFICATION.USER_NOT_AUTHENTICATED_BY_MOBILE_NETWORK
                message: Client must authenticate via the mobile network to use this service
            GENERIC_403_INVALID_TOKEN_CONTEXT:
              value:
                status: 403
                code: INVALID_TOKEN_CONTEXT
                message: Phone number cannot be deducted from access token context
    Generic500:
      description: Server error
      headers:
        x-correlator:
          $ref: "#/components/headers/x-correlator"
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            status: 500
            code: INTERNAL
            message: Server error
    Generic503:
      description: Service unavailable. Typically the server is down.
      headers:
        x-correlator:
          $ref: "#/components/headers/x-correlator"
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            status: 503
            code: UNAVAILABLE
            message: Service unavailable
    Generic504:
      description: Request time exceeded. If it happens repeatedly, consider reducing the request complexity
      headers:
        x-correlator:
          $ref: "#/components/headers/x-correlator"
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            status: 504
            code: TIMEOUT
            message: Request timeout exceeded. Try later.