Wireless Sim Resource

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

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.

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

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.

Sim properties

Resource Properties in REST API format
`sid`	sid<DE> Not PII The unique string that we created to identify the Sim resource.
`unique_name`	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.
`account_sid`	sid<AC> Not PII The SID of the Account to which the Sim resource belongs.
`rate_plan_sid`	sid<WP> Not PII The SID of the RatePlan resource to which the Sim resource is assigned.
`friendly_name`	string PII MTL: 30 DAYS The string that you assigned to describe the Sim resource.
`iccid`	string PII MTL: 30 DAYS The ICCID associated with the SIM.
`e_id`	string Not PII Deprecated.
`status`	enum:status Not PII The status of the Sim resource. Can be: `new`, `ready`, `active`, `deactivated`, `canceled`, `deleted`, `scheduled`, or `updating`. See Status Values for the description of each status.
`reset_status`	enum:reset_status 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.
`commands_callback_url`	url Not PII The URL we call using the `commands_callback_method` when the 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.
`commands_callback_method`	http_method Not PII The HTTP method we use to call `commands_callback_url`. Can be: `POST` or `GET`. Default is `POST`.
`sms_fallback_method`	http_method Not PII Deprecated.
`sms_fallback_url`	url Not PII Deprecated.
`sms_method`	http_method Not PII Deprecated.
`sms_url`	url Not PII Deprecated.
`voice_fallback_method`	http_method Not PII Deprecated. The HTTP method we use to call `voice_fallback_url`. Can be: `GET` or `POST`. Default is `POST`.
`voice_fallback_url`	url 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_method`	http_method Not PII Deprecated. The HTTP method we use to call `voice_url`. Can be: `GET` or `POST`. Default is `POST`.
`voice_url`	url Not PII Deprecated. The URL we call using the `voice_method` when the SIM-connected device makes a voice call.
`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 Sim resource was last updated specified in ISO 8601 format.
`url`	url Not PII The absolute URL of the resource.
`links`	uri_map Not PII The URLs of related subresources.
`ip_address`	string Not PII Deprecated.

Status Values

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

Status	Description
`new`	The 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`.
`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 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.
`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 Suspended SIM Fees in Programmable Wireless Pricing for more details.
`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, if it has been lost or stolen.
`canceled`	Terminal status. The SIM is blocked from connecting to the network and can never be reactivated.
`scheduled`	The 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.
`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.

Fetch a Sim resource

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

Parameters in REST API format
`sid` Path	get sid_like<DE> Not PII The SID or the `unique_name` of the Sim resource to fetch.

Parameters in REST API format

sid

Path

get sid_like<DE> Not PII

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

Example 1

Loading Code Sample...

Example JSON response

Fetch a Sim resource identified by its SID

Fetch a Sim resource

Fetch a Sim resource identified by its SID

Example 2

Loading Code Sample...

Example JSON response

Fetch a Sim resource identified by its UniqueName

Fetch a Sim by its UniqueName

Fetch a Sim resource identified by its UniqueName

Read multiple Sim resources

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.

Parameters

Parameters in REST API format
`status` Optional	get enum:status Not PII Only return Sim resources with this status.
`iccid` Optional	get string PII MTL: 30 DAYS Only return Sim resources with this ICCID. This will return a list with a maximum size of 1.
`rate_plan` Optional	get string Not PII The SID or unique name of a RatePlan resource. Only return Sim resources assigned to this RatePlan resource.
`e_id` Optional	get string Not PII Deprecated.
`sim_registration_code` Optional	get string Not PII Only return Sim resources with this registration code. This will return a list with a maximum size of 1.

Example 1

Loading Code Sample...

Example JSON response

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

Read multiple Sim resources

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

Update a Sim resource

post

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

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

Parameters

Parameters in REST API format
`sid` Path	post sid_like<DE> Not PII The SID or the `unique_name` 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 `sid` in the URL path to address the resource.
`callback_method` Optional	post http_method Not PII The HTTP method we should use to call `callback_url`. Can be: `POST` or `GET`. The default is `POST`.
`callback_url` Optional	post url 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`).
`friendly_name` Optional	post string PII MTL: 30 DAYS A descriptive string that you create to describe the Sim resource. It does not need to be unique.
`rate_plan` Optional	post sid_like<WP> Not PII The SID or unique name of the RatePlan resource to which the Sim resource should be assigned.
`status` Optional	post enum:status Not PII The new status of the Sim resource. Can be: `ready`, `active`, `suspended`, or `deactivated`.
`commands_callback_method` Optional	post http_method Not PII The HTTP method we should use to call `commands_callback_url`. Can be: `POST` or `GET`. The default is `POST`.
`commands_callback_url` Optional	post url Not PII The URL we should call using the `commands_callback_method` when the SIM sends a Command. Your server should respond with an HTTP status code in the 200 range; any response body is ignored.
`sms_fallback_method` Optional	post http_method Not PII The HTTP method we should use to call `sms_fallback_url`. Can be: `GET` or `POST`. Default is `POST`.
`sms_fallback_url` Optional	post url 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`.
`sms_method` Optional	post http_method Not PII The HTTP method we should use to call `sms_url`. Can be: `GET` or `POST`. Default is `POST`.
`sms_url` Optional	post url 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.
`voice_fallback_method` Optional	post http_method Not PII Deprecated.
`voice_fallback_url` Optional	post url Not PII Deprecated.
`voice_method` Optional	post http_method Not PII Deprecated.
`voice_url` Optional	post url Not PII Deprecated.
`reset_status` Optional	post ienum:reset_status 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.
`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`. For more information, see the Move SIMs between Subaccounts documentation.

Example 1

Loading Code Sample...

Example JSON response

Update a Sim, providing a callback URL and callback method

Update a Sim resource

Update a Sim, providing a callback URL and callback method

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 SID of 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 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

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.

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

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 the our downstream provider, the ResetStatus will return to null. You cannot issue another reset request while the ResetStatus is resetting.

Delete a Sim resource

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.

Parameters

Parameters in REST API format
`sid` Path	delete sid_like<DE> Not PII The SID or the `unique_name` of the Sim resource to delete.

Parameters in REST API format

sid

Path

delete sid_like<DE> Not PII

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

Example 1

Loading Code Sample...

Example JSON response

Delete a Sim resource

View SIM lifecycle events

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:

"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 by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.

Parameters

Example 1

Fetch a Sim resource

Example 2

Fetch a Sim by its UniqueName

Parameters

Example 1

Read multiple Sim resources

Parameters

Example 1

Update a Sim resource

Parameters

Example 1

Delete a Sim resource

Need some help?

Thank you for your feedback!

Thanks for your feedback!