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

​
Status

​
User-Controlled

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

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

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