Learn how to determine a Super SIM's status, what each of the states are, and how a Sim resource enters them.
Last updated
Every Sim resource will be in one of five possible states, each of which indicates a Super SIM's authority to connect to the cellular network while in that state. Some states are achieved automatically; others can be set by changing the Sim resource's status property. This guide will describe each of the states and show you how a Sim resource enters them. It will also detail some common scenarios in which you may want or need to change a Sim resource's state.
At any given moment, a Sim resource will be in one of the following states:
new
ready
active
inactive
scheduled
The resource's status property will tell you to which of these states it is currently set — and therefore whether the Super SIM represented by the resource is able to allow its host device to access the network. The value of status is a string matching one of the states listed above.
Changing a Sim resource's state doesn't change the Super SIM it represents in any way, but simply governs whether partner networks permit that Super SIM to access network resources.
So what do these states represent exactly?
| State | Meaning |
|---|---|
Fleets are how Sims are organized into groups. All the Sims in a Fleet behave the same way: how their data usage is billed and whether they accept SMS Commands. Rather than apply these settings to each Sim individually, you just update the Fleet, and all the Sims in that Fleet automatically adopt the new configuration.
A yet-to-be-activated, new Sim resource can be told to transition to ready or toactive. When this happens, the resource's status will initially be set to scheduled. The change to the requested state is made asynchronously, and the resource's status property will only show the desired value when the update has actually been applied.
When a Sim's status is ready or active, its Super SIM can be used by a device to connect to the network and transfer data. In fact, it must be set to ready or active in order to be able to connect.
As indicated in the table above, a ready Sim will automatically become active after it has consumed 250KB of data, it has sent or received five SMS Commands, or after three months in the ready state, whichever occurs first.
Once active, the Sim resource can be manually transitioned to inactive only by specifying that as its new state. The resource's status will initially be set to scheduled. The change to the requested state is made asynchronously, and the resource's status property will only show the desired value when the update has actually been applied:
When you update a Sim resource, you can include a callback URL (as the value of the query parameter CallbackUrl). If the Sim resource's update is handled asynchronously, this callback URL will be sent notifications when the target resource's status actually changes (first to scheduled, then to the requested value). The callback URL is used for this requested change only; it is not applied as a global setting. If the Sim resource's update is completed synchronously, no notification will be sent to the callback URL.
The following diagram shows how this asynchronous behavior operates over time:
You can view a Super SIM's status in the Twilio Console: look under the STATUS column for the SIM or SIMs you're interested in.
To access this information programmatically, you can make a request to the Super SIM API using the Twilio SDK for your favorite language. However you make the request, the value of the returned resource's status property will tell you its state.
Using curl:
This call will return the same JSON as shown above.
As you can see, the Sim used in these examples has not yet been activated — its status is new — and it has not yet been assigned to a Fleet: the fleet_sid property is null.
You can change a Sim's status in Console: go to the list of SIMs, filter as required to narrow the list of Sims to the one you want, and click on its name or SID. On the Sim's information page, scroll down to the Properties section, and select the Sim's new status from the Status menu. Click the Save button to apply the change.
To make this change programmatically, make a POST request to the Super SIM API using the Twilio SDK for your favorite language. In the request's URL-encoded query parameters, you include Status — its value is the state to which you want the Sim to transition.
Please see the Sim resource documentation to learn what other fields you can include. As noted earlier, it's a good idea to include the URL of an endpoint on your own server to which state-change notifications will be sent. Here's a fictional URL to show you how it's done:
The only states that a Sim resource can be manually instructed to change to are ready, active, and inactive. Once it is no longer new or ready, a Sim resource can never return to that state (see the first diagram above). The scheduled state is only ever set automatically, and briefly, in response to your own state-change requests.
You will transition a fresh Super SIM from new to ready or active (via scheduled) when you fit it into a device, configure the device's Access Point Name (APN) setting, and connect to the network.
Transition the Sim to ready (rather than active) if you are using the Super SIM it represents for testing and would prefer not to incur monthly fees. Once the Sim has consumed 250KB of data, five SMS Commands have been sent or received by the Super SIM, or three months have passed, its state will automatically transition to active. Or you can switch it to active manually earlier.
If you have a Super SIM that you want to stop using for an extended period, so that it does not incur charges, just set its Sim resource's status to inactive. For example:
When you're ready to use the SIM again, simply reactivate it:
Alternatively, make these status changes in Console, as described in the previous section.
An inactive Sim resource can only reconnect if it is moved back into the active state, and this can only be achieved through the API, as shown above, or Console, under your account credentials.
If a physical Super SIM is lost or stolen, switch it to inactive as soon as possible to prevent its use. An inactive Super SIM is blocked from connecting to the network.
new
The Sim resource has never been activated, and the represented Super SIM can't connect to the network. A Sim resource can remain in new indefinitely at no charge. Once it has transitioned to ready or active, it can't be returned to new
ready
active
The Sim resource's Super SIM can connect to the network and is capable of consuming network resources in accordance with the configuration of the Fleet resource to which it has been assigned (indicated by the Sim resource's fleet_sid property)
inactive
The Sim resource's Super SIM is blocked from connecting to the network. The Sim resource can be switched to active at any time. A Sim resource can remain in inactive indefinitely at no charge
scheduled
A request to update the Sim resource's state is queued and will be processed asynchronously. The value of status will automatically transition to the requested state when the update operation has completed
The Sim resource's Super SIM can connect to the network and is capable of consuming network resources in accordance with the configuration of the to which it has been assigned (indicated by the Sim resource's fleet_sid property), but no monthly subscription fee will be charged. A Sim resource's status can only be switched to ready if it currently new. Once a ready Super SIM has consumed 250KB of data, five SMS Commands have been sent or received by the Super SIM, or three months have passed, the Sim resource's state will automatically transition to active. Use ready to enable and test your connectivity without incurring monthly fees before devices are sent to end-users or deployed into the field
