> ## Documentation Index > Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt > Use this file to discover all available pages before exploring further. # Connectivity SIM model: the eSIM / IoT data-line state machine > The four states a programmable-wireless (eSIM / IoT M2M) SIM moves through — ordered, active, suspended, terminated — who advances each transition, which are reversible, how fleets and quotas behave, and how complementary line types (private gateway, prefix announcement) fit. # Connectivity SIM model A connectivity SIM is a **data-only line**: an eSIM or IoT (M2M) SIM identified by its ICCID that carries internet traffic and nothing else. It never terminates voice or SMS — outbound calls and messages always leave through your Orbit numbers, never through a cellular SIM. This page is the concept anchor for that object: the states a SIM settles into, who advances each transition, and what fleets, quotas, and OTA profiles attach to it. For step-by-step operations use the [Provision and operate eSIM / IoT SIMs guide](/guides/connectivity-sim-lifecycle); for the line-type menu across all of Numbers, start at [Numbers overview](/numbers/overview). Reads need the `numbers:read` scope; lifecycle writes need `numbers:write`. ## How a data-only SIM differs from a DID The [number status map](/concepts/number-lifecycle) anchors the lifecycle of an E.164 phone number (a DID): purchased for voice, SMS, fax, or WhatsApp. A connectivity SIM is a different object with a different closed enum: | | Phone number (DID) | Connectivity SIM | | ------------------ | ----------------------------------------------------------------------------- | ---------------------------------------------- | | **Identifier** | E.164 number | ICCID (19 digits) | | **Carries** | Voice, SMS, fax, WhatsApp | Internet data only | | **States** | `active`, `pending_compliance`, `inactive`, `released`, `parked`, `suspended` | `ordered`, `active`, `suspended`, `terminated` | | **Billing driver** | Monthly line + usage | Plan + metered data bytes | | **Mutation door** | Purchase/release/reclaim/update endpoints | `/numbers/connectivity/*` lifecycle endpoints | Reserve SIMs for devices that need connectivity and no reachable phone number. When a device also needs to receive M2M SMS at a stable address, pair the SIM with a purchased DID (see "Pairing a SIM with a DID" below). ## The state machine A SIM is always in exactly one of four states. The lifecycle is a closed enum, and every transition goes through a lifecycle endpoint — there is no way to land in a state without one of these doors: ``` order → ordered (entry point) activate → ordered → active (reversible further, see below) suspend → active → suspended (reversible) resume → suspended → active (reversible — the active ⇄ suspended pair) terminate → any state → terminated (terminal sink) ``` * **`ordered`** — the SIM exists and is billed against its plan, but no data session can accrue. This is the wait state between order and activation. For consumer eSIM plans it also holds the SIM while you issue a self-install activation (below). * **`active`** — the SIM may carry data. Sessions meter against its usage counter; quota, fleet, and OTA semantics all apply in this state. * **`suspended`** — a soft pause on an active SIM. No new data session is accepted; the SIM keeps its identity, quota, and fleet membership, and comes back with a resume call. Three actors place a SIM here: you (manual suspend), the quota enforcer (hard cap reached), and the device-lock guard (a session reported an IMEI outside the SIM's authorized-device allowlist). * **`terminated`** — the terminal sink. Nothing else runs against the SIM; the record stays readable for audit. Only one door closes permanently: `terminate`. The `active ⇄ suspended` pair reverses freely, and every state except `terminated` can also terminate early (`ordered → terminated` skips activation entirely). Every transition attempt against a SIM in the wrong state (for example, suspending a SIM that is already `terminated`) is rejected with `409`; check the current `state` with `GET /numbers/connectivity/sims/:iccid` before you retry. ## Who advances each transition Only the tenant (or an operator holding `numbers:write`) moves a SIM: each transition is an explicit POST to the lifecycle endpoint, and the change is committed atomically so concurrent calls serialize instead of last-writer-wins. Two transitions are additionally triggered by policy you configured earlier — the quota enforcer and the device-lock guard both suspend the SIM from inside the usage-path read-modify-write, before the violating session lands. The lifecycle fires a webhook per transition (`connectivity_sim.ordered`, `.activated`, `.suspended`, `.resumed`, `.terminated`) so your backend can react without polling. ## Fleets and pooled plans A fleet is nothing more than the set of SIMs ordered with the same `fleetId`. That string is the entire membership mechanism — and it buys you two things: 1. **A roll-up.** `GET /numbers/connectivity/fleets` returns one entry per fleet: member count, cumulative usage across members, and — for fleets on a pooled plan — pool health. 2. **A policy anchor.** Network Access Profiles attach to the fleet, not to individual SIMs, so a country/carrier allow-block policy applies uniformly to every member. The two plan families behave differently at roll-up: * **Pooled plans** (for example `iot-fleet-pooled`) — the plan carries an aggregate data allowance shared across the pool. The fleet summary reports allowance drawn, remaining, and an `ok` / `warning` / `exceeded` status, so fleet-wide consumption is the primary meter and per-SIM quotas become the safety net on top. * **Pay-as-you-go plans** (for example `esim-global-payg`) — each SIM meters standalone and nothing pools. The fleet is a grouping and policy construct, not a billing one. SIMs ordered without a `fleetId` stay standalone: they appear in the SIM list, join no roll-up, and stay unrestricted by any Network Access Profile. ## Quota and OTA semantics **Quota** is a per-SIM policy you set once and the platform enforces on every recorded session: * `dataLimitBytes` — a hard cap. When cumulative usage reaches it, the SIM auto-suspends and a `connectivity_sim.limit_exceeded` event fires once. * `warningThresholdPct` — a 1–99 percent marker of the cap. Crossing it fires `connectivity_sim.usage_warning` exactly once per threshold crossing, ahead of the hard stop. The correct recovery loop for the limit event is: raise the cap (`PATCH .../quota`), then resume the SIM (`POST .../resume`). The webhook payloads carry `iccid`, `plan_id`, `usage_bytes`, `data_limit_bytes`, and `warning_threshold_bytes`, so automation can do both steps without a read. A sibling guard on the same path: if you set an authorized-IMEI allowlist, a session reported from a device outside it suspends the SIM and accrues no usage — the theft-lock sibling of the quota suspend. **OTA (over-the-air) profiles** are the reconfiguration path: an OTA profile pushes a setting — most often an APN — to a live SIM over the air, queued or applied while the SIM is `active`. It is how you re-APN operator-managed IoT fleet hardware without reissuing SIMs. **RSP / eSIM activation** is the consumer-eSIM sibling of OTA: for `esim`-type plans you issue an SGP.22 activation — an LPA activation code plus QR payload — that the end user scans to install the profile on their own phone, tablet, or laptop. Re-issuing rotates the code; the previous payload stops being usable. Where OTA targets devices you manage, RSP targets devices owned by the end customer. ## Variant: pairing a data-only SIM with a DID The one case a data-only SIM cannot cover is a device that must send or receive SMS — for reboot / config-push control commands, or to report telemetry from constrained devices. Pair the SIM with a purchased DID and use **SMS Commands**: POST to `/numbers/connectivity/sims/:iccid/commands` with an org-owned `from` DID and the `to` device's address. The DID supplies the messaging identity; the SIM continues to carry data. Membership stays independent — suspending or terminating the SIM leaves the DID untouched, and releasing the DID leaves the SIM untouched. ## Complementary line types: private gateway and prefix announcements Two sibling lifecycle kernels sit beside the SIM one and compose instead of overlapping: * **Private wireless gateway** — a dedicated private APN that lands fleet traffic on your corporate network (IPsec / VPC peering) with private IP assignment. Its state machine runs `requested → provisioning → active ⇄ suspended → deprovisioned`, with `failed` as the provisioning-failure branch. Use it when fleet traffic must never touch the public APN. * **Tenant prefix announcement** — when you own a publicly routable IPv4 block (BYO-prefix), you register it and control which edge announces it, with strict failover ordering and fencing that prevents the same edge from ever appearing twice in the priority list (the hijack/active-active failure mode). States run `registered → announcing ⇄ withdrawn → deannounced`. Both carry the same data-only guarantee as SIMs: they change where data traffic lands, never how voice or SMS terminates. ## What this is not * **Not the DID lifecycle.** Number purchase, release, parking, and compliance states live in the [number status map](/concepts/number-lifecycle). * **Not outbound voice/SMS.** A SIM carries data only; callable and messageable endpoints come from purchased numbers. * **Not the operations runbook.** Endpoint-by-endpoint steps, payload tables, and troubleshooting live in the [lifecycle guide](/guides/connectivity-sim-lifecycle). ## Cross-links * [Provision and operate eSIM / IoT SIMs](/guides/connectivity-sim-lifecycle) — the step-by-step operations this page anchors. * [Numbers overview](/numbers/overview) — the line-type menu across DIDs, SIMs, and port-ins. * [Number status map](/concepts/number-lifecycle) — the E.164 DID state model. * [Webhook events](/reference/webhook-events) — payload shapes for every `connectivity_sim.*` event named above.