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://developers.telnyx.com/development/llms/wireless-sims-esims-llms-txt.md

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 →

SIM Cards

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

Getting SIMs

Physical SIMs

Physical SIM orders go through Mission Control — you can’t order them via API.

Order — Set quantity, add to cart, and check out. Telnyx ships triple-cut SIM cards (2FF/3FF/4FF) to your address.
Register — Each physical SIM has a 10-digit registration code printed on the card. Register via the portal (Register SIM Cards tab, manual or CSV) or the API (POST /actions/register/sim_cards). During registration you assign a SIM Card Group and optional tags.
Enable — Once registered, activate the SIM on the network via POST /sim_cards/{id}/actions/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. Purchase through Mission Control 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. 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 for state management (enable, disable, standby, delete) and 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. 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}` (group level) or `PATCH /sim_cards/{id}` (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}` to add the current IMEI or clear the list. Then re-enable with `POST /sim_cards/{id}/actions/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 — from `registered`, `disabled`, or `standby`
`disabled`	Disable SIM — from `enabled`
`standby`	Set Standby — from `enabled`
`data_limit_exceeded`	System — SIM exceeded its group or SIM-level data limit. Adjust via Update Group or Update SIM.
`unauthorized_imei`	System — SIM inserted into a device not in its `authorized_imeis` list. Fix via Update SIM.
`blocked` / `abolished`	System — account-level billing interruption. Resolve with Telnyx support.

Deletion

DELETE /sim_cards/{id} 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

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

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.

Action
Assign Private Wireless Gateway
Remove Private Wireless Gateway
Assign Wireless Blocklist
Remove Wireless Blocklist

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.

Bulk Actions

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

Action
Bulk Enable Voice
Bulk Disable Voice
Bulk Set Public IPs
Validate Registration Codes

Track progress via 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: Get all SIM cards belonging to the user that match the given filters.
Get SIM card: Returns the details regarding a specific SIM card.
Update a SIM card: Updates SIM card data
Deletes a SIM card: The SIM card will be decommissioned, removed from your account and you will stop being charged. The SIM card won’t be able to connect to the network after…
Register SIM cards: Register the SIM cards associated with the provided registration codes to the current user’s account.
Purchase eSIMs: Purchases and registers the specified amount of eSIMs to the current user’s account.
Request a SIM card enable: This API enables a SIM card, connecting it to the network and making it possible to consume data.
Request a SIM card disable: This API disables a SIM card, disconnecting it from the network and making it impossible to consume data.
Request setting a SIM card to standby: 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.
Request bulk disabling voice on SIM cards.: This API triggers an asynchronous operation to disable voice on SIM cards belonging to a specified SIM Card Group.
Request bulk enabling voice on SIM cards.: This API triggers an asynchronous operation to enable voice on SIM cards belonging to a specified SIM Card Group.
Request bulk setting SIM card public IPs.: This API triggers an asynchronous operation to set a public IP for each of the specified SIM cards.
Validate SIM cards registration codes: It validates whether SIM card registration codes are valid or not.

SIM Card Orders

Get all SIM card orders: Get all SIM card orders according to filters.
Create a SIM card order: Creates a new order for SIM cards.
Get a single SIM card order: Get a single SIM card order by its ID.
Preview SIM card orders: Preview SIM card order purchases.

SIM Card Actions

List SIM card actions: 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: This API fetches detailed information about a SIM card action to follow-up on an existing asynchronous operation.
List bulk SIM card actions: 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: 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: Get all SIM card groups belonging to the user that match the given filters.
Create a SIM card group: Creates a new SIM card group object
Get SIM card group: Returns the details regarding a specific SIM card group
Update a SIM card group: Updates a SIM card group
Delete a SIM card group: Permanently deletes a SIM card group
Request Private Wireless Gateway removal from SIM card group: 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: 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: 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: 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: 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: This API allows fetching detailed information about a SIM card group action resource to make follow-ups in an existing asynchronous operation.

​Telnyx Wireless: SIMs & eSIMs — Full Documentation

​Overview

​Overview

​SIM Types

​Resource Model

​SIM Lifecycle

​Multi-IMSI

​Pricing

​SIM Cards

​SIM Cards

​Getting SIMs

​Physical SIMs

​eSIMs

​Next Steps

​Lifecycle

​Status

​User-Controlled

​Transitional

​System-Imposed

​What Puts a SIM Into Each Status

​Deletion

​SIM Card Groups

​SIM Card Groups

​Default Group

​Group Settings

​Group Actions

​Bulk Operations

​Bulk Operations

​Bulk Actions

​API Reference (SIMs & eSIMs)

​SIM Cards

​SIM Card Orders

​SIM Card Actions

​SIM Card Groups

​SIM Card Group Actions

Telnyx Wireless: SIMs & eSIMs — Full Documentation

Overview

Overview

SIM Types

Resource Model

SIM Lifecycle

Multi-IMSI

Pricing

SIM Cards

SIM Cards

Getting SIMs

Physical SIMs

eSIMs

Next Steps

Lifecycle

Status

User-Controlled

Transitional

System-Imposed

What Puts a SIM Into Each Status

Deletion

SIM Card Groups

SIM Card Groups

Default Group

Group Settings

Group Actions

Bulk Operations

Bulk Operations

Bulk Actions

API Reference (SIMs & eSIMs)

SIM Cards

SIM Card Orders

SIM Card Actions

SIM Card Groups

SIM Card Group Actions