[WIP] feat: add optional 'ageTiers' for granular risk assessment

code/API_definitions/device-swap.yaml

@@ -28,8 +28,10 @@ info:
       - POST retrieve-date: Provides timestamp of latest device swap, if any, for a given phone number.
           - If no swap has been performed and the network operator supports unlimited DeviceSwap monitoring timeframe, the API will return the first phone number usage in a device (the timestamp of the first time that the phone number was connected to the network, it is, the first time that the SIM is installed in a device).
           - If the latest device swap date (or the first phone number usage, if no device swap) cannot be communicated due to local regulations (or Network Operator internal privacy policies) preventing the safekeeping of the information for longer than the stated period, a `null` value will be returned. Optionally, a `monitoredPeriod` could be provided to indicate monitored time frame (in days) supported by the Network Operator. In this case the response must be treated as "there were no device swap events during 'monitoredPeriod'. Either the parameter is optional, it is recommended to support it in DeviceSwap implementations.
-      - POST check: Checks if device swap has been performed during a past period (defined in the request with 'maxAge' attribute) for a given phone number, the API will return boolean response (true/false), indicating that the device has been swapped or not in the specified period. In case the phone number has never been installed in a device, or no data is available in the operators records (e.g. database error), API will return a 422 error.
-
+      - POST check: Checks if device swap has been performed during a past period.
+            - The API returns a boolean response (true/false) based on the mandatory 'maxAge' attribute.
+            - Optionally, the client can provide 'ageTiers' (list of time buckets) to receive a 'tierIndex', enabling granular risk assessment without exposing exact timestamps.
+            - In case the phone number has never been installed in a device, or no data is available in the operators records (e.g. database error), API will return a 422 error.
       # Identifying the phone number from the access token
 
       This API requires the API consumer to identify a phone number as the subject of the API. There is 2 ways to retrieve it depending on the authorization flow used:
@@ -239,6 +241,20 @@ components:
           minimum: 1
           maximum: 2400
           default: 240
+        # --- NEW FIELD START ---
+        ageTiers:
+          type: array
+          description: |
+            OPTIONAL. A list of integers defining time buckets (in hours) for risk assessment.
+            The response will contain 'tierIndex' indicating which bucket the actual swap age falls into.
+            If omitted, the API behaves as a standard boolean check.
+          items:
+            type: integer
+            format: int32
+            minimum: 1
+            maximum: 2400
+          example: [1, 4, 24, 72, 240]
+        # --- NEW FIELD END ---
     PhoneNumber:
       type: string
       pattern: '^\+[1-9][0-9]{4,14}$'
@@ -252,6 +268,21 @@ components:
         swapped:
           type: boolean
           description: Indicates whether the device has been swapped during the period within the provided age.
+        # --- NEW FIELD START ---
+        tierIndex:
+          type: integer
+          format: int32
+          description: |
+            OPTIONAL. The 0-based index of the bucket in 'ageTiers' where the actual swap age falls.
+
+            Logic:
+            1. Iterate through 'ageTiers'.
+            2. Find the first tier where actual_age <= tier_value.
+            3. Return that index.
+
+            Returns null (or omitted) if the swap age exceeds all defined tiers or if 'ageTiers' was not provided.
+          example: 1
+        # --- NEW FIELD END ---          
     ErrorInfo:
       type: object
       required: