Menu

Expand
Rate this page:

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/Sims

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

Sim properties

Resource Properties in REST API format
sid
sid<HS> Not PII

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 sid in the URL to address the resource.

account_sid
sid<AC> Not PII

The SID of the Account that the Super SIM belongs to.

iccid

The ICCID associated with the SIM.

status
enum:status Not PII

The status of the Super SIM. Can be new, ready, active, inactive, or scheduled. See the Super SIM Status Values for a description of each.

fleet_sid
sid<HF> Not PII

The unique ID of the Fleet configured for this SIM.

date_created
date_time<iso8601> Not PII

The date and time in GMT when the resource was created specified in ISO 8601 format.

date_updated
date_time<iso8601> Not PII

The date and time in GMT when the resource was last updated specified in ISO 8601 format.

url
url Not PII

The absolute URL of the Sim Resource.

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 new status indefinitely at no charge, but once it is transitioned to ready or active, it cannot be returned to new.

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 ready if it is currently new.


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


Use ready to enable and test your connectivity before devices are sent to customers or deployed into the field without incurring monthly fees.

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.

Fetch a Sim resource

get
https://supersim.twilio.com/v1/Sims/{Sid}
Parameters
Parameters in REST API format
sid
Path
get sid_like<HS> Not PII

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

        get
        https://supersim.twilio.com/v1/Sims
        Parameters
        Parameters in REST API format
        status
        Optional
        get ienum:status Not PII

        The status of the Sim resources to read. Can be new, ready, active, inactive, or scheduled.

        fleet
        Optional
        get sid_like<HF> Not PII

        The SID or unique name of the Fleet to which a list of Sims are assigned.

        iccid
        Optional
        get string PII MTL: 30 DAYS

        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 by 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
                    
                    
                    
                    
                    Read a Sim resource by its ICCID. Returns a list with 1 or 0 records.

                    Read a Sim Resource by its ICCID

                    Read a Sim resource by its ICCID. Returns a list with 1 or 0 records.

                    Update a Sim resource

                    post
                    https://supersim.twilio.com/v1/Sims/{Sid}
                    Parameters
                    Parameters in REST API format
                    sid
                    Path
                    post sid_like<HS> Not PII

                    The SID of the Sim resource to update.

                    unique_name
                    Optional
                    post string PII MTL: 30 DAYS

                    An application-defined string that uniquely identifies the resource. It can be used in place of the resource's sid in the URL to address the resource.

                    status
                    Optional
                    post ienum:status_update Not PII

                    The new status of the resource. Can be: ready, active, or inactive. See the Super SIM Status Values for more info.

                    fleet
                    Optional
                    post sid_like<HF> Not PII

                    The SID or unique name of the Fleet to which the SIM resource should be assigned.

                    callback_url
                    Optional
                    post url Not PII

                    The URL we should call using the callback_method after an asynchronous update has finished.

                    callback_method
                    Optional
                    post http_method Not PII

                    The HTTP method we should use to call callback_url. Can be: GET or POST and the default is POST.

                    account_sid
                    Optional
                    post sid_like<AC> Not PII

                    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 status will be set to scheduled as the update is placed in a queue.
                    • Finally, the Sim resource’s status will 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 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 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 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 unique_name if it has one.

                    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
                                
                                
                                
                                
                                Your Super SIM’s permissions are controlled by its Fleet

                                Update a Sim’s Fleet

                                Your Super SIM’s permissions are controlled by its Fleet
                                Example 3
                                      
                                      
                                      
                                      
                                      You can refer to a Fleet by its Unique Name when updating your Sim

                                      Update a Sim’s Fleet by Unique Name

                                      You can refer to a Fleet by its Unique Name when updating your Sim
                                      Example 4
                                            
                                            
                                            
                                            
                                            Activate your Super SIM to connect to the network

                                            Update a Sim’s Status

                                            Activate your Super SIM to connect to the network

                                            Move Super SIMs between Subaccounts

                                            If you are using Subaccounts, you can transfer new Super SIMs between your accounts.

                                            While using the master 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 master account to a subaccount.
                                            • From a subaccount to the master 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
                                                  
                                                  
                                                  
                                                  
                                                  Sim resource must be `new`

                                                  Transfer a Super SIM to a Subaccount

                                                  Sim resource must be `new`
                                                  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.

                                                        
                                                        
                                                        

                                                        Thank you for your feedback!

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

                                                        Sending your feedback...
                                                        🎉 Thank you for your feedback!
                                                        Something went wrong. Please try again.

                                                        Thanks for your feedback!

                                                        Refer us and get $10 in 3 simple steps!

                                                        Step 1

                                                        Get link

                                                        Get a free personal referral link here

                                                        Step 2

                                                        Give $10

                                                        Your user signs up and upgrade using link

                                                        Step 3

                                                        Get $10

                                                        1,250 free SMSes
                                                        OR 1,000 free voice mins
                                                        OR 12,000 chats
                                                        OR more