Sim Resource
To avoid ambiguity throughout this page, Sim (initial cap) refers to the Sim API resource. SIM (all caps) refers to the physical Subscriber Identity Module (that is, a SIM card) associated with a Sim resource.
A Sim instance represents a single physical Super SIM:
https://supersim.twilio.com/v1/SimsA Sim instance can be referenced in the API either by its unique sid or a user-defined unique_name:
https://supersim.twilio.com/v1/Sims/{sid}
https://supersim.twilio.com/v1/Sims/{uniqueName}Before a Super SIM can begin using data or sending/receiving SMS via Commands, the corresponding Sim instance must be assigned to a Fleet and activated.
Customers may request that Sim data be deleted. If you wish to do so, please contact our support team. For more information on Twilio’s data retention and deletion policy, please see this support document.
Sim properties
| Resource Properties in REST API format | |
|---|---|
sid
|
The unique string that identifies the Sim resource. |
unique_name
|
An application-defined string that uniquely identifies the resource. It can be used in place of the resource's |
account_sid
|
The SID of the Account that the Super SIM belongs to. |
iccid
|
The ICCID associated with the SIM. |
status
|
The status of the Super SIM. Can be |
fleet_sid
|
The unique ID of the Fleet configured for this SIM. |
date_created
|
The date and time in GMT when the resource was created specified in ISO 8601 format. |
date_updated
|
The date and time in GMT when the resource was last updated specified in ISO 8601 format. |
url
|
The absolute URL of the Sim Resource. |
links
|
|
Status values
The table below describes the available status values of a Sim instance:
| Status | Description |
new |
The SIM has never been enabled and is waiting to be activated so that it can connect to the network. A Sim resource can exist in |
ready |
The SIM can connect to the network and is capable of consuming network resources in accordance with its Fleet, but no monthly subscription fee will be charged. A Sim resource’s status can only be updated to Once the SIM has consumed 250KB of data, five SMS Commands have been sent to or received from the SIM, or three months have passed, the Sim resource’s status will automatically transition to Use |
active |
The SIM can connect to the network and is capable of consuming network resources in accordance with its Fleet. |
inactive |
The SIM is blocked from connecting to the network. |
scheduled |
The update is queued and will be processed when the network operator is ready. The Sim resource’s status will automatically transition to the requested status when the update operation is completed. |
Add a Super SIM to your Account
https://supersim.twilio.com/v1/Sims
All Super SIMs purchased through Console arrive pre-registered to the Twilio account which placed the order. To receive an unregistered Super SIM that is eligible to be added to your Account, you will have received the SIM either at an in-person event, such as a developer conference, or from an independent partner as part of their solution.
If you are interested in ordering unregistered SIMs for your use case, please contact sales-wireless@twilio.com to speak with an IoT Sales Specialist.
If you have a Super SIM that has not yet been registered to a Twilio Account, you can add it to your Account by providing the SIM’s ICCID and the registration code. On a plastic multi-size SIM card, these two values are printed on the card. For an embedded SIM (MFF2), if you have a registrable SIM, you will need to obtain this information either from your vendor or from Twilio.
Parameters
| Parameters in REST API format | |
|---|---|
iccid
Required
|
The ICCID of the Super SIM to be added to your Account. |
registration_code
Required
|
The 10-digit code required to claim the Super SIM for your Account. |
Example 1
Fetch a Sim resource
https://supersim.twilio.com/v1/Sims/{Sid}
Parameters
| Parameters in REST API format | |
|---|---|
sid
Path
|
The SID of the Sim resource to fetch. |
Example 1
You can fetch a Sim resource by either its sid or unique_name. To find a Sim resource by a Super SIM’s ICCID, use the iccid query parameter while reading from the Sims resource.
Read multiple Sim resources
https://supersim.twilio.com/v1/Sims
Parameters
| Parameters in REST API format | |
|---|---|
status
Optional
|
The status of the Sim resources to read. Can be |
fleet
Optional
|
The SID or unique name of the Fleet to which a list of Sims are assigned. |
iccid
Optional
|
The ICCID associated with a Super SIM to filter the list by. Passing this parameter will always return a list containing zero or one SIMs. |
Example 1
Find a Sim resource by a Super SIM’s ICCID
You may need to find a Sim resource with just a Super SIM’s ICCID. You can read the Sim resource by an ICCID using the iccid query parameter. If a Sim resource for that ICCID is found, a list with one record will be returned. If a Sim resource for that ICCID is not found on your Account, an empty list will be returned.
Example 2
Update a Sim resource
https://supersim.twilio.com/v1/Sims/{Sid}
Parameters
| Parameters in REST API format | |
|---|---|
sid
Path
|
The SID of the Sim resource to update. |
unique_name
Optional
|
An application-defined string that uniquely identifies the resource. It can be used in place of the resource's |
status
Optional
|
The new status of the resource. Can be: |
fleet
Optional
|
The SID or unique name of the Fleet to which the SIM resource should be assigned. |
callback_url
Optional
|
The URL we should call using the |
callback_method
Optional
|
The HTTP method we should use to call |
account_sid
Optional
|
The SID of the Account to which the Sim resource should belong. The Account SID can only be that of the requesting Account or that of a Subaccount of the requesting Account. Only valid when the Sim resource's status is new. |
Asynchronous updates
Some Sim resource updates will be completed asynchronously. To receive a notification when a Sim resource has finished updating, provide a callback_url and a callback_method with your initial HTTP request.
When an update is handled asynchronously, the Sim resource will undergo multiple updates:
- First, the Sim resource’s
statuswill be set toscheduledas the update is placed in a queue. - Finally, the Sim resource’s
statuswill transition to the final state.
If a Sim resource’s Fleet is changed as part of an asychronous update, the existing value of the fleet_sid property will be returned when the update request is accepted. When the update completes, the new value will be shown on the Sim resource.
In the scenarios below, “activating” means updating the Sim resource’s status to a value that will allow the Super SIM to use cellular network resources: either ready or active. Please refer to Status values for descriptions of each status.
The following update scenarios will be handled asynchronously:
Activating a Sim resource
When a Sim resource’s status is updated from new to ready or active.
Deactivating a Sim resource
When a Sim resource’s status is updated from active to inactive.
Reactivating a Sim resource
When a Sim resource’s status is updated from inactive to active.
Changing an activated Sim resource’s Fleet
When a Sim resource is already ready or active and its Fleet is updated. When the update request is accepted, the Sim resource's status will change to scheduled. The Sim resource’s fleet_sid property will be unchanged at this point. If the update succeeds, the Sim resource’s status returns to ready or active and the Sim resource’s fleet_sid property now returns the new Fleet resource’s SID.
Callback values
If you provided a value for the callback_url parameter in your update request, the asynchronous request made to that URL will contain the following parameters.
SimSid |
The unique SID of the Sim resource that this callback is in reference to. |
SimUniqueName |
The Sim resource’s |
SimStatus |
A string representing the Sim resource’s status after the update completed. |
AccountSid |
The unique SID of the Account that the Sim resource belongs to. |
If the callback_method was set to POST or not provided, the callback parameters will be delivered as HTML form parameters. If the callback_method was set to GET, the callback parameters will be delivered as a query string.
Example 1
Example 2
Example 3
Example 4
Move Super SIMs between Subaccounts
If you are using Subaccounts, you can transfer new Super SIMs between your accounts.
While using the primary Account’s credentials, use the account_sid parameter to provide the Account SID of the Account you wish to own that Super SIM. Super SIMs can be moved between Accounts the following ways:
- From the primary Account to a Subaccount.
- From a Subaccount to the primary Account.
- From a subaccount to another Subaccount.
If the Super SIM you are moving is assigned to a Fleet, you must also pass the sid or unique_name of a Fleet resource that belongs to the new Account, or null, in the fleet parameter of your Update request.
Example 5
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 by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.
