Menu

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?

REST API: Sims

A Sim instance represents a physical SIM that is capable of connecting to a wireless network.

To avoid ambiguity throughout this page, 'Sim' (capitalized) refers to the Sim API resource. 'SIM' (all caps) refers to the physical Subscriber Identity Module (e.g. a SIM card) associated with a Sim resource.

Before becoming active, a Sim must have a Rate Plan, which describes the capabilities and restrictions that will apply to the SIM.

Common Tasks

Asynchronous Resources

The Sim resource performs Asynchronous Operations. To receive an asynchronous notification when a Sim resource has finished updating, you should provide a callback URL and optionally a callback method parameter with your initial HTTP Request. This is demonstrated in some of the examples below.

HTTP Resources and Methods

Sim Instance Resource

Resource URLs

https://wireless.twilio.com/v1/Sims/{SimSid}
https://wireless.twilio.com/v1/Sims/{SimUniqueName}

Resource Properties

A Sim instance resource is represented by the following properties:

Names in PHP format
sid
sid<DE> Not PII

A 34 character string that uniquely identifies this resource.

uniqueName
string Not PII

A user-provided string that uniquely identifies this resource as an alternative to the sid.

accountSid
sid<AC> Not PII

The unique id of the Account that this Sim belongs to.

ratePlanSid
sid<WP> Not PII

The unique ID of the Rate Plan configured for this Sim.

friendlyName

A user-provided string that identifies this resource. Non-unique.

iccid

The ICCID associated with the SIM.

eId
string Not PII

status
enum:status Not PII

A string representing the status of the Sim. May be new, ready, active, deactivated, canceled, scheduled or updating. See Status Values for a description of each status.

commandsCallbackUrl
url Not PII

The URL that will receive a webhook when this Sim originates a machine-to-machine Command. Your server should respond with an HTTP status code in the 200 range; any response body will be ignored.

commandsCallbackMethod
http_method Not PII

A string representing the HTTP method to use when making a request to commands_callback_url. Can be one of POST or GET. Defaults to POST.

smsFallbackMethod
http_method Not PII

The HTTP method Twilio will use when requesting the sms_fallback_url. Either GET or POST.

smsFallbackUrl
url Not PII

The URL that Twilio will request if an error occurs retrieving or executing the TwiML requested by sms_url.

smsMethod
http_method Not PII

The HTTP method Twilio will use when requesting the above Url. Either GET or POST.

smsUrl
url Not PII

The URL Twilio will request when the SIM-connected device send an SMS that is not a Command.

voiceFallbackMethod
http_method Not PII

The HTTP method Twilio will use when requesting the voice_fallback_url. Either GET or POST.

voiceFallbackUrl
url Not PII

The URL that Twilio will request if an error occurs retrieving or executing the TwiML requested by voice_url.

voiceMethod
http_method Not PII

The HTTP method Twilio will use when requesting the above Url. Either GET or POST.

voiceUrl
url Not PII

The URL Twilio will request when the SIM-connected device makes a call.

dateCreated
date_time<iso8601> Not PII

The date that this resource was created, given as GMT in ISO 8601 format.

dateUpdated
date_time<iso8601> Not PII

The date that this resource was last updated, given as GMT in ISO 8601 format.

url
url Not PII

The URL for this resource.

links
uri_map Not PII

Each Sim instance resource supports a few subresources, listed here for convenience.

ipAddress
string Not PII

Status Values

The table below describes the available status values of a Sim instance.

Status Description
new The Sim is waiting to be activated so that it can join the network. A Sim 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 Rate Plan, but no monthly fee will be charged. Once the SIM has consumed 250KB of data or three months have passed, the Sim will transition automatically to active status. On the fifth Command sent to_sim or from_sim the device will automatically transition to the active status. Use the ready status when shipping your device to a customer if you aren't exactly sure when they'll start using it. Not available for the Narrowband developer plan.
active The Sim can connect to the network and is capable of consuming network resources in accordance with its Rate Plan.
suspended The Sim is blocked from connecting to the network. After three months of suspension at no charge, a suspended monthly fee will be initiated. See pricing.
deactivated The Sim is blocked from connecting to the network. After 72 hours, the Sim will transition automatically to the terminal status canceled. Use this status when you never want the Sim to reconnect (for example it has been lost or stolen).
canceled Terminal status. The Sim is blocked from connecting to the network, and can no longer be reactivated.
scheduled The upstream network operator is temporarily unable to update the status of this SIM. The Sim status will be automatically updated to the requested status when the upstream network operator resumes accepting transactions.
updating The Sim is in the process of being asynchronously updated. While the Sim is updating, it may not be possible to modify some fields. In these cases, you will receive a 409 Conflict response.

HTTP GET

Returns a representation of the Sim identified by the Sid or Alias property.

Example

Request a Sim instance using its Sid, represented as JSON.

        
        
        
        
        Example

        Request a Sim instance using its UniqueName, represented as JSON.

              
              
              
              

              HTTP POST

              The POST method allows you to update a Sim instance resource.

              Optional Parameters

              Any or all of the following parameters can be provided. In the case where a request parameter corresponds to a property on the instance resource, that property will be updated to the provided value.

              Names in PHP format
              sid
              Required
              post sid_like<DE> Not PII

              A 34 character string that uniquely identifies this resource.

              uniqueName
              Optional
              post string Not PII

              A user-provided string that uniquely identifies this resource as an alternative to the Sid.

              callbackMethod
              Optional
              post http_method Not PII

              The HTTP method Twilio will use when making a request to the callback URL (valid options are GET or POST). Defaults to POST.

              callbackUrl
              Optional
              post url Not PII

              Twilio will make a request to this URL when the Sim has finished updating. In the case of a transition from the Sim's new status to its ready status, or from any status to its deactivated status, you will receive two callbacks. One when the Sim moves to its intermediary status (ready or deactivated), and a second when it transitions to its final status (active or canceled).

              friendlyName
              Optional
              post string PII MTL: 30 DAYS

              A user-provided string that identifies this resource. Non-unique.

              ratePlan
              Optional
              post sid_like<WP> Not PII

              The Sid or UniqueName of the RatePlan that this Sim should use. Note: the RatePlan of a Sim can only be modified when the Sim has a suspended or deactivated status.

              status
              Optional
              post enum:status Not PII

              A string representing the status of the Sim. Valid options depend on the current state of the Sim, but may include ready, active, suspended or deactivated.

              commandsCallbackMethod
              Optional
              post http_method Not PII

              A string representing the HTTP method to use when making a request to CommandsCallbackUrl. Can be one of POST or GET. Defaults to POST.

              commandsCallbackUrl
              Optional
              post url Not PII

              The URL that will receive a webhook when this Sim originates a Command. Your server should respond with an HTTP status code in the 200 range; any response body will be ignored.

              smsFallbackMethod
              Optional
              post http_method Not PII

              The HTTP method Twilio will use when requesting the sms_fallback_url. Either GET or POST.

              smsFallbackUrl
              Optional
              post url Not PII

              The URL that Twilio will request if an error occurs retrieving or executing the TwiML requested by sms_url.

              smsMethod
              Optional
              post http_method Not PII

              The HTTP method Twilio will use when requesting the above Url. Either GET or POST.

              smsUrl
              Optional
              post url Not PII

              The URL Twilio will request when the SIM-connected device sends an SMS message that is not a Command.

              voiceFallbackMethod
              Optional
              post http_method Not PII

              The HTTP method Twilio will use when requesting the voice_fallback_url. Either GET or POST.

              voiceFallbackUrl
              Optional
              post url Not PII

              The URL that Twilio will request if an error occurs retrieving or executing the TwiML requested by voice_url.

              voiceMethod
              Optional
              post http_method Not PII

              The HTTP method Twilio will use when requesting the above Url. Either GET or POST.

              voiceUrl
              Optional
              post url Not PII

              The URL Twilio will request when the SIM-connected device makes a call.

              Callback Values

              If a callback URL is present in your request, the asynchronous request made to that URL will contain the following parameters.

              Parameter Description
              SimSid The Sim that this callback is in reference to.
              SimUniqueName The Sim's UniqueName, if it has one.
              SimStatus An updated string representing the new status of the Sim.
              ErrorCode If an error occurred, an error code is provided.
              ErrorMessage If an error occurred, an error message is provided.
              ApiVersion The version of the API that your initial request was made to.
              AccountSid The unique id of the Account that this Sim 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

              Update a Sim by setting its status to active. Provide a callback URL and callback method to be asynchronously notified when the update has completed.

                    
                    
                    
                    

                    HTTP PUT

                    Not supported.

                    HTTP DELETE

                    Delete a Sim from your account.

                    Sim Instance Subresources

                    Sim Usage Records Subresource

                    Represents a usage report for the Sim over a specified period. See the Sim Usage Records resource for properties and response formats.

                    Resource URLs

                    https://wireless.twilio.com/v1/Sims/{SimSid}/UsageRecords
                    https://wireless.twilio.com/v1/Sims/{SimUniqueName}/UsageRecords
                    

                    Sims List Resource

                    Resource URL

                    https://wireless.twilio.com/v1/Sims
                    

                    HTTP GET

                    Returns a list of Sims within an account. The list includes paging information.

                    Example 1

                    List all Sims in the account.

                          
                          
                          
                          
                          List Filters

                          The following GET query string parameters allow you to limit the list returned. Note, parameters are case-sensitive:

                          Parameter Description
                          Status Only return Sims with this status.
                          RatePlan Only return Sims with this Rate Plan.
                          Iccid Return Sims with this Iccid. Currently this should be a list with maximum size 1.

                          HTTP POST

                          Not Supported. SIM resources are created by ordering SIMs, or registering a Starter SIM.

                          HTTP PUT

                          Not supported.

                          HTTP DELETE

                          Not supported.

                          Sim Lifecycle Events

                          The lifecycle events of a Sim are audited and reported by Monitor Events. An update to a Sim resource results in a Monitor Event with an 'Event Type' of wireless-sim.updated. The valid resource_properties that can be reported are rate_plan_sid and status. For each, a previous and updated value may be provided. For example:

                          "event_data": {
                            "resource_properties": {
                              "rate_plan_sid": {
                                "previous": "WP0195dea2f0b1e00dbc54d0715e36e2db",
                                "updated": "WP3b921b4711ee21ac01c7075a7eb19fcf"
                              },
                              "status": {
                                "previous": "new",
                                "updated": "active"
                              }
                            }
                          }
                          

                          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.