How to Use Super SIM Fleets and Network Access Profiles
The Super SIM API provides you with the ability to specify which mobile networks a device containing a Super SIM is permitted to connect to. This guide will quickly bring you up to speed with how this works so that you will be able to apply your own lists of networks to your groups of SIMs.
Each Super SIM is represented in the Super SIM API by a Sim resource. You organize Sim resources into groups by assigning them to Fleet resources. A Fleet is a collection of Sims with the same behavior. You can have as many Fleets as you need. You might have a Fleet per product, for example, or multiple Fleets per product with each Fleet dedicated to a specific territory and/or sub-SKU. The choice is really up to you and your use-case.
Each Fleet is assigned a Network Access Profile resource. A Network Access Profile (NAP) essentially defines a collection of cellular networks which the Fleet's Sims are permitted to access. Again, you can use as many or as few (you need at least one) NAPs as you need. A given Fleet can use only one NAP at a time, but a single NAP can be shared by multiple Fleets simultaneously:
Each NAP's list of the mobile networks that it provides access to is exclusive: if a particular mobile network is not on the list, it does not belong to that NAP and cannot be accessed by Sims in any Fleet using that NAP. Mobile networks are represented in the API by Network resources.
How does a Super SIM know which networks it can use? From the NAP its Fleet is using. When a device attempts to initiate a cellular connection it will only be able to do so if its modem can detect one of the Networks within the relevant NAP's list of permitted networks. All other networks are considered forbidden, and the modem will not connect to them automatically. Even if the device commands its modem to connect manually, if the target network is a forbidden network, it will not connect — the network will return the error 5004/ROAMING_NOT_ALLOWED.
You can get and set the list of Networks a Sim can connect to at any time. For a given Sim, start by accessing its Fleet's networkAccessProfileSid property to get the SID of the Network Access Profile that the Fleet is currently using. Then use that SID to get the Network Access Profile itself.
A Network Access Profile resource doesn't include the list of networks as a property. Instead it provides the URL from which the list can be retrieved. Access the Network Access Profile's links property; its own networks property has the URL you require. For example:
_11{_11 "unique_name": "NAP Name",_11 "sid": "HAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",_11 "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",_11 "date_created": "2020-05-01T20:00:00Z",_11 "date_updated": "2020-05-01T20:00:00Z",_11 "url": "https://supersim.twilio.com/v1/NetworkAccessProfiles/HAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",_11 "links": {_11 "Networks": "https://supersim.twilio.com/v1/NetworkAccessProfiles/HAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Networks"_11 }_11}
A request sent to this URL will return a paged list of zero or more Network resources representing the networks available to the NAP. The returned JSON contains a meta field which holds the paging information, including the current page number, the number of entries per page and the URL of the next page of data in sequence — this will be null if there are no further pages. The JSON also contains a networks field and this is the array of Network resources. Each of these Network resources contains information about the network represented, including:
-
Its
friendly_nameproperty, which is usually but not always the network's brand name. -
Its
iso_countryproperty, which will be its primary operating territory. -
Its
identifiersproperty, which is an array of objects, each one of which comprises key mobile industry standard network identifiers for that network: its MCC (Mobile Country Code) and MNC (Mobile Network Code), accessed respectively through the object'smccandmncproperties. See MCC and MNC , below, for more information
Please see the Network resource documentation for a full list of resource properties.
MCC and MNC are the standard means by which mobile network operators identify themselves. You can find a full list of MCCs and MNCs here. It's important to understand that because of the many mergers and takeovers that have taken place in the global mobile network industry over the past 30 years, a given network operator may use multiple MNCs for a given MCC. To be sure to include all of a network operator's networks in Network Access Profile, you will to include all of its MNCs in its Network resource.
For example, Vodafone in the UK (MCC 234) has three MNCs: 15, 27 and 91. So its Network resource would look something like this:
_10{ "friendly_name": "Vodafone",_10 "iso_country": "gb",_10 "identifiers": [_10 { "mnc": 15, "mcc": 234 },_10 { "mnc": 27, "mcc": 234 },_10 { "mnc": 91, "mcc": 234 }_10 ]_10}
For the same reasons, you may find that a known MNC is not accompanied by an expected Friendly Name. For instance, T-Mobile USA recently acquired Sprint, which uses the MNC 530. We will continue to show Sprint as the friendly name while Sprint remains a separate entity for commercial purposes.
To allow all of a Fleet's Sims to access a network, or to block them from using one, simply update the list of Network resources within the Network Access Profile being used by the Fleet, or assign the Fleet an alternative NAP which has the required networks in its array of Network resources. However you update the list of available networks, devices currently connected to a newly-forbidden network will remain connected, but will not be allowed to connect to that network when they next attach.
You can change a Fleet's Network Access Profile by updating its networkAccessProfileSid property with the SID of the Network Access Profile you want the Fleet to use.
If you need to change the network list for a subset of the Fleet's Sims, you will need to assign the subset to a new Fleet that has been set to use a suitably configured Network Access Profile, which may also be a new resource or one you are using for other Fleets.
To update a Fleet's Network Access Profile directly, either POST a Network SID to the NAP's Networks sub-resource — see above for guidance on discovering the URL of this sub-resource — to add it, or make a DELETE request to the same URL and pass SID of the Network you wish to remove from the list. Updating the NAP this way will affect every Fleet that is using it.
In addition to the programmatic access to Sim, Fleet, NAP, and Network resources provided by the Super SIM API, they can also be accessed in a more human-friendly way through the Twilio Console. You can create Fleets, create NAPs, and assign the latter to the former. You can change an existing NAP's list of Networks, or switch a Fleet to a different NAP, for example. Sims can be activated and assigned to Fleets.
Console can also be used to delete unwanted and unused Fleets and NAPs. In Console, click on the name of the Fleet or NAP you wish to delete, and then click the Delete link at the bottom of the page. You will be asked to confirm your action before the Fleet or NAP is deleted. Fleets to which SIMs are currently assigned cannot be deleted, nor can NAPs that are currently assigned to a Fleet.
Network Access Profiles provide a powerful and flexible means of managing access to mobile networks. You can change the list of cellular networks to which a given Sim is permitted to use by changing the Fleet it belongs to, by switching its Fleet to a different NAP, or by updating the Fleet's NAP directly. All Fleets must have an NAP. NAPs can be shared by multiple Fleets, or used on a one-to-one basis — the choice is yours, determined by your use case.