LogoLogo
ProductsDevelopersAPI ReferenceContact Us
API Reference
API Reference
  • Overview
  • Products
    • Super SIM
      • Sim Resource
        • Sim BillingPeriod subresource
      • ESimProfile Resource
      • Fleet Resource
      • NetworkAccessProfile Resource
        • NetworkAccessProfile Network Subresource
      • Network Resource
      • SettingsUpdates Resource
      • Usage Record Resource
      • SMSCommand Resource
      • IPCommand Resource
    • Programmable Wireless
      • Account UsageRecord Resource
      • Command Resource
      • DataSession Resource
      • RatePlan Resource
      • Wireless Sim Resource
      • Sim UsageRecord Resource
  • Global Resources
    • API Clients
      • Ping
      • Clients
    • Identity and Access Management
      • Account
    • Webhook
On this page

Was this helpful?

  1. Products
  2. Programmable Wireless

Wireless Sim Resource

PreviousRatePlan ResourceNextSim UsageRecord Resource

Last updated 5 months ago

Was this helpful?

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 before it can become active. The Rate Plan describes the capabilities and restrictions that apply to the SIM.


Asynchronous resources

The Sim resource operates . 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<DE>

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<AC>

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<WP>

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


e_id string

Deprecated.


status enum<string>

Possible values:

new

ready

active

suspended

deactivated

canceled

scheduled

updating


reset_status enum<string>

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<uri>


commands_callback_method enum<http-method>

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<http-method>

Deprecated.

Possible values:

GET

POST


sms_fallback_url string<uri>

Deprecated.


sms_method enum<http-method>

Deprecated.


sms_url string<uri>

Deprecated.


voice_fallback_method enum<http-method>

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


voice_fallback_url string<uri>

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<http-method>

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


voice_url string<uri>

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


date_created string<date-time>


date_updated string<date-time>


url string<uri>

The absolute URL of the resource.


links object<uri-map>

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

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


Fetch a Sim resource


Read multiple Sim resources

Update a Sim resource

Callback values

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


Delete a Sim resource

View SIM lifecycle events

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"
    }
  }
}

The SID of the to which the Sim resource is assigned.

The associated with the SIM.

The status of the Sim resource. Can be: new, ready, active, deactivated, canceled, deleted, scheduled, or updating. See for the description of each status.

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

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

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

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 for more details.

The SIM is in the process of being . While the Sim is updating, it may not be possible to modify some fields. In these cases, you will receive a 409 Conflict response.

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

A SIM's lifecycle events are audited and reported by . An update to a Sim resource results in a Monitor Event with an Event Type of wireless-sim.updated.

RatePlan resource
ICCID
Command
ISO 8601
ISO 8601
Monitor Events
Rate Plan
asynchronously
Status Values
asynchronous request
Programmable Wireless Pricing
asynchronously updated

Get a Sim

get
Authorizations
Path parameters
SidstringRequired

The SID of the RatePlan resource to fetch.

Responses
200
Get Sim
application/json
400
Invalid request
application/json
401
Credentials were not provided and are required to access this resource
application/json
403
Credentials were not provided and are required to access this resource
application/json
404
Resource not found
application/json
415
Credentials were not provided and are required to access this resource
application/json
422
Resource not found
application/json
500
Internal Server Error
application/json
503
Server is temporary not available
application/json
get
curl --location --globoff 'https://programmable-wireless.api.korewireless.com/v1/Sims/<string>' \
--header 'Authorization: Bearer <YOUR_AUTH_TOKEN>'
{
  "sid": "text",
  "unique_name": "text",
  "friendly_name": "text",
  "account_sid": "text",
  "status": "deactivated",
  "rate_plan_sid": "text",
  "iccid": "text",
  "eid": "text",
  "commands_callback_url": "https://example.com",
  "commands_callback_method": "GET",
  "date_created": "2025-05-20T05:57:46.919Z",
  "date_updated": "2025-05-20T05:57:46.919Z",
  "ip_address": "text",
  "reset_status": "resetting",
  "links": {
    "rate_plan": "text",
    "usage_records": "text",
    "data_sessions": "text"
  },
  "url": "https://example.com",
  "voice_url": "https://example.com",
  "voice_method": "GET",
  "voice_fallback_url": "https://example.com",
  "voice_fallback_method": "GET",
  "sms_url": "https://example.com",
  "sms_method": "GET",
  "sms_fallback_url": "https://example.com",
  "sms_fallback_method": "GET"
}

List Sims

get
Authorizations
Query parameters
Statusstring · enumOptional

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

Possible values:
IccidstringOptional

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

Example: {"value":"iccid"}
RatePlanstringOptional

The SID or unique name of a RatePlan resource. Only return Sim resources assigned to this RatePlan resource.

Example: {"value":"rate_plan"}
EIdstringOptional

Deprecated.

SimRegistrationCodestringOptional

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

PageSizeinteger · min: 1 · max: 1000Optional

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

PageintegerOptional

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

PageTokenstringOptional

The page token. This is provided by the API.

Responses
200
Data Usage List
application/json
400
Invalid request
application/json
401
Credentials were not provided and are required to access this resource
application/json
403
Credentials were not provided and are required to access this resource
application/json
404
Resource not found
application/json
415
Credentials were not provided and are required to access this resource
application/json
422
Resource not found
application/json
500
Internal Server Error
application/json
503
Server is temporary not available
application/json
get
curl --location --globoff 'https://programmable-wireless.api.korewireless.com/v1/Sims?Status=<string>&Iccid=<string>&RatePlan=<string>&EId=<string>&SimRegistrationCode=<string>&PageSize=<integer>&Page=<integer>&PageToken=<string>' \
--header 'Authorization: Bearer <YOUR_AUTH_TOKEN>'
{
  "sims": [
    {
      "sid": "text",
      "unique_name": "text",
      "friendly_name": "text",
      "account_sid": "text",
      "status": "deactivated",
      "rate_plan_sid": "text",
      "iccid": "text",
      "eid": "text",
      "commands_callback_url": "https://example.com",
      "commands_callback_method": "GET",
      "date_created": "2025-05-20T05:57:46.919Z",
      "date_updated": "2025-05-20T05:57:46.919Z",
      "ip_address": "text",
      "reset_status": "resetting",
      "links": {
        "rate_plan": "text",
        "usage_records": "text",
        "data_sessions": "text"
      },
      "url": "https://example.com",
      "voice_url": "https://example.com",
      "voice_method": "GET",
      "voice_fallback_url": "https://example.com",
      "voice_fallback_method": "GET",
      "sms_url": "https://example.com",
      "sms_method": "GET",
      "sms_fallback_url": "https://example.com",
      "sms_fallback_method": "GET"
    }
  ],
  "meta": {
    "first_page_url": "https://example.com",
    "key": "text",
    "next_page_url": "https://example.com",
    "page": 1,
    "page_size": 1,
    "previous_page_url": "https://example.com",
    "url": "https://example.com"
  }
}

Update A Sim

post
Authorizations
Path parameters
SidstringRequired

The SID of the RatePlan resource to fetch.

Body
UniqueNamestringOptional

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.

CallbackMethodstring · enumOptional

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

Possible values:
CallbackUrlstring · uriOptional

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

FriendlyNamestringOptional

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

RatePlanstringOptional

The SID or unique name of the RatePlan resource to which the Sim resource should be assigned.

Statusstring · enumOptional

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

Possible values:
CommandsCallbackMethodstring · enumOptional

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

Possible values:
CommandsCallbackUrlstring · uriOptional

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.

SmsFallbackMethodstring · enumOptional

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

Possible values:
SmsFallbackUrlstring · uriOptional

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

SmsMethodstring · enumOptional

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

Possible values:
SmsUrlstring · uriOptional

The URL we should call using the sms_method when the SIM-connected device sends an SMS message that is not a Command.

VoiceFallbackMethodstring · enumOptional

Deprecated.

Possible values:
VoiceFallbackUrlstring · uriOptional

Deprecated.

VoiceMethodstring · enumOptional

Deprecated.

Possible values:
VoiceUrlstring · uriOptional

Deprecated.

ResetStatusstring · enumOptional

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:
AccountSidstringOptional

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.

Responses
200
Data Usage Update
application/json
400
Invalid request
application/json
401
Credentials were not provided and are required to access this resource
application/json
403
Credentials were not provided and are required to access this resource
application/json
404
Resource not found
application/json
415
Credentials were not provided and are required to access this resource
application/json
422
Resource not found
application/json
500
Internal Server Error
application/json
503
Server is temporary not available
application/json
post
curl --location --globoff 'https://programmable-wireless.api.korewireless.com/v1/Sims/<string>' \
--header 'Authorization: Bearer <YOUR_AUTH_TOKEN>'
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Accept: application/json' \
--data-urlencode 'UniqueName=<string>' \
--data-urlencode 'CallbackMethod=<http-method>' \
--data-urlencode 'CallbackUrl=<uri>' \
--data-urlencode 'FriendlyName=<string>' \
--data-urlencode 'RatePlan=<string>' \
--data-urlencode 'Status=<string>' \
--data-urlencode 'CommandsCallbackMethod=<http-method>' \
--data-urlencode 'CommandsCallbackUrl=<uri>' \
--data-urlencode 'SmsFallbackMethod=<http-method>' \
--data-urlencode 'SmsFallbackUrl=<uri>' \
--data-urlencode 'SmsMethod=<http-method>' \
--data-urlencode 'SmsUrl=<uri>' \
--data-urlencode 'VoiceFallbackMethod=<http-method>' \
--data-urlencode 'VoiceFallbackUrl=<uri>' \
--data-urlencode 'VoiceMethod=<http-method>' \
--data-urlencode 'VoiceUrl=<uri>' \
--data-urlencode 'ResetStatus=<string>' \
--data-urlencode 'AccountSid=<string>'
{
  "sid": "text",
  "unique_name": "text",
  "friendly_name": "text",
  "account_sid": "text",
  "status": "deactivated",
  "rate_plan_sid": "text",
  "iccid": "text",
  "eid": "text",
  "commands_callback_url": "https://example.com",
  "commands_callback_method": "GET",
  "date_created": "2025-05-20T05:57:46.919Z",
  "date_updated": "2025-05-20T05:57:46.919Z",
  "ip_address": "text",
  "reset_status": "resetting",
  "links": {
    "rate_plan": "text",
    "usage_records": "text",
    "data_sessions": "text"
  },
  "url": "https://example.com",
  "voice_url": "https://example.com",
  "voice_method": "GET",
  "voice_fallback_url": "https://example.com",
  "voice_fallback_method": "GET",
  "sms_url": "https://example.com",
  "sms_method": "GET",
  "sms_fallback_url": "https://example.com",
  "sms_fallback_method": "GET"
}

Delete a Sim

delete
Authorizations
Path parameters
SidstringRequired

The SID of the RatePlan resource to fetch.

Responses
204
The resource was deleted successfully.
400
Invalid request
application/json
401
Credentials were not provided and are required to access this resource
application/json
403
Credentials were not provided and are required to access this resource
application/json
404
Resource not found
application/json
409
Resource not found
application/json
500
Internal Server Error
application/json
503
Server is temporary not available
application/json
delete
curl --location --globoff --request DELETE 'https://programmable-wireless.api.korewireless.com/v1/Sims/<string>' \
--header 'Authorization: Bearer <YOUR_AUTH_TOKEN>'

No content

  • Asynchronous resources
  • Sim Properties
  • Status Values
  • Fetch a Sim resource
  • GETGet a Sim
  • Read multiple Sim resources
  • GETList Sims
  • Update a Sim resource
  • POSTUpdate A Sim
  • Callback values
  • Move SIMs between Subaccounts
  • Reset a SIM's connectivity
  • Delete a Sim resource
  • DELETEDelete a Sim
  • View SIM lifecycle events