# Wireless Sim Resource
A Sim resource represents a physical SIM that can connect to a wireless network.
{% hint style="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.
{% endhint %}
{% hint style="warning" %}
A Sim resource must have a [Rate Plan](https://docs.korewireless.com/en-us/api/products/programmable-wireless/rateplan-resource) before it can become active. The Rate Plan describes the capabilities and restrictions that apply to the SIM.
{% endhint %}
***
## Asynchronous resources
The Sim resource operates [asynchronously](#asynchronous-resources). 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
**sid** SID\
The unique string that we created to identify the Sim resource.
Pattern:`^DE[0-9a-fA-F]{32}$`
Min length:`34`
Max length:`34`
***
**unique\_name** string
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\
The SID of the Account to which the Sim resource belongs.
Pattern:`^AC[0-9a-fA-F]{32}$`
Min length:`34`
Max length:`34`
***
**rate\_plan\_sid** SID\
The SID of the [RatePlan resource](https://docs.korewireless.com/en-us/api/products/programmable-wireless/rateplan-resource) to which the Sim resource is assigned.
Pattern:`^WP[0-9a-fA-F]{32}$`
Min length:`34`
Max length:`34`
***
**friendly\_name** string
The string that you assigned to describe the Sim resource.
***
**iccid** string
The [ICCID](https://en.wikipedia.org/wiki/SIM_card#ICCID) associated with the SIM.
***
**e\_id** string
Deprecated.
***
**status** enum\
The status of the Sim resource. Can be: `new`, `ready`, `active`, `deactivated`, `canceled`, `deleted`, `scheduled`, or `updating`. See [Status Values](#status-values) for the description of each status.
Possible values:
`new`
`ready`
`active`
`suspended`
`deactivated`
`canceled`
`scheduled`
`updating`
***
**reset\_status** enum\
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\_url** string\
The URL we call using the `commands_callback_method` when the SIM originates a machine-to-machine [Command](https://docs.korewireless.com/en-us/api/products/programmable-wireless/command-resource). Your server should respond with an HTTP status code in the 200 range; any response body will be ignored.
***
**commands\_callback\_method** enum\
The HTTP method we use to call `commands_callback_url`. Can be: `POST` or `GET`. Default is `POST`.
Possible values:
`GET`
`POST`
***
**sms\_fallback\_method** enum\
Deprecated.
Possible values:
`GET`
`POST`
***
**sms\_fallback\_url** string\
Deprecated.
***
**sms\_method** enum\
Deprecated.
***
**sms\_url** string\
Deprecated.
***
**voice\_fallback\_method** enum\
Deprecated. The HTTP method we use to call `voice_fallback_url`. Can be: `GET` or `POST`. Default is `POST`.
***
**voice\_fallback\_url** string\
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** enum\
Deprecated. The HTTP method we use to call `voice_url`. Can be: `GET` or `POST`. Default is `POST`.
***
**voice\_url** string\
Deprecated. The URL we call using the `voice_method` when the SIM-connected device makes a voice call.
***
**date\_created** string\
The date and time in GMT when the resource was created specified in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format.
***
**date\_updated** string\
The date and time in GMT when the Sim resource was last updated specified in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format.
***
**url** string\
The absolute URL of the resource.
***
**links** object\
The URLs of related subresources.
***
**ip\_address** string
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 status 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](https://docs.korewireless.com/en-us/programmable-wireless/help-and-support/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](#asynchronous-resources). 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
{% openapi src="" path="/v1/Sims/{Sid}" method="get" %}
[openapi3\_0 (alf).yaml](https://3487028960-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJknMM6SZJYk9EbbitKp5%2Fuploads%2F4alsAWeuMtriesOfOixr%2Fopenapi3_0%20\(alf\).yaml?alt=media\&token=8a6481d4-a087-4460-b7cd-9e4a4d0e6341)
{% endopenapi %}
***
## Read multiple Sim resources
{% openapi src="" path="/v1/Sims" method="get" %}
[openapi3\_0 (alf).yaml](https://3487028960-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJknMM6SZJYk9EbbitKp5%2Fuploads%2F4alsAWeuMtriesOfOixr%2Fopenapi3_0%20\(alf\).yaml?alt=media\&token=8a6481d4-a087-4460-b7cd-9e4a4d0e6341)
{% endopenapi %}
## Update a Sim resource
{% openapi src="" path="/v1/Sims/{Sid}" method="post" %}
[openapi3\_0 (alf).yaml](https://3487028960-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJknMM6SZJYk9EbbitKp5%2Fuploads%2F4alsAWeuMtriesOfOixr%2Fopenapi3_0%20\(alf\).yaml?alt=media\&token=8a6481d4-a087-4460-b7cd-9e4a4d0e6341)
{% endopenapi %}
### **Callback values**
If a callback URL is present in your request, the [asynchronous request](#asynchronous-resources) 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.
{% hint style="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.
{% endhint %}
### 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 our downstream provider, the `ResetStatus` will return to `null`. You cannot issue another reset request while the `ResetStatus` is `resetting`.
***
## Delete a Sim resource
{% openapi src="" path="/v1/Sims/{Sid}" method="delete" %}
[openapi3\_0 (alf).yaml](https://3487028960-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJknMM6SZJYk9EbbitKp5%2Fuploads%2F4alsAWeuMtriesOfOixr%2Fopenapi3_0%20\(alf\).yaml?alt=media\&token=8a6481d4-a087-4460-b7cd-9e4a4d0e6341)
{% endopenapi %}
\
View SIM lifecycle events
------------------------------------------------------------------------------------------
A SIM's lifecycle events are audited and reported by [Monitor Events](https://docs.korewireless.com/en-us/developers/get-started/event-streams). 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:
```json
"event_data": {
"resource_properties": {
"rate_plan_sid": {
"previous": "WP0195dea2f0b1e00dbc54d0715e36e2db",
"updated": "WP3b921b4711ee21ac01c7075a7eb19fcf"
},
"status": {
"previous": "new",
"updated": "active"
}
}
}
```