Repository navigation
Proposed Enhancement: Include a multi-SIM dependent flag in responses #242
Description
Problem description
The current API description does not specify the API behaviour for multi-SIM scenarios (i.e. scenarios where multiple SIMs share the same primary MSISDN).
For the specified use cases for this API, it is reasonable for an API provider to always return or verify the primary MSISDN, irrespective of which device / SIM is being verified, as that is the MSISDN that will be known to the end user and hence shared with the API consumer.
Hence it can be expected that implementations exist that will always return or verify the primary MSISDN.
However, for some API consumers, particularly where the API is being used for security / fraud prevention, it may be important for them to know whether the device / SIM interacting with their application is the primary device (containing the primary SIM) or a secondary device (containing a secondary SIM).
Currently, they do not know if the device contains the primary or secondary SIM.
Possible evolution
An optional flag can be added to the response to indicate whether the device whose MSISDN is being retrieved or verified is the primary device or a secondary device.
For example:
{
"devicePhoneNumber": "+123456789",
"primaryDevice": true
}
Some possible definitions of primaryDevice that can be given to the API consumer could be:
- The device that the mobile subscription account holder would normally use for personal transactions (phone calls, messaging, direct but relatively short interactions with apps)
- The device that mobile subscription account holder would choose to keep if they could only have one mobile subscription
- The mobile subscription account holder's personal smartphone that only they use
Identification of the primaryDevice will therefore be somewhat subjective, but nonetheless it can be expected that the mobile subscription account holder will normally have one, and only one, "primary device" which can be identified with a reasonably high probability by the network operator.
Making the flag optional means this is not a breaking change for any API provider. If it is preferred to keep the response body consistent between implementations, the flag could be made mandatory, but allowed to take a null value for those API providers who do not want to support the feature.
Alternative solution
Support for the feature could be made a requirement by mandating the additional flag with no option to assign a null value
Additional context
None
Activity
AxelNennker commentedon Aug 14, 2026
I am. very unsure what a primary device is. I think at Telekom Deutschland a subscriber can have 10 multisim. A phone, a watch, two BMW, a dog tracker, ... If the subscriber puts a new SIM with a different number into the phone, then there would be no phone that has the multisim. I don't know what the primaryPhone is then.
I think, what we could add to NV responses is "isMultiSim" true/false.
That isMultiSim flag would also better match the title of this issue.
Do customers / ASPs ask for that?
[-]Proposed Enhancement: Include a multi-SIM flag in responses[/-][+]Proposed Enhancement: Include a multi-SIM dependent flag in responses[/+]eric-murray commentedon Aug 14, 2026
Hi @AxelNennker
That's interesting, and a great reason why such a feature needs to be discussed between the different API providers.
So, for DT, there is no distinction between SIMs in a multi-SIM group? The SIMs could be used in any of the devices with no change in the functionality of these devices, and no perceivable difference to the account holder?
In that case, DT would not support the new flag, as it has no meaning for your multi-SIM implementation.
I think a flag simply to indicate whether or not the SIM is part of a multi-SIM group is not a particularly useful fraud marker. That sounds more like a separate standalone API, rather than an additional response parameter from this API.
I updated the issue title to avoid that it dictates possible solutions.
eric-murray commentedon Aug 17, 2026
I added some possible definitions for "primary device" to help with the discussion and to guide any analysis of the likelihood of correctly identifying such a device.
HuubAppelboom commentedon Aug 18, 2026
@eric-murray @AxelNennker At KPN we also have multi-sim propositions where we can not tell which sim is the primary device, because both sim cards act as the same.
What may be better is in stead of trying to define or detect what a primary device is, to provide information when a device belongs to a category which may require different handling from an anti-fraud perspective. For example, for Apple iWatch (and similar android smart watches) which use the same phone number as a regular phone, this is often well known to the telco and the end user alike.
So for this category, I would suggest to add an optional boolean to indicate it to be companion device, like:
{
"devicePhoneNumber": "+123456789",
"companionDevice": true
}
This also prevents that the telco shares more information than what parties already know.
And if there are more clear categories that can reliably be identified, and which are needed to be shared to detect/prevent fraud, this can be added with additional booleans.
eric-murray commentedon Sep 1, 2026
Hi @HuubAppelboom
This is a reasonable proposal.
Is my understanding correct that you propose only two possibilities:
companionDeviceproperty is present with valuetrue; orcompanionDeviceproperty is not present at allHence
companionDevice: falsewould never be returned, and if thecompanionDeviceproperty was not present, then the API consumer could not infer anything about whether the SIM was a primary or secondary SIM.HuubAppelboom commentedon Sep 1, 2026
@eric-murray In any case, companionDevice : True should only be returned when it is 100% certain that the device is such a companion device. When it is unknown (because you have 2 identical SIM cards, with no differentiation) or the user has only 1 SIM, you can return False.
Regards
Huub
ECORMAC commentedon Sep 7, 2026
Hi All,
Is there a need to indicate "Primary device" / "Companion Device" in the resp?
Prior to invoking the NumberVerification API, the API invoker shall get an Access token. This is done, for example, with CIBA, invoking the bc-authorize with a login_hint followed by a token. The login_hint includes the device IP address, or a TS.43 token that the device has obtained, so using these two formats, there is no doubt of which device the numberVerify applies. The third format of the login_hint is an MSISDN, which in this case does not work, due to the multi-SIM aspect (and may cause false verifications if the API invoker sets the “primary device” flag but the user is using a secondary device).
So the login-hint should be enough to allow the network to identify the device (primary/secondary etc)?
Thanks,
Cormac
HuubAppelboom commentedon Sep 7, 2026
@ECORMAC Hi Cormac, with Number Verify, most implementations that I know follow currently the authorization code flow, where the MNO retrieves the phone number in the first step, and later compares this with the phone number submitted by the API consumer at the verify step. In this scenario the login_hint is not used.
For the newer TS.43 flow either the CIBA flow is used or (much better) the JWT Bearer Flow.
HuubAppelboom commentedon Sep 7, 2026
@ECORMAC The issue the companion device solves is that the Operator Token (or the Authorization Code) could be generated on the companion device. For some customers this is allowed, others may see this as a security risk, and they only want to accept the Number Verification done on the primary device
The other thing you need to know is that with many implementations the companion device does have its own msisidn associated with it, but this phone number is never shared with the customer. With the share version of Number Verification, this would mean that you would typically share the msisdn associated with the primay device (so that companion device msisdn is never shared). But this makes it very relevant for API Consumer to know that it is a companion device.
By sharing the companion information, we can offering a working solution for companion devices (for customers who would like to have the primary msisdn verified/shared), and at the same time provide a solution for customers that would like to accept Number Verification only from the primary device.
eric-murray commentedon Sep 16, 2026
OK, so there are three possibilities:
companionDeviceproperty is present with valuetruewhen the API provider is sure that the identified device is NOT a device that the end user would be using to interact with a "regular" application; orcompanionDeviceproperty is present with valuefalsewhen the API provider believes that the device is one that the end user MAY be using to interact with a "regular" application; orcompanionDeviceproperty is not present at all if, and only if, the API provider does not support this functionalityWe can, of course, discuss the definition of a "regular application", as I'm sure someone can come up with a use case where they are using their smart watch for online banking. My preference is to agree a definition of
companionDevicebased on use case, rather than form factor.HuubAppelboom commentedon Sep 16, 2026
@eric-murray This sounds a bit too complex to me, why would it be necessary to bring the application into this ?? After all, the API Consumer knows the application best, why would the API Provider need to detect whether it is a "regular"application.
The issue I see is that the API Consumer wants to know whether the phone number he receives does indeed belong to the SIM as a primary device, or that the phone number is coming from a companion device, which has the phone number of another primary device attached to it. I assume the API Consumer attaches a different risk factor to this class of companion device, under the assumption that they may be easier to be taken over/abused by fraudsters.
In the TS43 specs they are also mentionning that there are actually three forms of companion devices:
SharedNumber - Indicates that the “Shared Number” service is active on the companion device (where the device carries the same MSISDN as the primary one)
DiffNumber - Indicates that the “Diff Number” service is active on the companion device (where the device carries a different MSISDN from the primary one but is assigned to the same subscriber.)
FamilyNumber - Indicates that the configuration is for the “Family Number” service (where the device carries a different MSISDN from the primary one and the MSISDN can be assigned to another individual or subscriber.)
What may be better is to simply share that it is a companionDevice True/False, and the type of the phone number as defined in TS.43
The API Consumer can then always decide what they want to do with the it.
HuubAppelboom commentedon Sep 17, 2026
@eric-murray Regarding companion devices, with IOS27 you can also have this situation with 2 iphones, where one iphone acts as a primary device, and the 2nd iphone as a companion device. Especially with the phone number share version with TS.43 token it becomes important what number will be shared, and communicating what type of number it is. It may however be straightforward to implement this for the TS.43 flow, but with the authorization code flow, it may become much more complex. So, we probably also need to have an indicator that for this flow the information is not_available. So perhaps not a boolean treu/false, but a deviceType enumarator could work better (like primaryDevice, companionDevice, unknown). And if the device is companionDevice, also indicate what type of phone number it is (sharedNumber, diffNumber, familyNumber).
eric-murray commentedon Oct 13, 2026
Hi @HuubAppelboom
Finally returning to this in advance of the sub-project meeting this week.
So if the API consumer only has the additional information
"companionDevice": trueor"companionDevice": false, I'm wondering whether a device such as a tablet device (e.g. iPad) should be considered to be a "companion device". A banking app might think it perfectly reasonable for their customer to interact with them using a tablet device, but not a smartwatch. But if the iPad was defined as a companion device, this additional information would not be that useful. To my mind, the difference between the two devices for this API is not the form-factor per se, but the applications that would be expected to be run on the different devices.However, I agree that a definition of "companion device" based on the applications expected to be run would be subjective, and difficult to determine accurately.
The problems with just using the TS.43 definition of companion device is:
In terms of implementation, it is probably a moot point - each mobile operator will implement this enhancement in their own way (or not implement it at all). Some will define the iPad as a companion device, and some will not. Hopefully all will define the smartwatch as a companion device.
The question is, what definition of "companion device" do we give the API consumer?
HuubAppelboom commentedon Oct 14, 2026
@eric-murray What I think we should focus more on in this context is what type of phone number it is, because that will be a clear fraud or identification risk, for example when it is a family phone number shared between more than 1 subscriber. That may be more relevant than defining what a companion device is. On the other hand, if you can make a clear distinction between devices, it may still add value, so maybe we should not block it either in the specification.
For example, what we could do is
deviceHierarchy : primaryDevice, companionDevice, unknown
and
phoneNumberType: singleNumber, sharedNumber, diffNumber, familyNumber
That way you can always map the different use cases, and leave it up to the API Provider how they want to map things
For companionDevice, I would use as definition something like this device is confirmed to belong to the same end user ( and who also has a primary device), and it either has a sharedNumber, diffNumber or familiyNumeber associated with it
The singleNumber is to be used when this number is only in use with one device, also important to know in this context
For cases where we can not tell what the hierarchy is between devices (like what we have with SIM cards which are exact clones), we can use deviceHierarchy unknown