Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

Wireless Sim Resource


A Sim resource represents a physical SIM that can connect to a wireless network.

(information)

Info

To avoid ambiguity, 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.

(warning)

Warning

A Sim resource must have a Rate Plan before it can become active. The Rate Plan describes the capabilities and restrictions that apply to the SIM.


Asynchronous resources

asynchronous-resources page anchor

The Sim resource operates asynchronously. To receive a notification when a Sim resource has finished updating, you should provide a callback URL and a callback method with your initial HTTP request. This is demonstrated in an example below.


Resource properties
sidtype: SID<DE>Not PII

The unique string that we created to identify the Sim resource.


unique_nametype: stringPII 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.


rate_plan_sidtype: SID<WP>Not PII

The SID of the RatePlan resource(link takes you to an external page) to which the Sim resource is assigned.


friendly_nametype: stringPII MTL: 30 days

The string that you assigned to describe the Sim resource.


iccidtype: stringPII MTL: 30 days

The ICCID(link takes you to an external page) associated with the SIM.


e_idtype: stringNot PII

Deprecated.


statustype: enum<STRING>Not PII

The status of the Sim resource. Can be: new, ready, active, deactivated, canceled, deleted, scheduled, or updating. See Status Values(link takes you to an external page) for the description of each status.

Possible values:
newreadyactivesuspendeddeactivatedcanceledscheduledupdating

reset_statustype: enum<STRING>Not PII

The connectivity reset status of the SIM. Can be: null or resetting. When a connectivity reset is initiated on a SIM, this property is resetting. After the reset completes, it is null.

Possible values:
resetting

commands_callback_urltype: string<URI>Not PII

The URL we call using the commands_callback_method when the SIM originates a machine-to-machine Command(link takes you to an external page). Your server should respond with an HTTP status code in the 200 range; any response body will be ignored.


commands_callback_methodtype: enum<HTTP METHOD>Not PII

The HTTP method we use to call commands_callback_url. Can be: POST or GET. Default is POST.

Possible values:
HEADGETPOSTPATCHPUTDELETE

sms_fallback_methodtype: enum<HTTP METHOD>Not PII

Deprecated.

Possible values:
HEADGETPOSTPATCHPUTDELETE

sms_fallback_urltype: string<URI>Not PII

Deprecated.


sms_methodtype: enum<HTTP METHOD>Not PII

Deprecated.

Possible values:
HEADGETPOSTPATCHPUTDELETE

sms_urltype: string<URI>Not PII

Deprecated.


voice_fallback_methodtype: enum<HTTP METHOD>Not PII

Deprecated. The HTTP method we use to call voice_fallback_url. Can be: GET or POST. Default is POST.

Possible values:
HEADGETPOSTPATCHPUTDELETE

voice_fallback_urltype: string<URI>Not PII

Deprecated. The URL we call using the voice_fallback_method when an error occurs while retrieving or executing the TwiML requested from voice_url.


voice_methodtype: enum<HTTP METHOD>Not PII

Deprecated. The HTTP method we use to call voice_url. Can be: GET or POST. Default is POST.

Possible values:
HEADGETPOSTPATCHPUTDELETE

voice_urltype: string<URI>Not PII

Deprecated. The URL we call using the voice_method when the SIM-connected device makes a voice call.


date_createdtype: string<DATE TIME>Not PII

The date and time in GMT when the resource was created specified in ISO 8601(link takes you to an external page) format.


date_updatedtype: string<DATE TIME>Not PII

The date and time in GMT when the Sim resource was last updated specified in ISO 8601(link takes you to an external page) format.


urltype: string<URI>Not PII

The absolute URL of the resource.


linkstype: object<URI MAP>Not PII

The URLs of related subresources.


ip_addresstype: stringNot PII

Deprecated.

Status Values

status-values page anchor

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

StatusDescription
newThe SIM is waiting to be activated so that it can join the network. A Sim can remain new indefinitely at no charge, but once it becomes ready or active, it cannot be returned to new.
readyThe 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 become active.Use the ready status when shipping your device to a customer if you aren't exactly sure when they will start using it.Note This statis is not available for the Narrowband developer plan.
activeThe SIM can connect to the network and is capable of consuming network resources in accordance with its Rate Plan.
suspendedThe SIM is blocked from connecting to the network. After three months of suspension at no charge, a suspended monthly fee will be initiated. See Suspended SIM Fees in Programmable Wireless Pricing for more details.
deactivatedThe 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, if it has been lost or stolen.
canceledTerminal status. The SIM is blocked from connecting to the network and can never be reactivated.
scheduledThe upstream network operator is temporarily unable to update the status of this SIM. Its status will be automatically updated to the requested status when the upstream network operator resumes accepting transactions.
updatingThe 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.

GET https://wireless.twilio.com/v1/Sims/{Sid}

The {Sid} parameter can be the SID or the UniqueName property of the Sim resource that you want to fetch.

Parameters

fetch-parameters page anchor
URI parameters
Sidtype: stringNot PII
Path Parameter

The SID or the unique_name of the Sim resource to fetch.

Fetch a Sim resource identified by its SID

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_10
// Download the helper library from https://www.twilio.com/docs/node/install
_10
// Find your Account SID and Auth Token at twilio.com/console
_10
// and set the environment variables. See http://twil.io/secure
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.wireless.v1.sims('DEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_10
.fetch()
_10
.then(sim => console.log(sim.uniqueName));

Output

_30
{
_30
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_30
"unique_name": "unique_name",
_30
"commands_callback_method": "POST",
_30
"commands_callback_url": "http://www.example.com",
_30
"date_created": "2015-07-30T20:00:00Z",
_30
"date_updated": "2015-07-30T20:00:00Z",
_30
"friendly_name": "friendly_name",
_30
"sms_fallback_method": "POST",
_30
"sms_fallback_url": "http://www.example.com",
_30
"sms_method": "POST",
_30
"sms_url": "http://www.example.com",
_30
"voice_fallback_method": "POST",
_30
"voice_fallback_url": "http://www.example.com",
_30
"voice_method": "POST",
_30
"voice_url": "http://www.example.com",
_30
"links": {
_30
"data_sessions": "https://wireless.twilio.com/v1/Sims/DEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/DataSessions",
_30
"rate_plan": "https://wireless.twilio.com/v1/RatePlans/WPXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_30
"usage_records": "https://wireless.twilio.com/v1/Sims/DEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/UsageRecords"
_30
},
_30
"rate_plan_sid": "WPXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_30
"sid": "DEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_30
"iccid": "iccid",
_30
"e_id": "e_id",
_30
"status": "new",
_30
"reset_status": null,
_30
"url": "https://wireless.twilio.com/v1/Sims/DEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_30
"ip_address": "192.168.1.1"
_30
}

Fetch a Sim by its UniqueName

fetch-a-sim-by-its-uniquename page anchor

Fetch a Sim resource identified by its UniqueName

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_10
// Download the helper library from https://www.twilio.com/docs/node/install
_10
// Find your Account SID and Auth Token at twilio.com/console
_10
// and set the environment variables. See http://twil.io/secure
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.wireless.v1.sims('AliceSmithSmartMeter')
_10
.fetch()
_10
.then(sim => console.log(sim.uniqueName));

Output

_30
{
_30
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_30
"unique_name": "unique_name",
_30
"commands_callback_method": "POST",
_30
"commands_callback_url": "http://www.example.com",
_30
"date_created": "2015-07-30T20:00:00Z",
_30
"date_updated": "2015-07-30T20:00:00Z",
_30
"friendly_name": "friendly_name",
_30
"sms_fallback_method": "POST",
_30
"sms_fallback_url": "http://www.example.com",
_30
"sms_method": "POST",
_30
"sms_url": "http://www.example.com",
_30
"voice_fallback_method": "POST",
_30
"voice_fallback_url": "http://www.example.com",
_30
"voice_method": "POST",
_30
"voice_url": "http://www.example.com",
_30
"links": {
_30
"data_sessions": "https://wireless.twilio.com/v1/Sims/DEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/DataSessions",
_30
"rate_plan": "https://wireless.twilio.com/v1/RatePlans/WPXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_30
"usage_records": "https://wireless.twilio.com/v1/Sims/DEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/UsageRecords"
_30
},
_30
"rate_plan_sid": "WPXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_30
"sid": "DEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_30
"iccid": "iccid",
_30
"e_id": "e_id",
_30
"status": "new",
_30
"reset_status": null,
_30
"url": "https://wireless.twilio.com/v1/Sims/DEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_30
"ip_address": "192.168.1.1"
_30
}


Read multiple Sim resources

read-multiple-sim-resources page anchor
GET https://wireless.twilio.com/v1/Sims

Returns a list of SIMs within an account, each represented as a Sim instance. The list is paginated.

URI parameters
Statustype: enum<STRING>Not PII
Query Parameter

Only return Sim resources with this status.

Possible values:
newreadyactivesuspendeddeactivatedcanceledscheduledupdating

Iccidtype: stringPII MTL: 30 days
Query Parameter

Only return Sim resources with this ICCID. This will return a list with a maximum size of 1.


RatePlantype: stringNot PII
Query Parameter

The SID or unique name of a RatePlan resource(link takes you to an external page). Only return Sim resources assigned to this RatePlan resource.


EIdtype: stringNot PII
Query Parameter

Deprecated.


SimRegistrationCodetype: stringNot PII
Query Parameter

Only return Sim resources with this registration code. This will return a list with a maximum size of 1.


PageSizetype: integerNot PII
Query Parameter

How many resources to return in each list page. The default is 50, and the maximum is 1000.


Pagetype: integerNot PII
Query Parameter

The page index. This value is simply for client state.


PageTokentype: stringNot PII
Query Parameter

The page token. This is provided by the API.

Return a list of Sims within an account, including paging information

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_10
// Download the helper library from https://www.twilio.com/docs/node/install
_10
// Find your Account SID and Auth Token at twilio.com/console
_10
// and set the environment variables. See http://twil.io/secure
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.wireless.v1.sims.list({limit: 20})
_10
.then(sims => sims.forEach(s => console.log(s.sid)));

Output

_12
{
_12
"sims": [],
_12
"meta": {
_12
"first_page_url": "https://wireless.twilio.com/v1/Sims?Status=new&Iccid=iccid&RatePlan=rate_plan&PageSize=50&Page=0",
_12
"key": "sims",
_12
"next_page_url": "https://wireless.twilio.com/v1/Sims?Status=new&Iccid=iccid&RatePlan=rate_plan&PageSize=50&Page=1",
_12
"page": 0,
_12
"page_size": 50,
_12
"previous_page_url": "https://wireless.twilio.com/v1/Sims?Status=new&Iccid=iccid&RatePlan=rate_plan&PageSize=50&Page=0",
_12
"url": "https://wireless.twilio.com/v1/Sims?Status=new&Iccid=iccid&RatePlan=rate_plan&PageSize=50&Page=0"
_12
}
_12
}


POST https://wireless.twilio.com/v1/Sims/{Sid}

The {Sid} parameter can be the SID or the UniqueName of the Sim resource to update.

URI parameters
Sidtype: stringNot PII
Path Parameter

The SID or the unique_name of the Sim resource to update.


Request body parameters
UniqueNametype: stringPII MTL: 30 days

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


CallbackMethodtype: enum<HTTP METHOD>Not PII

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

Possible values:
HEADGETPOSTPATCHPUTDELETE

CallbackUrltype: string<URI>Not PII

The URL we should call using the callback_url when the SIM has finished updating. When the SIM transitions from new to ready or from any status to deactivated, we call this URL when the status changes to an intermediate status (ready or deactivated) and again when the status changes to its final status (active or canceled).


FriendlyNametype: stringPII MTL: 30 days

A descriptive string that you create to describe the Sim resource. It does not need to be unique.


RatePlantype: stringNot PII

The SID or unique name of the RatePlan resource(link takes you to an external page) to which the Sim resource should be assigned.


Statustype: enum<STRING>Not PII

The new status of the Sim resource. Can be: ready, active, suspended, or deactivated.

Possible values:
newreadyactivesuspendeddeactivatedcanceledscheduledupdating

CommandsCallbackMethodtype: enum<HTTP METHOD>Not PII

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

Possible values:
HEADGETPOSTPATCHPUTDELETE

CommandsCallbackUrltype: string<URI>Not PII

The URL we should call using the commands_callback_method when the SIM sends a Command(link takes you to an external page). Your server should respond with an HTTP status code in the 200 range; any response body is ignored.


SmsFallbackMethodtype: enum<HTTP METHOD>Not PII

The HTTP method we should use to call sms_fallback_url. Can be: GET or POST. Default is POST.

Possible values:
HEADGETPOSTPATCHPUTDELETE

SmsFallbackUrltype: string<URI>Not PII

The URL we should call using the sms_fallback_method when an error occurs while retrieving or executing the TwiML requested from sms_url.


SmsMethodtype: enum<HTTP METHOD>Not PII

The HTTP method we should use to call sms_url. Can be: GET or POST. Default is POST.

Possible values:
HEADGETPOSTPATCHPUTDELETE

SmsUrltype: string<URI>Not PII

The URL we should call using the sms_method when the SIM-connected device sends an SMS message that is not a Command(link takes you to an external page).


VoiceFallbackMethodtype: enum<HTTP METHOD>Not PII

Deprecated.

Possible values:
HEADGETPOSTPATCHPUTDELETE

VoiceFallbackUrltype: string<URI>Not PII

Deprecated.


VoiceMethodtype: enum<HTTP METHOD>Not PII

Deprecated.

Possible values:
HEADGETPOSTPATCHPUTDELETE

VoiceUrltype: string<URI>Not PII

Deprecated.


ResetStatustype: enum<STRING>Not PII

Initiate a connectivity reset on the SIM. Set to resetting to initiate a connectivity reset on the SIM. No other value is valid.

Possible values:
resetting

AccountSidtype: stringNot PII

The SID of the Account(link takes you to an external page) to which the Sim resource should belong. The Account SID can only be that of the requesting Account or that of a Subaccount(link takes you to an external page) of the requesting Account. Only valid when the Sim resource's status is new. For more information, see the Move SIMs between Subaccounts documentation(link takes you to an external page).

Update a Sim, providing a callback URL and callback method

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_14
// Download the helper library from https://www.twilio.com/docs/node/install
_14
// Find your Account SID and Auth Token at twilio.com/console
_14
// and set the environment variables. See http://twil.io/secure
_14
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_14
const authToken = process.env.TWILIO_AUTH_TOKEN;
_14
const client = require('twilio')(accountSid, authToken);
_14
_14
client.wireless.v1.sims('DEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_14
.update({
_14
callbackMethod: 'POST',
_14
callbackUrl: 'https://sim-manager.mycompany.com/sim-update-callback/AliceSmithSmartMeter',
_14
status: 'active'
_14
})
_14
.then(sim => console.log(sim.uniqueName));

Output

_30
{
_30
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_30
"unique_name": "unique_name",
_30
"commands_callback_method": "POST",
_30
"commands_callback_url": "http://www.example.com",
_30
"date_created": "2015-07-30T20:00:00Z",
_30
"date_updated": "2015-07-30T20:00:00Z",
_30
"friendly_name": "friendly_name",
_30
"links": {
_30
"data_sessions": "https://wireless.twilio.com/v1/Sims/DEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/DataSessions",
_30
"rate_plan": "https://wireless.twilio.com/v1/RatePlans/WPXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_30
"usage_records": "https://wireless.twilio.com/v1/Sims/DEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/UsageRecords"
_30
},
_30
"rate_plan_sid": "WPXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_30
"sid": "DEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_30
"iccid": "iccid",
_30
"e_id": "e_id",
_30
"status": "active",
_30
"reset_status": null,
_30
"sms_fallback_method": "POST",
_30
"sms_fallback_url": "http://www.example.com",
_30
"sms_method": "POST",
_30
"sms_url": "http://www.example.com",
_30
"voice_fallback_method": "POST",
_30
"voice_fallback_url": "http://www.example.com",
_30
"voice_method": "POST",
_30
"voice_url": "http://www.example.com",
_30
"url": "https://wireless.twilio.com/v1/Sims/DEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_30
"ip_address": "192.168.1.30"
_30
}

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

ParameterDescription
SimSidThe SID of the SIM that this callback is in reference to.
SimUniqueNameThe SIM's UniqueName, if it has one.
SimStatusAn updated string representing the new status of the SIM.
ErrorCodeIf an error occurred, an error code is provided.
ErrorMessageIf an error occurred, an error message is provided.
ApiVersionThe version of the API that your initial request was made to.
AccountSidThe unique SID 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.

Move SIMs between Subaccounts

move-sims-between-subaccounts page anchor

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

While using the master account's credentials, use the AccountSid parameter to provide the Account SID of the account you wish to own that SIM. 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.
(warning)

Warning

If the SIM you are moving is assigned to a Rate Plan, you must also pass the SID or unique name of a Rate Plan that belongs to the new account, or null, in the RatePlan parameter of your Update request.

Reset a SIM's connectivity

reset-a-sims-connectivity page anchor

You can force your SIM to detach from the cellular network and reconnect by updating the Sim resource's ResetStatus to resetting.

Once the reset request is accepted by our downstream provider, the ResetStatus will return to null. You cannot issue another reset request while the ResetStatus is resetting.


DELETE https://wireless.twilio.com/v1/Sims/{Sid}

Deleting a Sim resource causes the referenced SIM to be removed from your account and placed in the terminal Canceled state, i.e., it will no longer function.

The {Sid} parameter can be the SID or the UniqueName of the Sim resource to be deleted.

URI parameters
Sidtype: stringNot PII
Path Parameter

The SID or the unique_name of the Sim resource to delete.

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_10
// Download the helper library from https://www.twilio.com/docs/node/install
_10
// Find your Account SID and Auth Token at twilio.com/console
_10
// and set the environment variables. See http://twil.io/secure
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.wireless.v1.sims('DEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX').remove();


View SIM lifecycle events

view-sim-lifecycle-events page anchor

A SIM's lifecycle events 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:


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


Rate this page: