How to Determine a Super SIM’s Status

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 it governs whether partner networks permit that Super SIM to access network resources.

So what do these states represent exactly?

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.

Expand image

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:

Expand image

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, or tools like the Twilio CLI and curl. However you make the request, the value of the returned resource's status property will tell you its state.

For example, if you request a Sim resource using the Twilio CLI:

twilio api:supersim:v1:sims:fetch --sid <YOUR_SIM_SID_OR_UNIQUE_NAME>

The response is:

1
SID                                 Unique Name  Status
2
HSxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx  sim-name     new

Alternatively, you can get the response as JSON:

1
twilio api:supersim:v1:sims:fetch --sid <YOUR_SIM_SID_OR_UNIQUE_NAME> -o json
2

3
[
4
  { 
5
    "sid": "<SIM_SID>",
6
    "account_sid": "<YOUR_ACCOUNT_SID>",
7
    "unique_name": "My SIM",
8
    "status": "new",
9
    "fleet_sid": null,
10
    "iccid": "<THE_SIM_ICCID>",
11
    "date_created": "2015-07-30T20:00:00Z",
12
    "date_updated": "2015-07-30T20:00:00Z",
13
    "url": "https://supersim.twilio.com/v1/Sims/<SIM_SID>"
14
  }
15
]

Or you might make the using curl:

1
curl -X GET https://supersim.twilio.com/v1/Sims/<YOUR_SIM_SID_OR_UNIQUE_NAME> \
2
  -u <YOUR_ACCOUNT_SID>:<YOUR_AUTH_TOKEN>

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, or tools like the Twilio CLI and curl. In the request's URL-encoded query parameters, you include Status — its value is the state to which you want the Sim to transition. For example:

1
twilio api:supersim:v1:sims:update --sid <YOUR_SIM_SID_OR_UNIQUE_NAME> \
2
  --status <NEW_STATE>

or:

1
curl -X POST https://supersim.twilio.com/v1/Sims/<SIM_SID> \
2
  -d "Status=<NEW_STATE>" \
3
  -u <YOUR_ACCOUNT_ID>:<YOUR_AUTH_TOKEN>

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:

1
twilio api:supersim:v1:sims:update --sid <YOUR_SIM_SID_OR_UNIQUE_NAME> \
2
  --status <NEW_STATE> \
3
    --callback-url https://example.com/api

or

1
curl -X POST https://supersim.twilio.com/v1/Sims/<SIM_SID> \
2
  -d "Status=<NEW_STATE>" \
3
  -d "CallbackUrl=https://example.com/api" \
4
  -u <YOUR_ACCOUNT_ID>:<YOUR_AUTH_TOKEN>

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:

1
twilio api:supersim:v1:sims:update --sid <YOUR_SIM_SID_OR_UNIQUE_NAME> \
2
  --status inactive

or:

1
curl -X POST https://supersim.twilio.com/v1/Sims/<SIM_SID> \
2
  -d "Status=inactive" \
3
  -u <YOUR_ACCOUNT_ID>:<YOUR_AUTH_TOKEN>

When you're ready to use the SIM again, reactivate it:

1
twilio api:supersim:v1:sims:update --sid <YOUR_SIM_SID_OR_UNIQUE_NAME> \
2
  --status active

or:

1
curl -X POST https://supersim.twilio.com/v1/Sims/<SIM_SID> \
2
  -d "Status=active" \
3
  -u <YOUR_ACCOUNT_ID>:<YOUR_AUTH_TOKEN>

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.