# Provision a Number

Give a user a number and an eSIM, and get the eSIM onto their device.

> Enterprise API · https://developer.telgea.com/docs/enterprise/guides/number-provisioning

## Number Provisioning Overview [#number-provisioning-overview]

**Number provisioning** is the process of allocating and activating a new phone number for a user.
This involves coordinating with mobile network operators, configuring eSIM profiles, and ensuring the number is ready for voice, data, and messaging services.
The Telgea Platform and its Open API makes this process simple and intuitive.

## How it fits together [#how-it-fits-together]

## The User Plan Container [#the-user-plan-container]

When you provision a mobile number in a market for a Telgea user, you get their base, market-bound
phone number — their `local` number, a full-service eSIM carrying voice, SMS and data.

A user plan can hold a second line: a data-only, ancillary travel eSIM with no calling capabilities and
no phone number, but more extensive and lower-rate data roaming (their `travel` number). That line is
**not** created by the provisioning call and is not created for every organization. It is added
afterwards, on its own, and only for an organization whose contract includes one and which holds a
data pool outside its home zone — a travel eSIM has no data to roam on otherwise. Treat
`travelNumber` as absent unless a response says otherwise.

As a layer of abstraction, in the Telgea Platform, a local eSIM and any associated travel eSIM are
referred to as a **User Plan.** The Telgea Platform manages this abstraction and APIs act on the User
Plan abstraction level.

## Asynchronous Processing Model [#asynchronous-processing-model]

Provisioning is **always asynchronous** because its completion is dependent on several factors such as the
selected market, underlying network conditions, services requested and more. How long it takes depends mostly on the
market's network — [Markets](https://developer.telgea.com/docs/enterprise/concepts/markets) carries the average for each one.

Wait for the API to report the line in service rather than a timer, and never read a long `PROVISIONING` as a failure.

## Provision a line [#provision-a-line]

<Callout type="warn" title="Try it in the playground — for real">
  You can run this whole flow from the playground: [create a user](https://developer.telgea.com/playground#tag/users/POST/v1/users), then [create their plan](https://developer.telgea.com/playground#tag/user-plans/POST/v1/user-plans). There is no sandbox, so these calls act on your live organization — provisioning creates a real line.
</Callout>

### Creating a User [#creating-a-user]

First [create a user](https://developer.telgea.com/docs/enterprise/api/users#create-a-new-user) with the `POST /v1/users` API:

```json op="POST /v1/users" dir=request
// POST /v1/users
{
  "firstName": "Test",
  "lastName": "User",
  "email": "new-user@telgea.com"
}
```

### Initiating provisioning [#initiating-provisioning]

The `userId` on the returned entity is the key used for User Plan actions. Use it to call `POST /v1/user-plans`:

```json op="POST /v1/user-plans" dir=request
// POST /v1/user-plans
{
  "userId": "1bbf32d6-5888-4c36-b50c-0816b532c1d2",
  "countryCode": "US"
}
```

The User Plans API immediately returns – this does **not** mean that a plan is provisioned, instead the provisioning
process has been initiated for this user, as apparent from the User Plan's `PROVISIONING` status:

```json op="POST /v1/user-plans" dir=response status=200
// Response HTTP 200 OK
{
  "status": "PROVISIONING", // Note provisioning status
  "localNumberId": "8238c1b9-c2c0-4455-9b03-4bd787052709",
  "travelNumberId": null // Always null: this call provisions the local line alone
}
```

### Tracking Provisioning Completion [#tracking-provisioning-completion]

Once provisioning completes, the User Plan transitions from `PROVISIONING` to `ACTIVE`. Poll
[`GET /v1/user-plans/{userId}`](https://developer.telgea.com/docs/enterprise/api/user-plans#get-user-plan-details) until it does. Space your polls to the
market's [typical provisioning time](#asynchronous-processing-model) rather than polling in a tight loop, since every
request counts against your key's daily budget.

Instead of polling, you can subscribe to the [UserPlanActive webhook](https://developer.telgea.com/docs/enterprise/webhooks/user-plan-active) to be notified
when the User Plan transitions to `ACTIVE`.

> Once the line is in service, it gains a `sim` property carrying the network details you need for
> installation. A line publishes those details only in the `READY` state; in any other state `sim` is `null`.

## Installing the eSIM [#installing-the-esim]

When the User Plan becomes `ACTIVE`, the MSISDN (phone number) and the eSIM details are on the plan:

```json op="GET /v1/user-plans/{userId}" dir=response status=200
// GET /v1/user-plans/1bbf32d6-5888-4c36-b50c-0816b532c1d2
{
  "userId": "1bbf32d6-5888-4c36-b50c-0816b532c1d2",
  "email": "new-user@telgea.com",
  "firstName": "Test",
  "lastName": "User",
  "status": "ACTIVE",
  "teamId": null,
  "localNumber": {
    "id": "8238c1b9-c2c0-4455-9b03-4bd787052709",
    "type": "local",
    "countryCode": "US",
    "phoneNumber": "+186975166810",
    "state": "READY",
    "sim": {
      "iccid": "89546189664901487180",
      "activationCode": "LPA:1$SMDP.TELGEA.COM$63872-95732-52566",
      "pinOne": "2602",
      "pinTwo": "1100",
      "pukOne": "42501848",
      "pukTwo": "40541678"
    }
  },
  "travelNumber": null, // Present only once a travel eSIM has been provisioned for this user
  "terminationScheduledAt": null
}
```

The `activationCode` of each SIM is the key piece of information needed for user installation. Its format is the same
for all eSIMs globally as per GSMA standards (`LPA:1$SERVER$ID`) and the QR codes you might have used to install eSIMs
are just that LPA string encoded as a QR.

So to put the eSIM on a device, encode `activationCode` as a QR code with any QR library and show it to the user, or
hand them the string to enter manually. Nothing about the code is Telgea-specific and you never need to fetch an image
from us. Note that a line's `id` is separate from the `userId`, and that a user holding both eSIM types has one `id`
per line. As the travel eSIM is used only when roaming outside the Home Zone, you might not prompt the user to install
it right away.

> If your organization has Telgea's end-user communications enabled, the user also receives an installation email
> carrying the QR code, and a notification in the Telgea app. White-label integrations have them switched off, so the
> `activationCode` above is the only delivery and presenting it to the user is yours to do.

**That's it! Your user now has a ready-to-use, supercharged Telgea phone number.**