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.
