Menu

Expand
Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

How to Determine a Super SIM’s Status

Every Sim resource records one of four 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.

Sim resource states

At any given moment, a Sim resource will be in one of the following states:

  • new
  • 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 access to 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 access to network resources.

So what do these states represent exactly?

State Meaning
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 active, it can’t be returned to new
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 An update to the Sim resource’s status is queued and will be processed asynchronously. The value of status will automatically transition to the requested state when the update operation has completed

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 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.

Active Super SIMs

When a Sim resource’s status is 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 active in order to be able to connect.

Once active, the Sim resource can be manually transitioned to inactive only by specifying that as its new status value. The resource’s status will initially be set to scheduled. The change to the requested state is made asynchronously, and the resource’s status will only show the desired value when the update has actually been applied:

When you change a Sim resource, you can include a callback URL (as the value of the query parameter CallbackUrl) and this 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.

The following diagram shows how this asynchronous behavior operates over time:

How to check a Sim’s status

Please see the Sim resource documentation to learn how to request Sim resources. The value of the resource’s status property will tell you its current state. For example, if you request a Sim resource using curl:

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

The response returns the Sim resource as JSON:

{ "sid": "<SIM_SID>",
  "account_sid": "<YOUR_ACCOUNT_SID>",
  "unique_name": "My SIM",
  "status": "new",
  "fleet_sid": null,
  "iccid": "<THE_SIM_ICCID>",
  "date_created": "2015-07-30T20:00:00Z",
  "date_updated": "2015-07-30T20:00:00Z",
  "url": "https://supersim.twilio.com/v1/Sims/<SIM_SID>" }

As you can see, this Sim has not yet been activated — its status is new — and it has not yet been assigned to a Fleet.

You can also view a Super SIM’s status in the Console, under the STATUS column of the SIMs list.

How to change a Sim’s status

You can change a Sim resource’s status by making a POST request to the API. 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:

curl -X POST \
    https://supersim.twilio.com/v1/Sims/<SIM_SID> \
    --data-urlencode "Status=<NEW_STATE>" \
    -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:

curl -X POST \
    https://supersim.twilio.com/v1/Sims/<SIM_SID> \
    --data-urlencode "Status=<NEW_STATE>" \
    --data-urlencode "CallbackUrl=https://example.com/api/v1/notifications" \
    -u <YOUR_ACCOUNT_ID>:<YOUR_AUTH_TOKEN>

The only states that a Sim resource can be manually instructed to change to are active and inactive. Once it is no longer new, a Sim can never return to that state. The scheduled state is only ever set automatically, and briefly, in response to your own state-change requests.

When to change a Sim’s state

You will transition a fresh Super Sim from new to active (via scheduled) when you fit it into a device, configure the device’s Access Point Name (APN) setting, and connect to the network.

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: send a POST request to the API and set the Status parameter’s value to inactive. For example:

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

When you’re ready to use the SIM again, simply reactivate it: just send a POST request to the API and this set the Status parameter’s value to active:

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

An inactive Sim 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 the 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.

Rate this page:

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.