reviewer comments applied

code/API_definitions/CAMARA/NUMBER_VERIFICATION_API.md

@@ -23,12 +23,12 @@ Before starting to use the API, the developer needs to know about the below spec
 
 Two endpoints are defined in Number Verification API:
 
-- POST /number-verification/v0/verify : Verifies if the specified phone number (clear or hashed format) matches the one that the user is currently using.
+- POST /number-verification/v0/verify : Verifies if the specified phone number (plain text or hashed format) matches the one that the user is currently using.
 - GET /number-verification/v0/device-phone-number : Returns the phone number associated with the access token so API clients can verify the number themselves.
 
 **Authentication**
 
-Security access keys such as OAuth 2.0 3-legged Access Tokens used by Client applications to invoke this API with dedicated scope. Client **must authenticate via IP** to use this service.
+Security access keys such as OAuth 2.0 3-legged Access Tokens used by Client applications to invoke this API with dedicated scope. Client **must use network based authentication methods** to use this service. 
 
 Sample API invocations are presented in Section 4.6.
 
@@ -50,7 +50,7 @@ Following table defines API endpoints of exposed REST based for Number Verificat
 
 | **Endpoint** | **Operation** | **Description** |
 | -------- | --------- | ----------- |
-| POST /number-verification/v0/verify | **Request to verify a number** | Create request in order to verify if the specified phone number (clear or hashed format) matches the one that the user is currently using |
+| POST /number-verification/v0/verify | **Request to verify a number** | Create request in order to verify if the specified phone number (plain text or hashed format) matches the one that the user is currently using |
 | GET /number-verification/v0/device-phone-number | **Request to get the device phone number** | Create a request to get the phone number associated with the access token so the API clients can verify the number themselves |
 
 

code/API_definitions/CAMARA/number_verification.yaml

@@ -12,7 +12,7 @@ info:
 
     # Resources and Operations overview
     This API currently provides two endpoints where both require a **3-legged token** and authentication via **mobile network** (excluding for example by SMS/OTP or user/password as an authentication method):
-    - The first one checks if the user mobile phone number matches the phone number associated with the mobile device. It can receive either a hashed phone number or a clear phone number as input and it compares the received input with the authenticated user's phone number associated to the access token in order to respond **true/false**.
+    - The first one checks if the user mobile phone number matches the phone number associated with the mobile device. It can receive either a hashed or a plain text phone number as input and it compares the received input with the authenticated user's phone number associated to the access token in order to respond **true/false**.
     - The next one retrieves the phone number associated to the user's token and returns it so the verification can be made by the service provider.
   version: 0.2.0
   termsOfService: http://example.com/terms/
@@ -34,17 +34,17 @@ servers:
         description: Base path for the number verification API
 tags:
   - name: Phone number verify
-    description: API operation to verify a phone number received as input. It can be received either in clear or hashed format.
+    description: API operation to verify a phone number received as input. It can be received either in plain text or hashed format.
   - name: Phone number share
     description: API operation to return the phone number associated to the access token.
 paths:
   /verify:
     post:
       tags:
         - Phone number verify
-      summary: Verifies if the received hashed/clear phone number matches the phone number associated with the access token
+      summary: Verifies if the received hashed/plain text phone number matches the phone number associated with the access token
       description: |-
-        Verifies if the specified phone number (clear or hashed format) matches the one that the user is currently using.
+        Verifies if the specified phone number (plain text or hashed format) matches the one that the user is currently using.
          - The number verification will be done for the user that has authenticated via mobile network and so their `sub` is in the access token
          - 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