Optional ageTiers parameter for privacy-preserving granularity

[yyeAduna]

Problem description
Current consumers of the API (e.g., banks) often need more granular signals to assess account-takeover risk alongside their own data. A simple boolean result (True/False) doesn’t provide enough detail, while returning the underlying event date/time isn’t feasible due to strict privacy requirements (e.g., GDPR) and operator restrictions. As a result, clients must make multiple calls with different maxAge values (for example, 1 hour, then 24 hours) to infer the risk level—creating unnecessary network and API load and poor overall performance.

Possible evolution
Introduce an optional input parameter ageTiers (list of integers) that enables a "Tiered Response" mode, where the highest tier is the maxAge.

Backward Compatible: If ageTiers is omitted, the API behaves exactly as it does today (using maxAge).

Privacy Friendly: Returns a tier index rather than an exact timestamp.

Efficient: Reduces N API calls to 1 call.

Alternative solution
make multiple calls with different maxAge values

Additional context
Samples1: Swapped at 3 hour ago

input:
{
"phoneNumber": "+1234567890",
"maxAge": 240,
"ageTiers": [1,4,24,72,240]
}

output:
{
"swapped": true, // Calculated using maxAge (3 < 240)
"tierIndex": 1 // 3 hours is > 1 but <= 4. It falls in the second bucket (Index 1).
}

Samples1: Swapped at more than 240 hour ago
output:
{
"swapped": false,
"tierIndex": -1 // out of the maxAge
}

[bigludo7]

Hello @yyeAduna
Thanks for the proposal. I tend to not get the value of the evolution regarding the added complexity.
IMHO our consumer want to know if there is a sim swap for the last x hours. this x is from their fraud policy rules and not sure why they will ask for an array.
Happy to hear from other companies.

[yyeAduna]

There are three reasons that the Age Tiers are useful for the SIM SWAP:

1. Banks' Risk Scoring is Probabilistic, Not Binary. Financial institution risk assessments are rarely binary "Yes/No" decisions. Instead, they are probability calculations designed to optimize the trade-off between Detection Rate (DR) and False Positive Rate (FPR). The acceptable "recent-ness" of a SIM swap (the MaxAge) fluctuates dynamically based on the transaction context. A routine login, OR a $200 P2P transfer, OR a $20,000 wire to a new beneficiary each requires a different risk tolerance. A rigid, single-threshold API forces banks to over-simplify this complex reality.

2. Prevention of Banks Information Leakage (Side-Channel Risk): If a bank is forced to send a different MaxAge parameter (e.g., "has swap occurred in the last 1 hour?") for different transactions, they inadvertently leak sensitive context to the MNO.
   By analyzing the strictness of the MaxAge request, an external party could infer the nature of the customer's transaction (e.g., a strict MaxAge implies a high-value/high-risk transaction) and reverse-engineer the bank's internal risk policies. It is something banks will try their best to stay way.

"Age Tiers" allow banks to request a standardized set of data without revealing the specific transaction trigger, preserving client privacy and corporate security. It perfectively solves the challenges from #1 and #2 at the same time.

3. Feature Engineering for Machine Learning Models Modern Banking fraud engines do not use SIM Swap data as a sequential "gate" (i.e., Check Swap -> If Safe -> Proceed). Instead, they ingest the SIM status as one of hundreds of weighted features into a Machine Learning ensemble (e.g., Random Forest) to generate a final risk score.

Reducing this signal to a boolean "True/False" is a form of lossy compression. It strips away valuable nuance.

Providing "Age Tiers" preserves data granularity, allowing the ML model to learn subtle correlations that a boolean flag would completely miss. Thus it increases the potential use case(s) and market this service can address.

[yyeAduna]

reopen for further discussion

[albertoramosmonagas]

Hi @yyeAduna,

From Telefónica’s side, I’d like to flag some concerns before ageTiers / tierIndex becomes a “standard” pattern (we’re seeing the same discussion in related Device swap API too).

The API should expose a portable telco signal (“swap within X”), not encode the consumer’s fraud policy / feature engineering into the contract. If tiers are client-defined, tierIndex has no stable meaning across consumers/operators/markets — it becomes semantics-by-convention, not a standard signal and if varying maxAge is the issue, a bank can use a fixed maxAge and do all decisioning/mapping internally. Moving tiering into the telco API shifts complexity without clearly solving the core problem. Also, even if technically backward compatible, this is a material functional change (new semantics, edge cases, support/testing burden) and pushes the L1 API toward scoring-like behavior.

Thanks.

[bigludo7]

Thanks @yyeAduna for reopening the issue.
I copied here my response from the PR:

To be honest this is a breaking change (not from technical perspective but functional/business) and from my company we're not sure about the breaking change vs evolution value.
I understand the business requirement but in this case I will see this as a L3 api (composite API) offered by channel partner and consuming atomic L1 MNO API.

Thanks.

[yyeAduna]

Thank you for the feedback — I agree an L1 API should remain a portable telco signal (“swap within X”) and should not embed a consumer’s fraud policy or scoring logic.

What I’m proposing is not scoring; it’s an optional batching mode to reduce chatty “N calls for N maxAge checks” into one HTTP round-trip, while still only returning privacy-safe outputs (no timestamps).

1. Reframe: Batching multiple L1 checks, not a new signal type The client provides the list of ageTiers (vectorized request) explicitly in the request. The API simply evaluates the same L1 predicate (“swap within X”) for those X values.

This is deterministic and stateless; there is no “semantics-by-convention” beyond what the requester includes in the payload.

2. Reduce policy/transaction-context leakage In practice, banks vary maxAge by context (login vs transfer vs new payee). Even if operators are trusted parties, minimizing exposure of business-rule thresholds in line with privacy-by-design principles.

Using a consistent “batched request shape” (e.g., always [1, 24, 168]) avoids revealing which single threshold was relevant for a given user action thus protecting their privacy.

3. Efficiency and consistent latency Today, to obtain more than a binary answer, clients often perform sequential calls (1h, then 24h, etc.) (e.g. to use for their ML engine). A batched mode reduces that to one call, improving latency, load, and reliability without exposing raw timestamps.

Conclusion If we treat ageTiers as an optional performance + privacy optimization (batching multiple standard L1 queries), rather than a standardized scoring pattern, does that address the concern about L3 creep?

[HuubAppelboom]

The privacy issue with an exact timestamp is that it can be abused to identify someone over and over again. At the exact time stamp (down to the very second), it is likely that this can be abused for that. That is the reason why the maxAge version of the SIM Swap API exsists, and also if you look at the fraud risk, you really don't need a very high precision.

When you leave the definition of the tiers up to the customer, they may still abuse it (by for example choosing tiers very close to each other).

So, in any case, if a tier option is introduced, I think it should at least have a minimum granularity defined, for example 1 hour

In general, what may be a more simple solution is to work with a logarithmic value in stead oftiers. In general, the longer the SIM Swap is ago, the less concerned you are about the accuracy.

For example, you could agree to return log (sim_swap_age), where sim_swap_age is rounded to multiples of 1 hour, and the returned value is always rounded with one decimal.
So for example
log (sim_swap_age) = 0.3
log (sim_swap_age) = 1.5
log (sim_swap_age) = 3.4

The longer the SIM Swap is ago, the less accurate the value becomes, which is better from a privacy perspective; at the same time, you still keep accuracy when it is a more recent Sim Swap.
You can also combine this with for example a rule that you never report values higher than 10000 hours ago (approx 1 year), so the log value you return is always between 0 and 4

And yes, a tier table with about 40 values in it would probably do the same trick.

[HuubAppelboom]

Another solution may be to make an offering where the customer pays per monthly active user, and let the customer do multiple calls with the same phone number (if the discussion is more a pricing issue). Then the customer can decide depending on the particular case what maxAge to use.

[yyeAduna]

Thanks for the feedback.

1. Privacy and abuse (granularity)

Yes, agree with the idea. We can put in some restrictions:
Guardrails: ageTiers MUST use the same unit as maxAge (integer hours only; floats rejected).
Enforcement: apply server-side hour quantization and enforce maxBuckets (e.g., 5–10) plus minSpacingHours (e.g., ≥ 2 hour between adjacent entries) to prevent probing.

2. Logarithmic scales

The log(age) idea is interesting and could be a good operator-defined profile.
With vectorized input, clients can approximate log/linear shapes as needed; to address portability, we could standardize a small set of predefined profiles / recommended vectors (e.g., [1, 10, 100, 1000] or [1,4,16, 32, ... ]) while keeping custom vectors optional.

3. Pricing vs performance
   MAU pricing can reduce cost friction, but it doesn’t remove the technical overhead:
   Latency: multiple round-trips (especially when sequential) will be slower than one batched request.
   Load: flat-rate models can unintentionally encourage extra gateway traffic; batching reduces total request volume.

[HuubAppelboom]

@yyeAduna @bigludo7 @albertoramosmonagas A more simple approach in stead of list of tiers (and an endless discussion on what the triers should be) is to have the discussion with the privacy officers in the markets concerned, and see whether the current retrieve_date version can be implemented in such a way that it addresses their privacy concerns.

For example, what you could do:

• when the SIM Swap date is less than 72 hours ago, provide the SIM Swap time stamp, but rounded down to exactly n hours ago, where n is an integer. So you will see time stamps that are exactly, 1,2 3,4...72 hours ago among the answers.
• when the SIM Swap date is more than 72 hours ago, and less than 365 days ago, provide the SIM Swap time stamp, but rounded down to a timestamp exactly m days ago, where m is an integer.
• when the SIM Swap date is more than 365 days ago, provide the SIM Swap time stamp that is exactly 365 days ago.

This way you don't need to have yet another specification that breaks backward compatibility, it provides the same (or a similar) level of granularity as a tiered model, and hopefully everybody can start using the same API.