Number and eSIM lifecycle

Each user plan carries a number (localNumber, and travelNumber when the organization has one) with its own state. Most of the time you see PROVISIONING briefly and then READY; the other states cover porting, SIM replacement, stopping and restoring service, and the end of a line. The states mean the same thing everywhere, but in a market whose operator publishes no API a number can hold one of them for a few hours.

States

Status	Meaning	Your action
PENDING	Part of the published enum; a number is not returned until it is being provisioned or ported.	None.
PROVISIONING	Number and eSIM profile are being created with the provider. Seen only briefly.	Wait for the line to reach READY.
PORTING	A port-in is bringing this number from another carrier.	Follow the port-in lifecycle.
PORTING_FAILED	The last port-in for this number ended in REJECTED or FAILED, or was cancelled.	Correct the data and submit a new port-in, which reuses this number, or discard the failed port-in so the number leaves the plan.
PORTING_DISCARDED	The failed port-in was discarded and the number stays with its carrier. Never returned: the number leaves the plan in the same step.	None; the plan reads INACTIVE.
READY	The number is live and the eSIM can be installed or is installed.	Render the QR from the activation code.
PORTING_OUT	The number is being handed to a carrier its owner moved to. Never returned: the number leaves the plan in the same step.	None; the plan reads INACTIVE.
PORTED_OUT	The number now belongs to the carrier its owner moved to, so nothing is deactivated here and the number is not released. Never returned: the number leaves the plan in the same step.	None; the plan reads INACTIVE.
REPLACING	A SIM replacement is in progress. The number returns to READY whether it succeeds or fails.	Wait until READY again, then render the new QR.
CHANGING	Part of the published enum, but not returned today.	None.
RECONFIGURING	Network configuration is changing: mobile data is being stopped or restored, or roaming zones are being enabled after provisioning.	Wait; the number returns to READY.
SUSPENDING	A suspension is being applied at the network.	None: POST …/suspension returns once the number is SUSPENDED.
SUSPENDED	All traffic on the number is stopped. Stopping only mobile data does not use this state.	Restore with DELETE …/suspension.
RESTORING	A restore is being applied at the network.	None: DELETE …/suspension returns once the number is READY.
DEACTIVATING	An ended line is being deactivated at the network, 14 days after its termination date. The number has already left the plan.	None.
DEACTIVATED	The line is deactivated and the number released.	None.

eSIM install flow

The activation code is the only thing you need to put the eSIM on a device: render the QR, or an install link, inside your own product. Organizations with Telgea's end-user communications enabled also email the user an installation QR; white-label integrations have that switched off, so the activation code is the only delivery.

1. Poll until the line is READY.
2. Read activationCode on the line. It is an LPA string such as LPA:1$….
3. Render it as a QR code with any library.

The NumberSimInstalled webhook tells you when the profile is on the device.

A lost or broken SIM goes through POST /v1/user-plans/{userId}/sim-replacement: the number passes through REPLACING and returns to READY with a new activation code, and you render a new QR.

Stopping service

Two operations stop service on a number, and they use different states:

• Stopping mobile data leaves the number READY. It passes through RECONFIGURING while the change is applied, and calls and texts keep working.
• Suspending the line stops all traffic. It moves READY → SUSPENDING → SUSPENDED, and back through RESTORING when you restore it.

While a number is suspended, its plan reads ACTIVE. It reads TERMINATING only once the plan's end is booked.

Each returns once the change has taken effect at the network, so you never have to poll for the intermediate states.

Neither is offered in every market: where Markets says "Not supported", both are refused and the number stays READY. Ending the line works everywhere.

Ending a line

When a line is ended, it is suspended on the termination date and deactivated at the network 14 days later. See Ending a line.

Related

• Provision a line

• User plan lifecycle

• SimReplaced and NumberSimInstalled webhooks