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 lines a customer holds

When you obtain a mobile number in a market for a customer, you get their base, market-bound phone number — a local line, a full-service eSIM carrying voice, SMS and data.

A customer 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 (a travel line). That line is not created by the call below 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. GET /v1/numbers is what says which lines a customer holds; each line carries its own type.

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 names whom the line is for. Use it to call POST /v1/numbers:

// POST /v1/numbers
{
  "userId": "1bbf32d6-5888-4c36-b50c-0816b532c1d2",
  "countryCode": "US"
}

The call returns at once – this does not mean the line is provisioned, only that provisioning has been initiated for it, as apparent from the PROVISIONING state it comes back in:

// Response HTTP 202 Accepted
{
  "numberId": "8238c1b9-c2c0-4455-9b03-4bd787052709",
  "state": "PROVISIONING"
}

Tracking Provisioning Completion

Once provisioning completes, the line goes from PROVISIONING to READY. Poll GET /v1/numbers/{numberId} 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.

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 line reaches READY, the MSISDN (phone number) and the eSIM details are on it:

// GET /v1/numbers/8238c1b9-c2c0-4455-9b03-4bd787052709
{
  "id": "8238c1b9-c2c0-4455-9b03-4bd787052709",
  "userId": "1bbf32d6-5888-4c36-b50c-0816b532c1d2",
  "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"
  },
  "createdAt": "2026-09-17T08:15:00.000Z",
  "stateUpdatedAt": "2026-09-17T08:20:00.000Z",
  "terminationScheduledAt": null,
  "activatedAt": "2026-09-17T08:20:00.000Z",
  "previousSims": []
}

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.

What the network shows your customers

Telgea sends your customers nothing, but the network each line runs on still reaches them in two ways, and the API cannot change either:

• Its name. The phone displays the network's name, not yours.
• Its texts. In some markets the network texts the customer directly about their data allowance or when they start roaming.

Tell your customers to expect these, so a text from their network is not mistaken for one from you.