# Number and eSIM lifecycle

The states of a single number, how an eSIM gets installed on the device, and how suspend and restore will fit in.

> Enterprise API · https://developer.telgea.com/docs/enterprise/concepts/number-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](https://developer.telgea.com/docs/enterprise/concepts/markets) a number can hold one of them for a few hours.

## States [#states]

## eSIM install flow [#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`](https://developer.telgea.com/docs/enterprise/api/user-plans#replace-a-sim-card): the number passes through `REPLACING` and returns to `READY` with a new activation code, and you render a new QR.

## Stopping service [#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](https://developer.telgea.com/docs/enterprise/concepts/markets) says "Not supported", both are refused and the number stays `READY`. Ending the line works everywhere.

## Ending a line [#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](https://developer.telgea.com/docs/enterprise/guides/end-a-plan).

## Related [#related]

* [Provision a line](https://developer.telgea.com/docs/enterprise/guides/number-provisioning)

- [User plan lifecycle](https://developer.telgea.com/docs/enterprise/concepts/user-plan-lifecycle)

* [SimReplaced](https://developer.telgea.com/docs/enterprise/webhooks/sim-replaced) and [NumberSimInstalled](https://developer.telgea.com/docs/enterprise/webhooks/number-sim-installed) webhooks