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

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

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 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

Creating a User

First create a user with the POST /v1/users API:

// POST /v1/users
{
  "firstName": "Test",
  "lastName": "User",
  "email": "[email protected]"
}

Initiating provisioning

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

// 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:

// 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

Once provisioning completes, the User Plan transitions from PROVISIONING to ACTIVE. Poll GET /v1/user-plans/{userId} until it does. Space your polls to the market's typical provisioning time 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 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

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

// GET /v1/user-plans/1bbf32d6-5888-4c36-b50c-0816b532c1d2
{
  "userId": "1bbf32d6-5888-4c36-b50c-0816b532c1d2",
  "email": "[email protected]",
  "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.