Return value for swap_date when unavailable or unknown

[jlurien]

In our implementation we have found scenarios where there is no known date for the latest SIM swapped, typically because never was a proper swap, or for other reasons. We should define the expected behaviour in this scenario.

Current endpoint /retrieve-date considers the property latest_sim_change as optional. In the above scenario, should we return an empty object {} or some error, for example 404 with certain code SIM_SWAP.NO_CHANGE.

@bigludo7 How do you manage this scenario in your implementation? any preference?
@DT-DawidWroblewski In the MobileConnect approach, how is this handled?

[bigludo7]

Hello @jlurien
sorry for the delay.
We did not yet this problem as for now we only implement the check resource.
My first thinking for your UC is to send back a 404 but probably not with a SIM_SWAP.NO_CHANGE code but a SIM_SWAP.UNABLE_TO_PROVIDE_DATE.

We have also a requirement from our implem.
What we're supposed to answer when the msisdn is not managed by the service provider ?
I would like to add also a 404 SIM_SWAP.MSISDN_NOT_MANAGED

As of today we use 500 but this is not explicit for the requester.

Waiting for @DT-DawidWroblewski perspective. I'm ready to make a PR to accommodate this.

Thanks

[jlurien]

I think that for this other use case, MSISDN not managed, 404 is reasonable with a code like that.

[DT-DawidWroblewski]

Hi!

sorry for the late response...

it really depends on the market we're serving MC ATP:

1. in DE we're having a limitation of 30 days, meaning if simSwap took place later than 30 days from a request, we return an empty string. Additionally, we're checking the "activation date" of the sim card - if the sim was activated 30 days prior request - we return the date of this event. This is quite useful when the customer has more than one sim under one MSISDN (multi sim scenario)
2. in other countries we do have 30 days limitation (at least for now), so we're sharing the last sim swap date if it occurred, or an empty string if not.

From API service perspective, we should not throw an error - we're doing the check on MNO end.

[gregory1g]

If "retrieve-date" API is limited to a gracing period of so it must be clearly mentioned in the API description. As of now, one could reasonably expect to get recent SIM swap, does not matter if this happened in last 30 days or or earlier, Moreover, web application which calls this API could act international and could be not aware about country specific regulations - what makes "retrieve-date" interpretation more complicated.

Related question - it could be great to clearly specify if signing a new contract is considered as SIM swap or not (or even to introduce a special respond in this case). Rather often new contract gets an MSISDN which earlier was used by another person. This means that MSISDN-SIM association is changed.

[DT-DawidWroblewski]

Hi @gregory1g !

If "retrieve-date" API is limited to a gracing period of so it must be clearly mentioned in the API description.

Another option here is that we make a general description of an API definition and throw a statement to developers there are local break outs that impacts API response - like the one with 30 days grace period.

Moreover, web application which calls this API could act international and could be not aware about country specific regulations - what makes "retrieve-date" interpretation more complicated.

Some of clarification comes when Developer/Service Provider approach MNO and agrees to T&Cs with Use Case declaration - this is how we're working with Mobile Connect SP on boarding and it works :)

it could be great to clearly specify if signing a new contract is considered as SIM swap or not

this is not a simSwap, but sim activation date and initial MSISDN-IMSI pairing. In MC we define sim_change as Timestamp of last MSISDN <-> IMSI pairing change . please see reference docs - Table 3@section 4.2

activation date may be considered as a relevant data for simSwap for scenarios like:

1. first contract between customer and MNO
2. multisim scenario

Rather often new contract gets an MSISDN which earlier was used by another person.

there is a MC API for this one called Number recycle - here's reference product description of Vodafone & Telefonica

[gregory1g]

Another option here is that we make a general description of an API definition and throw a statement to developers there are local break outs that impacts API response - like the one with 30 days grace period.

Yes. This is an option as well.

Moreover, web application which calls this API could act international and could be not aware about country specific regulations - what makes "retrieve-date" interpretation more complicated.

Some of clarification comes when Developer/Service Provider approach MNO and agrees to T&Cs with Use Case declaration - this is how we're working with Mobile Connect SP on boarding and it works :)
Right. But then API description should say something like "retrieve data returns last simswap which happened during limited time frame (which is a subject of legal regulation)".
Actually, this is my point: to make API definition clear it makes sense to describe how it should act for such cases.

it could be great to clearly specify if signing a new contract is considered as SIM swap or not

this is not a simSwap, but sim activation date and initial MSISDN-IMSI pairing. In MC we define sim_change as Timestamp of last MSISDN <-> IMSI pairing change . please see reference docs - Table 3@section 4.2

activation date may be considered as a relevant data for simSwap for scenarios like:

1. first contract between customer and MNO
2. multisim scenario
   MultiSIM scenario: is adding a new SIM is considered as "SIM swap"?

Rather often new contract gets an MSISDN which earlier was used by another person.

there is a MC API for this one called Number recycle - here's reference product description of Vodafone & Telefonica

"Number recycle" addresses the very exact use case. For a developer which calls SIMSwap it plays no role why MSISDN-IMSI link is changed because of new SIM card is required or because of MSISDN is released and assigned to another contract. SimSwap could be more developer friendly.
Or am I wrong here?

[DT-DawidWroblewski]

"Number recycle" addresses the very exact use case. For a developer which calls SIMSwap it plays no role why MSISDN-IMSI link is changed because of new SIM card is required or because of MSISDN is released and assigned to another contract. SimSwap could be more developer friendly.
Or am I wrong here?

simSwap use cases are the following, but not limited to:

1. Prevention of various types of fraud in banking such as SIM swap fraud
2. Making SMS one-time passwords more secure
3. Secure authentication (authenticate + ATP)
4. Securing add new payee transactions in banking

Please see GSMA Mobile Connect Account Takeover Protection for more details IDY.24

Number recycle serves a different use case: SP wants to check if MSISDN is active and assigned to an MNO subscription. In MC/Anti-fraud APIs discussions we got insights from the US market where people change mobile phone numbers frequently and institutions, like banks or insurance companies, have issues with reaching proper people... while knowing only MSISDN as contact data.

I think that serving timestamp or boolean as a response is pretty simple and developer friendly :) still, MNOs have to clearly describe local service breakouts, coming from regulations.

[monamok]

In order to recap, @DT-DawidWroblewski @bigludo7 what is the conclusion here about the original issue?
As a part of documentation I think we must also clarify this scenario.

[trehman-gsma]

In order to recap, @DT-DawidWroblewski @bigludo7 what is the conclusion here about the original issue? As a part of documentation I think we must also clarify this scenario.

Hi all. Was there a conclusion to this?
@monamok - did you manage to get an answer?

The current API spec states "POST retrieve-date : Provides timestamp of latest SIM swap, if any, for a given phone number". I'm interested in knowing what is provided when a SIM swap date is unavailable.

[bigludo7]

@trehman-gsma Up to my knowledge we did not come to a conclusion on this topic.

[gregory1g]

@bigludo7 , right. I have searched the topic, but it looks like there is no commonly agrred approach. We can return empty value, empty string or magic date (some people do this). For magic date I would suggest to avoid future dates (like 9999...) because it contradicts the API logic. Probably we can return "1-Jan-1970" - in this case, a client most probably does not even need to implement a special handling - it does not matter if SimSwap really happened 50 years ago or did not happened at all.

[gregory1g]

According to https://www.json.org/json-en.html, a value can be either one of the simple types (string, number etc) or null.
null looks the best way to represent no value.

Like:
{
"latestSimChange": null
}

[DT-DawidWroblewski]

@gregory1g - thx for a feedback!

However, there is a difference when it comes to handling null vs a string with zero characters.

Here's a feedback I got from chatGPT ;)

Handling null values and empty strings (strings with zero characters) in software development can vary depending on the context and programming language you're working with. There's no definitive answer as to which is easier to handle, as it largely depends on your specific use case and requirements.
Here are some considerations:
1. Null Values:
   - Null values often represent the absence of a value or the lack of initialization.
   - Handling null values typically involves null checks to prevent null reference exceptions.
   - You need to account for potential null values when writing code, which can be error-prone if not done carefully.
   - Some programming languages like Java use null to indicate the absence of an object.
2. Empty Strings:
   - Empty strings are valid string objects with zero characters.
   - They are typically easier to work with as they don't lead to null reference exceptions.
   - You can perform string operations on empty strings without special checks.
   - Some languages consider empty strings as distinct from null values.
To decide which is easier to handle, you should consider your project's coding standards, the language you're using, and the specific use cases. In some cases, you might even need to handle both, as null values and empty strings can have different meanings.
Here are some references for further reading:
1. Java Handling Null Values:
   - [Oracle's Java Tutorial on Null References](https://docs.oracle.com/javase/tutorial/java/data/compare-object.html)
2. Python Handling None (Equivalent to null):
   - [Python None Documentation](https://docs.python.org/3/library/constants.html#None)
3. C# Handling Null Values:
   - [Microsoft Docs on Nullable Types](https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/nullable-types/)
4. JavaScript Handling Null and Empty Strings:
   - [MDN Web Docs on null](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null)
   - [MDN Web Docs on empty strings](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Grammar_and_types#String_quotes)
Remember that best practices may change over time, so it's essential to check the documentation and guidelines for your specific programming language and project requirements.

Following chatGPT suggestion, let's describe the context:

An app developer wants to retrieve the simSwap date to prevent fraud. Developer expects to receive a value (String) in the latestSimChange key, as described in our API:

latestSimChange: 
          type: string
          format: date-time
          description: Timestamp of latest SIM swap performed

yaml line

Therefore, an empty string with 0 characters is something in line with the existing scheme. Handling null may be challenging.

What do you think?

[fernandopradocabrillo]

Hi all,

Why is the property latestSimChange optional if we are considering to return it even if there is no date?

I think to solve this we have to think first what do we consider as a sim swap? If we are dealing with anti-fraud scenarios a swap should be every time the phone number has been assigned to a new sim so, from TEF we believe that this includes the first time the phone number is activated in the sim. This way there will always be a return date on the operation and there is no need to send empty strings or nulls.

[gregory1g]

It was discussed that there is a time frame covered by the API. So, if SimSwap did not happen in this time frame API should return "nothing", If I recall the discussion correctly, such a timefame could be even enforced legally. Returning 10 years old SimSwap goes beyond "anti fraud" API purpose.

It looks like there is a need to have a possibility to return .

[fernandopradocabrillo]

Yes, I agree with the time-frame for the checkSimSwap operation, if there hasn't been a swap in a certain period of time it returns swapped == false. Perfect with this.

But does this time-frame apply to the lastSimChange? I think it is more useful to indicate that the last swap was 5 years ago than to return an empty string that might lead one to think that there has never been one.
It is as if this operation loses its functionality after some time.

[gregory1g]

Exposing SimSwap which happened 10 years ago goes behind API purpose - this is already data collection (customer loyalty, careful handling of things etc), not a fraud protection.
And as somebody mentioned at the last meeting, such behavior could be prohibited by regulators.

Additionally, this would enforce operators to keep information about simswaps during the whole contract life time for all contracts.

"Null" means there was no SimSwap in the monitored period of time.

[bigludo7]

@fernandopradocabrillo @gregory1g @DT-DawidWroblewski

"Null" means there was no SimSwap in the monitored period of time.

OK - But do we consider in this case that we provided a full valid answer ? and there will be a fee like if I answer Sept25th,2023 at 12h36?
I'm bit perplex to bill full price for a null :)

In order to be explicit should we call the attribute notBeforeDate ? the value will be either the latest real sim swap or as far as we are able to provide.

[gregory1g]

Returning a monitoring period in the runtime could be a handy option especially since application will most probably work with different MNO.
Probably something like "monitoredPeriod"?
Like:
{
latestSimChange ="2023.10.30"
}
or
{
latestSimChange = null
monitoredPeriod = 90 # days
}

[bigludo7]

@gregory1g Yes works for me as well as we provide an explicit answer.

[trehman-gsma]

Hi all,

Why is the property latestSimChange optional if we are considering to return it even if there is no date?

I think to solve this we have to think first what do we consider as a sim swap? If we are dealing with anti-fraud scenarios a swap should be every time the phone number has been assigned to a new sim so, from TEF we believe that this includes the first time the phone number is activated in the sim. This way there will always be a return date on the operation and there is no need to send empty strings or nulls.

Is there an agreed view on whether activation date is considered a sim swap? Sorry, trying to follow the conversation in this chain, I don't think it's been agreed yet?

[gregory1g]

Just to put it down before we forget. One can expect that there is a time frame which is covered by API. This time can be limited by two factors:

1. formal regulations like GDPR
2. purpose of the API - this is a anti-fraud, not big data collection, API, therefore it should not information not relevant for this purpose.

So, we can generalize the question to: what to return if no SimSwap happened (according to SimSwap definition) in the supported time frame (independent from what drives this time frame).

[HuubAppelboom]

In the netherlands we provide the last Date/Time stamp.

If you ask me, the discussion about limiting the period for which you provide the SIM Swap Date/Time stamp is a bit pointless.

First of all if you regularly use SMS 2FA to login with the application and the application checks the SIM Swap date each time, you can still track the sim swap history, simply by recording and storing the SIM swap result with each and every login. Even if you don't get the Sim Swap Date anymore after 30 days, you can still reconstruct it by looking at the historical data points you collected. In practice, the banks that use this kind of data do store these data points with time, mainly for evidence (in case there is fraud) or for training their risk engines. So, the data minimisation you think to get is limited.

Another issue is that people will be using more and more eSIM in the coming years. In our case, moving from device to device means a new eSIM. So you will start seeing much more recent SIM swap dates in the near future.

Thirdly, the last SIM Swap Activation Date can also be used in other fraud cases, as a proxy for how long a mobile number has been allocated to a user. This can work particularly also for identity fraud cases where fraudster often cycle through mobile numbers. Ofcourse you can also make a separate API for this (MSISDN association), but as long as this is not available, SIM Swap will work as well.

If you ask me, if there is a restriction on the time frame supported due to regulatory reasons, please do mention this time frame in the result, and mention when there was no SIM swap.

[trehman-gsma]

We discussed this issue on 14/12/23 during the bi-weekly call (summary at the end of this comment). The discussion was in context of v0.4.0 as multiple operators are currently implementing this version for a production release.

This is the schema for latestSimChange in v0.4.0:

  schemas:
    SimSwapInfo:
      type: object
      properties:
        latestSimChange: 
          type: string
          format: date-time
          description: Timestamp of latest SIM swap performed

From a technical conformance perspective, it was agreed that one of these 3 options would technically adhere to the specification:

# 1 - a null returned
{
  "latestSimChange": null
}

# 2 - an empty body returned because latestSimChange is an optional attribute
{

}

# 3 - a string in date-time format
{
  "latestSimChange": "string in date-time format"
}

From a business/product perspective, there is not yet a global alignment. There is at least 1 region with a regional alignment whereby the activation date is returned if it is less than N months old otherwise a null will be returned.

It was suggested that regions could align because there may be governing regulations influencing the allowable content in the date-time option (e.g. in some regions, activation dates may only be returned if they are less than N years).

It was also suggested that - for cases where date-time is not returned then the null option could be advised instead of the empty body option.

In summary:

• From a technical conformance perspective, there is agreement. There are 3 options that can be returned as per the specification (date-time, null, empty body).
• From a business perspective, there is no global alignment. There is at least 1 regional alignment and it was suggested that regions should align.
• The null return option was preferred over the empty body return option in the discussion today.

Open discussion points:

• Global alignment vs Regional alignment - how to action this
• Advising null over empty body - how to formalise this

Hope I have captured all relevant points @DT-DawidWroblewski @bigludo7 @gregory1g