# Telnyx Wireless: SIMs & eSIMs — Full Documentation
> Complete page content for SIMs & eSIMs (Wireless section) of the Telnyx developer docs (https://developers.telnyx.com).
> Root index: https://developers.telnyx.com/llms.txt · Lightweight index for this subsection: https://telnyx-openapi-ng.s3.us-east-1.amazonaws.com/llms/wireless/sims-esims.txt

## Overview

### Overview

> Source: https://developers.telnyx.com/docs/iot-sim/get-started.md

## SIM Types

All Telnyx SIMs are eUICC-enabled. Three form factors:

| Type | Form Factor | Delivery | Use Case |
|:-----|:-----------|:---------|:---------|
| **SIM Card** | Triple-cut plastic (2FF/3FF/4FF) | Shipped | Routers, gateways, traditional devices |
| **eSIM** | Software profile | Over-the-air download | Phones, tablets, laptops — no physical SIM needed |

## Resource Model

Three core resources, all API-managed:

- **SIM Card** — the connectivity entity. Has an ICCID, status, data settings, optional voice flag. Covers both physical SIMs and eSIMs (eSIMs are purchased via a separate endpoint but become the same SIM Card resource with an activation code for OTA provisioning). Everything starts here.
- **SIM Card Group** — bulk management. Apply data limits, network preferences, and Private Wireless Gateway configs to all SIMs in a group at once.
- **Mobile Phone Number** — optional. Created when you enable voice or messaging on a SIM. Controls call forwarding, caller ID, messaging profile.

## SIM Lifecycle

```
Order → Register → `enabled` → [Active Use] → `disabled` / `standby`
```

| Status | MRC | Data | Description |
|:-------|:----|:-----|:------------|
| **Registered** | $2/mo | No | SIM exists in your account, not yet on network |
| `enabled` | $2/mo | Yes | Active on network, consuming data |
| `disabled` | $0.20/mo | No | Off network, reduced cost, retains config |
| `standby` | $0.20/mo | No | Same as disabled, ready for quick re-enable |

## Multi-IMSI

Every Telnyx SIM carries multiple IMSIs (Telnyx, Sparkle, BICs, T-Mobile, US Cellular). An on-SIM applet automatically selects the best IMSI per location — local network attachment instead of roaming, lower latency, better rates.

Default is automatic selection. You can override to manual per-SIM or per-group via API if you need to pin a specific IMSI for regulatory or testing purposes.

## Pricing

Three cost components:

| Component | Cost |
|:----------|:-----|
| **SIM purchase** | $1/SIM, $0.70/eSIM. $10 shipping outside US mainland. |
| **Monthly** | $2/active SIM, $0.20/disabled or standby |
| **Data** | Tiered by zone and volume. [Full breakdown →](https://support.telnyx.com/en/articles/3296669-programmable-wireless-pricing) |

---

## SIM Cards

### SIM Cards

> Source: https://developers.telnyx.com/docs/iot-sim/ordering-sims.md

## Getting SIMs

### Physical SIMs

Physical SIM orders go through [Mission Control](https://portal.telnyx.com/#/wireless/buy-sim-cards) — you can't order them via API.

1. **Order** — Set quantity, add to cart, and check out. Telnyx ships triple-cut SIM cards (2FF/3FF/4FF) to your address.
2. **Register** — Each physical SIM has a 10-digit registration code printed on the card. Register via the portal ([Register SIM Cards](https://portal.telnyx.com/#/wireless/buy-sim-cards) tab, manual or CSV) or the API ([`POST /actions/register/sim_cards`](/api-reference/sim-cards/register-sim-cards)). During registration you assign a SIM Card Group and optional tags.
3. **Enable** — Once registered, activate the SIM on the network via [`POST /sim_cards/{id}/actions/enable`](/api-reference/sim-cards/request-a-sim-card-enable) or the portal.

After registration, the SIM appears as a standard SIM Card resource. All further management is via the API.

### eSIMs

eSIMs are downloadable SIM profiles for consumer devices (phones, tablets, laptops) — not embedded SIM hardware. For eUICC hardware solutions, contact [Sales](https://telnyx.com/contact-us).

Purchase through [Mission Control](https://portal.telnyx.com/#/wireless/buy-esims) or the API (`POST /actions/purchase_esims`):

- **Portal** — Set quantity, assign a SIM Card Group, choose initial status, add tags. $0.70 activation fee per eSIM. No cart — purchase is immediate.
- **API** — [`POST /actions/purchase/esims`](/api-reference/sim-cards/purchase-esims). Same parameters, same instant provisioning.

Either way, you get an activation code immediately. Provide it to the device via QR code or direct input for OTA provisioning. No shipping, no registration step.

eSIM activation codes are one-time use. If the device loses the profile, you need a new eSIM purchase — you can't re-download the same profile.

After provisioning, eSIMs become the same SIM Card resource as physical SIMs. All API operations are identical.

## Next Steps

Once you have SIMs in your account, see [Lifecycle](/docs/iot-sim/sim-lifecycle) for state management (enable, disable, standby, delete) and [SIM Card Groups](/docs/iot-sim/sim-card-groups) for fleet configuration.

---

### Lifecycle

> Source: https://developers.telnyx.com/docs/iot-sim/sim-lifecycle.md

Every SIM follows the same state machine regardless of type (physical or eSIM).

## Status

### User-Controlled

| Status | On Network | Passes Traffic | Notes |
|:-------|:-----------|:---------------|:------|
| `enabled` | Yes | Yes | Active on the network. |
| `disabled` | No | No | Off the network. IP released. $0.20/mo holding fee. |
| `standby` | No | No | Off the network. IP preserved. $0.20/mo. |

**`disabled` vs `standby`** — the only difference is IP preservation. If your application depends on a stable IP (e.g., firewall allowlists, IoT platforms that register by IP), use `standby`. Otherwise `disabled` is fine.

### Transitional

All transitions are asynchronous. While in progress, the SIM reports a transitional status.

| Status | Target |
|:-------|:-------|
| `registering` | → `enabled` (initial setup) |
| `enabling` | → `enabled` |
| `disabling` | → `disabled` |
| `setting_standby` | → `standby` |

Track progress via [SIM Card Actions](/api-reference/sim-card-actions/list-sim-card-actions).

All state changes return `202` with a SIM Card Action — they are not instant. Poll the action status or list actions to confirm completion.

### System-Imposed

Set by Telnyx, not by API calls. The SIM cannot transition while in these states.

| Status | Meaning | How to Exit |
|:-------|:--------|:------------|
| `data_limit_exceeded` | SIM exceeded its group's data limit. | Raise the data limit via [`PATCH /sim_card_groups/{id}`](/api-reference/sim-card-groups/update-a-sim-card-group) (group level) or [`PATCH /sim_cards/{id}`](/api-reference/sim-cards/update-a-sim-card) (SIM level), or wait for billing cycle reset. Auto-transitions to `intended_status`. |
| `unauthorized_imei` | SIM is in a device not on its `authorized_imeis` list. | Update `authorized_imeis` via [`PATCH /sim_cards/{id}`](/api-reference/sim-cards/update-a-sim-card) to add the current IMEI or clear the list. Then re-enable with [`POST /sim_cards/{id}/actions/enable`](/api-reference/sim-cards/request-a-sim-card-enable). |
| `blocked` | Account-level service interruption (billing). | Resolve account billing issue. Auto-syncs back to intended state. |
| `abolished` | Account-level service interruption (billing). | Resolve account billing issue. Auto-syncs back to intended state. |

## What Puts a SIM Into Each Status

The SIM must have a `sim_card_group_id` before you can enable it or set it to standby.

| Target Status | What Triggers It |
|:--------------|:-----------------|
| `enabled` | [Enable SIM](/api-reference/sim-cards/request-a-sim-card-enable) — from `registered`, `disabled`, or `standby` |
| `disabled` | [Disable SIM](/api-reference/sim-cards/request-a-sim-card-disable) — from `enabled` |
| `standby` | [Set Standby](/api-reference/sim-cards/request-setting-a-sim-card-to-standby) — from `enabled` |
| `data_limit_exceeded` | System — SIM exceeded its group or SIM-level data limit. Adjust via [Update Group](/api-reference/sim-card-groups/update-a-sim-card-group) or [Update SIM](/api-reference/sim-cards/update-a-sim-card). |
| `unauthorized_imei` | System — SIM inserted into a device not in its `authorized_imeis` list. Fix via [Update SIM](/api-reference/sim-cards/update-a-sim-card). |
| `blocked` / `abolished` | System — account-level billing interruption. Resolve with Telnyx support. |

## Deletion

[`DELETE /sim_cards/{id}`](/api-reference/sim-cards/deletes-a-sim-card) permanently deregisters the SIM. This is irreversible:

- **Physical SIMs** — the plastic is now waste. You'd need to order and register a new one.
- **eSIMs** — the profile is gone. You'd need to purchase a new eSIM.

Prefer disable or standby if there's any chance you'll need the SIM again.

For eSIMs that can't be uninstalled from a device, pass `report_lost=true` — this is irreversible and the eSIM cannot be re-registered.

---

## SIM Card Groups

### SIM Card Groups

> Source: https://developers.telnyx.com/docs/iot-sim/sim-card-groups.md

**Groups vs Bulk Operations** — Groups are ongoing policy; a SIM inherits its group's settings as long as it's a member. Bulk operations are one-time actions on an explicit list of SIMs.

Every SIM belongs to a group and inherits its settings. Set policy on the group instead of updating SIMs individually.

## Default Group

Every account has a default group. SIMs that aren't explicitly assigned land here. Deleting a group moves its SIMs back to default. Moving SIMs between groups after they're active can briefly interrupt connectivity.

## Group Settings

Configurable via [`PATCH /sim_card_groups/{id}`](/api-reference/sim-card-groups/update-a-sim-card-group):

| Setting | Description |
|:--------|:------------|
| `name` | Display name for the group. |
| `data_limit` | Data cap (`amount` + `unit`). SIMs exceeding this enter `data_limit_exceeded` until the limit is raised or the billing cycle resets. |

## Group Actions

These are async — each returns an action ID. Track progress via [`GET /sim_card_group_actions`](/api-reference/sim-card-group-actions/list-sim-card-group-actions).

| Action |
|:-------|
| [Assign Private Wireless Gateway](/api-reference/sim-card-groups/request-private-wireless-gateway-assignment-for-sim-card-group) |
| [Remove Private Wireless Gateway](/api-reference/sim-card-groups/request-private-wireless-gateway-removal-from-sim-card-group) |
| [Assign Wireless Blocklist](/api-reference/sim-card-groups/request-wireless-blocklist-assignment-for-sim-card-group) |
| [Remove Wireless Blocklist](/api-reference/sim-card-groups/request-wireless-blocklist-removal-from-sim-card-group) |

---

## Bulk Operations

### Bulk Operations

> Source: https://developers.telnyx.com/docs/iot-sim/bulk-sim-actions.md

**Bulk vs Group** — Bulk actions are one-time operations on an explicit list of SIM IDs. Nothing persists. For ongoing policy that applies to current and future SIMs, use [Groups](/docs/iot-sim/sim-card-groups/index).

## Bulk Actions

All actions are async — submit a list of SIM IDs, get back an action ID, poll for status.

| Action |
|:-------|
| [Bulk Enable Voice](/api-reference/sim-cards/request-bulk-enabling-voice-on-sim-cards) |
| [Bulk Disable Voice](/api-reference/sim-cards/request-bulk-disabling-voice-on-sim-cards) |
| [Bulk Set Public IPs](/api-reference/sim-cards/request-bulk-setting-sim-card-public-ips) |
| [Validate Registration Codes](/api-reference/sim-cards/validate-sim-cards-registration-codes) |

Track progress via [List Bulk SIM Card Actions](/api-reference/sim-card-actions/list-bulk-sim-card-actions). Per-SIM results are included — some may succeed while others fail.

For bulk registration, validate codes first with the validation endpoint. This dry-run catches typos and invalid codes before you commit to a large batch.

---

## API Reference (SIMs & eSIMs)

### SIM Cards

- [Get all SIM cards](https://developers.telnyx.com/api-reference/sim-cards/get-all-sim-cards.md): Get all SIM cards belonging to the user that match the given filters.
- [Get SIM card](https://developers.telnyx.com/api-reference/sim-cards/get-sim-card.md): Returns the details regarding a specific SIM card.
- [Update a SIM card](https://developers.telnyx.com/api-reference/sim-cards/update-a-sim-card.md): Updates SIM card data
- [Deletes a SIM card](https://developers.telnyx.com/api-reference/sim-cards/deletes-a-sim-card.md): The SIM card will be decommissioned, removed from your account and you will stop being charged.<br />The SIM card won't be able to connect to the network after…
- [Register SIM cards](https://developers.telnyx.com/api-reference/sim-cards/register-sim-cards.md): Register the SIM cards associated with the provided registration codes to the current user's account.<br/><br/>
- [Purchase eSIMs](https://developers.telnyx.com/api-reference/sim-cards/purchase-esims.md): Purchases and registers the specified amount of eSIMs to the current user's account.<br/><br/>
- [Request a SIM card enable](https://developers.telnyx.com/api-reference/sim-cards/request-a-sim-card-enable.md): This API enables a SIM card, connecting it to the network and making it possible to consume data.<br/>
- [Request a SIM card disable](https://developers.telnyx.com/api-reference/sim-cards/request-a-sim-card-disable.md): This API disables a SIM card, disconnecting it from the network and making it impossible to consume data.<br/>
- [Request setting a SIM card to standby](https://developers.telnyx.com/api-reference/sim-cards/request-setting-a-sim-card-to-standby.md): The SIM card will be able to connect to the network once the process to set it to standby has been completed, thus making it possible to consume data.<br/>
- [Request bulk disabling voice on SIM cards.](https://developers.telnyx.com/api-reference/sim-cards/request-bulk-disabling-voice-on-sim-cards.md): This API triggers an asynchronous operation to disable voice on SIM cards belonging to a specified SIM Card Group.<br/>
- [Request bulk enabling voice on SIM cards.](https://developers.telnyx.com/api-reference/sim-cards/request-bulk-enabling-voice-on-sim-cards.md): This API triggers an asynchronous operation to enable voice on SIM cards belonging to a specified SIM Card Group.<br/>
- [Request bulk setting SIM card public IPs.](https://developers.telnyx.com/api-reference/sim-cards/request-bulk-setting-sim-card-public-ips.md): This API triggers an asynchronous operation to set a public IP for each of the specified SIM cards.<br/>
- [Validate SIM cards registration codes](https://developers.telnyx.com/api-reference/sim-cards/validate-sim-cards-registration-codes.md): It validates whether SIM card registration codes are valid or not.

### SIM Card Orders

- [Get all SIM card orders](https://developers.telnyx.com/api-reference/sim-card-orders/get-all-sim-card-orders.md): Get all SIM card orders according to filters.
- [Create a SIM card order](https://developers.telnyx.com/api-reference/sim-card-orders/create-a-sim-card-order.md): Creates a new order for SIM cards.
- [Get a single SIM card order](https://developers.telnyx.com/api-reference/sim-card-orders/get-a-single-sim-card-order.md): Get a single SIM card order by its ID.
- [Preview SIM card orders](https://developers.telnyx.com/api-reference/sim-card-orders/preview-sim-card-orders.md): Preview SIM card order purchases.

### SIM Card Actions

- [List SIM card actions](https://developers.telnyx.com/api-reference/sim-card-actions/list-sim-card-actions.md): This API lists a paginated collection of SIM card actions. It enables exploring a collection of existing asynchronous operations using specific filters.
- [Get SIM card action details](https://developers.telnyx.com/api-reference/sim-card-actions/get-sim-card-action-details.md): This API fetches detailed information about a SIM card action to follow-up on an existing asynchronous operation.
- [List bulk SIM card actions](https://developers.telnyx.com/api-reference/sim-card-actions/list-bulk-sim-card-actions.md): This API lists a paginated collection of bulk SIM card actions. A bulk SIM card action contains details about a collection of individual SIM card actions.
- [Get bulk SIM card action details](https://developers.telnyx.com/api-reference/sim-card-actions/get-bulk-sim-card-action-details.md): This API fetches information about a bulk SIM card action. A bulk SIM card action contains details about a collection of individual SIM card actions.

### SIM Card Groups

- [Get all SIM card groups](https://developers.telnyx.com/api-reference/sim-card-groups/get-all-sim-card-groups.md): Get all SIM card groups belonging to the user that match the given filters.
- [Create a SIM card group](https://developers.telnyx.com/api-reference/sim-card-groups/create-a-sim-card-group.md): Creates a new SIM card group object
- [Get SIM card group](https://developers.telnyx.com/api-reference/sim-card-groups/get-sim-card-group.md): Returns the details regarding a specific SIM card group
- [Update a SIM card group](https://developers.telnyx.com/api-reference/sim-card-groups/update-a-sim-card-group.md): Updates a SIM card group
- [Delete a SIM card group](https://developers.telnyx.com/api-reference/sim-card-groups/delete-a-sim-card-group.md): Permanently deletes a SIM card group
- [Request Private Wireless Gateway removal from SIM card group](https://developers.telnyx.com/api-reference/sim-card-groups/request-private-wireless-gateway-removal-from-sim-card-group.md): This action will asynchronously remove an existing Private Wireless Gateway definition from a SIM card group. Completing this operation defines that all SIM ca…
- [Request Wireless Blocklist removal from SIM card group](https://developers.telnyx.com/api-reference/sim-card-groups/request-wireless-blocklist-removal-from-sim-card-group.md): This action will asynchronously remove an existing Wireless Blocklist to all the SIMs in the SIM card group.
- [Request Private Wireless Gateway assignment for SIM card group](https://developers.telnyx.com/api-reference/sim-card-groups/request-private-wireless-gateway-assignment-for-sim-card-group.md): This action will asynchronously assign a provisioned Private Wireless Gateway to the SIM card group. Completing this operation defines that all SIM cards in th…
- [Request Wireless Blocklist assignment for SIM card group](https://developers.telnyx.com/api-reference/sim-card-groups/request-wireless-blocklist-assignment-for-sim-card-group.md): This action will asynchronously assign a Wireless Blocklist to all the SIMs in the SIM card group.

### SIM Card Group Actions

- [List SIM card group actions](https://developers.telnyx.com/api-reference/sim-card-group-actions/list-sim-card-group-actions.md): This API allows listing a paginated collection a SIM card group actions. It allows to explore a collection of existing asynchronous operation using specific fi…
- [Get SIM card group action details](https://developers.telnyx.com/api-reference/sim-card-group-actions/get-sim-card-group-action-details.md): This API allows fetching detailed information about a SIM card group action resource to make follow-ups in an existing asynchronous operation.