From 215da0511cd3663c8cfa90eb793ebfbc63c907b8 Mon Sep 17 00:00:00 2001 From: Shilpa Padgaonkar <77152136+shilpa-padgaonkar@users.noreply.github.com> Date: Wed, 18 Mar 2026 21:57:32 -0700 Subject: [PATCH 1/2] Update sim-swap.yaml with age band --- code/API_definitions/sim-swap.yaml | 69 ++++++++++++++++++++++++++---- 1 file changed, 61 insertions(+), 8 deletions(-) diff --git a/code/API_definitions/sim-swap.yaml b/code/API_definitions/sim-swap.yaml index 3f053d7..f2cbcee 100644 --- a/code/API_definitions/sim-swap.yaml +++ b/code/API_definitions/sim-swap.yaml @@ -28,12 +28,35 @@ info: The API provides 2 operations: - - POST retrieve-date : Provides timestamp of latest SIM swap, if any, for a given phone number. - - - If no swap has been performed and the network operator supports unlimited SimSwap monitoring timeframe, the API will return the SIM activation date (the timestamp of the first time that the SIM connected to the network). - - - If the latest SIM swap date (or the activation date if no SIM swap) cannot be communicated due to local regulations (or MNO 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 MNO. In this case the response must be treated as "there were no sim swap events during 'monitoredPeriod'. Either the parameter is optional, it is recommended to support it in SimSwap implementations. - + - POST retrieve-date : Provides the following two flavors as responses: + + - Timestamp of latest SIM swap, if any, for a given phone number. + + - If no swap has been performed and the network operator supports unlimited SimSwap monitoring timeframe, the API will return the SIM activation date (the timestamp of the first time that the SIM connected to the network). + + - If the latest SIM swap date (or the activation date if no SIM swap) cannot be communicated due to local regulations (or MNO 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 MNO. In this case the response must be treated as "there were no sim swap events during 'monitoredPeriod'. Either the parameter is optional, it is recommended to support it in SimSwap implementations. + + - SimSwapAgeBandEnum as a standardized recency bucket representing the elapsed time between the SIM activation/change date and the current time. The value maps the duration into fixed bands (0–14), ranging from 0 hours up to 3+ years. + + - Standardized AgeBand enum mapping:
+ 0 = 0h ≤ d < 4h
+ 1 = 4h ≤ d < 12h
+ 2 = 12h ≤ d < 1d
+ 3 = 1d ≤ d < 2d
+ 4 = 2d ≤ d < 5d
+ 5 = 5d ≤ d < 7d
+ 6 = 7d ≤ d < 14d
+ 7 = 14d ≤ d < 30d
+ 8 = 30d ≤ d < 60d
+ 9 = 60d ≤ d < 90d
+ 10 = 90d ≤ d < 180d
+ 11 = 180d ≤ d < 1y
+ 12 = 1y ≤ d < 2y
+ 13 = 2y ≤ d < 3y
+ 14 = 3y+
+ 111 = Change has not happened
+ 999 = Subscriber valid, but no real-time profile found
+ - POST check: Checks if SIM swap has been performed during a past period (defined in the request with 'maxAge' attribute) for a given phone number. - Note: In the specification of the API the 'maxAge' could be between 1 hour to 2400 hours. If this delay is not managed due to the operator's own privacy threshold (which in theory would likely be linked to local regulations in the country) and a request is performed with a value inferior to 2400 but superior to operator policy, then, an error `400 OUT_OF_RANGE `is expected with an explicit message to explain the limitation like `Check monitor period could not exceed local regulations (30 days)`. @@ -134,6 +157,8 @@ paths: $ref: "#/components/examples/RETRIEVE_MONITORED_PERIOD" RETRIEVE_MONITORED_NULL: $ref: "#/components/examples/RETRIEVE_MONITORED_NULL" + RETRIEVE_AGEBAND: + $ref: "#/components/examples/RETRIEVE_AGEBAND" "400": $ref: "#/components/responses/Generic400" "401": @@ -219,8 +244,9 @@ components: example: "b4333c46-49c0-4f62-80d7-f0ef930f1c46" SimSwapInfo: type: object - required: - - latestSimChange + oneOf: + - required: [latestSimChange] + - required: [simSwapAgeBand] properties: latestSimChange: type: string @@ -232,6 +258,29 @@ components: type: integer description: Timeframe in days for SIM card change supervision for the phone number. It could be valued in the response if the latest SIM swap occurred before this monitored period. example: 120 + simSwapAgeBand: + type: integer + description: Standardized recency bucket representing the elapsed time between the SIM activation/change date and the current time. + enum: + - 0 + - 1 + - 2 + - 3 + - 4 + - 5 + - 6 + - 7 + - 8 + - 9 + - 10 + - 11 + - 12 + - 13 + - 14 + - 111 + - 999 + nullable: true + example: 1 CheckSimSwapInfo: type: object required: @@ -475,6 +524,10 @@ components: value: latestSimChange: null monitoredPeriod: 120 + RETRIEVE_AGEBAND: + summary: SimSwap age band is sent back + value: + simSwapAgeBand: 1 CHECK_2LEGS: summary: Check request without 3-legged access tokens value: From 5b11589501f10348098a521184039c96f687317e Mon Sep 17 00:00:00 2001 From: Maximilian Laue <112983658+maxl2287@users.noreply.github.com> Date: Thu, 19 Mar 2026 08:51:45 +0100 Subject: [PATCH 2/2] fix: remove trailing whitespaces --- code/API_definitions/sim-swap.yaml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/code/API_definitions/sim-swap.yaml b/code/API_definitions/sim-swap.yaml index f2cbcee..e332858 100644 --- a/code/API_definitions/sim-swap.yaml +++ b/code/API_definitions/sim-swap.yaml @@ -29,13 +29,13 @@ info: The API provides 2 operations: - POST retrieve-date : Provides the following two flavors as responses: - + - Timestamp of latest SIM swap, if any, for a given phone number. - If no swap has been performed and the network operator supports unlimited SimSwap monitoring timeframe, the API will return the SIM activation date (the timestamp of the first time that the SIM connected to the network). - If the latest SIM swap date (or the activation date if no SIM swap) cannot be communicated due to local regulations (or MNO 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 MNO. In this case the response must be treated as "there were no sim swap events during 'monitoredPeriod'. Either the parameter is optional, it is recommended to support it in SimSwap implementations. - + - SimSwapAgeBandEnum as a standardized recency bucket representing the elapsed time between the SIM activation/change date and the current time. The value maps the duration into fixed bands (0–14), ranging from 0 hours up to 3+ years. - Standardized AgeBand enum mapping:
@@ -56,7 +56,7 @@ info: 14 = 3y+
111 = Change has not happened
999 = Subscriber valid, but no real-time profile found
- + - POST check: Checks if SIM swap has been performed during a past period (defined in the request with 'maxAge' attribute) for a given phone number. - Note: In the specification of the API the 'maxAge' could be between 1 hour to 2400 hours. If this delay is not managed due to the operator's own privacy threshold (which in theory would likely be linked to local regulations in the country) and a request is performed with a value inferior to 2400 but superior to operator policy, then, an error `400 OUT_OF_RANGE `is expected with an explicit message to explain the limitation like `Check monitor period could not exceed local regulations (30 days)`. @@ -280,7 +280,7 @@ components: - 111 - 999 nullable: true - example: 1 + example: 1 CheckSimSwapInfo: type: object required: