Skip to main content

​
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; for the line-type menu across all of Numbers, start at 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 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: 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:
  • 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.
  • 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.