GSMA Phone Number Verify API

openapi: 3.2.0
info:
  title: Number Verification Phone Number Verify API
  description: 'This API can verify or retrieve the **mobile phone number** that is currently allocated by the network operator to the SIM in the end user''s device


    In this API **phone number** refers to the mobile phone number.'
  version: wip
  x-camara-commonalities: 0.8.0
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: '{apiRoot}/number-verification/vwip'
  variables:
    apiRoot:
      default: http://localhost:9091
      description: API root, defined by the service provider, e.g. `api.example.com` or `api.example.com/somepath`
tags:
- name: Phone Number Verify
  description: API operation to verify a phone number received as input. It can be received either in plain text or hashed format.
paths:
  /verify:
    post:
      tags:
      - Phone Number Verify
      summary: Verifies if the received hashed/plain text phone number matches the phone…
      description: 'Verifies if the specified phone number (either in plain text or hashed format) matches the one that the user is currently using. Only one of the plain or hashed formats must be provided.

        - The number verification will be done for the user that has authenticated via mobile network

        - It returns true/false depending on if the hashed phone number received as input matches the authenticated user''s `device phone number` associated to the access token'
      operationId: phoneNumberVerify
      parameters:
      - $ref: ../common/CAMARA_common.yaml#/components/parameters/x-correlator
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NumberVerificationRequestBody'
        required: true
      responses:
        '200':
          description: OK
          headers:
            x-correlator:
              $ref: ../common/CAMARA_common.yaml#/components/headers/x-correlator
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NumberVerificationMatchResponse'
        '400':
          $ref: ../common/CAMARA_common.yaml#/components/responses/Generic400
        '401':
          $ref: ../common/CAMARA_common.yaml#/components/responses/Generic401
        '403':
          $ref: '#/components/responses/PhoneNumberVerificationPermissionDenied403'
      security:
      - openId:
        - number-verification:verify
components:
  schemas:
    DevicePhoneNumberVerified:
      description: Number verification. True, if it matches
      type: boolean
    NumberVerificationRequestBody:
      type: object
      description: Payload to verify the phone number.
      minProperties: 1
      maxProperties: 1
      properties:
        phoneNumber:
          $ref: ../common/CAMARA_common.yaml#/components/schemas/PhoneNumber
        hashedPhoneNumber:
          description: Hashed phone number. SHA-256 (in hexadecimal representation) of the mobile phone number in **E.164 format (starting with country code)**. Prefixed with '+'.
          type: string
          pattern: ^[a-fA-F0-9]{64}$
          maxLength: 64
          example: 32f67ab4e4312618b09cd23ed8ce41b13e095fe52b73b2e8da8ef49830e50dba
    NumberVerificationMatchResponse:
      type: object
      description: Number verification result
      required:
      - devicePhoneNumberVerified
      properties:
        devicePhoneNumberVerified:
          $ref: '#/components/schemas/DevicePhoneNumberVerified'
  responses:
    PhoneNumberVerificationPermissionDenied403:
      description: "Client does not have sufficient permission.\nIn addition to regular scenario of `PERMISSION_DENIED`, other scenarios may exist:\n  - Client authentication was not via mobile network. In order to check the authentication method, AMR parameter value in the 3-legged user's access token can be used and make sure that the authentication was not either by SMS+OTP nor username/password (`{\"code\": \"NUMBER_VERIFICATION.USER_NOT_AUTHENTICATED_BY_MOBILE_NETWORK\",\"message\": \"Client must authenticate via the mobile network to use this service\"}`)\n"
      headers:
        x-correlator:
          $ref: ../common/CAMARA_common.yaml#/components/headers/x-correlator
      content:
        application/json:
          schema:
            allOf:
            - $ref: ../common/CAMARA_common.yaml#/components/schemas/ErrorInfo
            - type: object
              properties:
                status:
                  enum:
                  - 403
                code:
                  enum:
                  - PERMISSION_DENIED
                  - NUMBER_VERIFICATION.USER_NOT_AUTHENTICATED_BY_MOBILE_NETWORK
          examples:
            GENERIC_403_PERMISSION_DENIED:
              description: Permission denied. OAuth2 token access does not have the required scope or when the user fails operational security
              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
  securitySchemes:
    openId:
      description: OpenID Connect authentication.
      type: openIdConnect
      openIdConnectUrl: https://example.com/.well-known/openid-configuration
externalDocs:
  description: Project documentation at CAMARA
  url: https://github.com/camaraproject/NumberVerification