# Provision a Number Give a user a number and an eSIM, and get the eSIM onto their device. > Partner API · https://developer.telgea.com/docs/partner/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 lines a customer holds [#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`](https://developer.telgea.com/docs/partner/api/numbers#list-lines) is what says which lines a customer holds; each line carries its own `type`. ## 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/partner/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] You can run this whole flow from the playground: [create a user](https://developer.telgea.com/playground#tag/users/POST/v1/users), then [obtain their line](https://developer.telgea.com/playground#tag/numbers/POST/v1/numbers). There is no sandbox, so these calls act on your live organization — provisioning creates a real line. ### Creating a User [#creating-a-user] First [create a user](https://developer.telgea.com/docs/partner/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 names whom the line is for. Use it to call `POST /v1/numbers`: ```json op="POST /v1/numbers" dir=request // 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: ```json op="POST /v1/numbers" dir=response status=202 // Response HTTP 202 Accepted { "numberId": "8238c1b9-c2c0-4455-9b03-4bd787052709", "state": "PROVISIONING" } ``` ### Tracking Provisioning Completion [#tracking-provisioning-completion] Once provisioning completes, the line goes from `PROVISIONING` to `READY`. Poll [`GET /v1/numbers/{numberId}`](https://developer.telgea.com/docs/partner/api/numbers#get-a-line) 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. > 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 line reaches `READY`, the MSISDN (phone number) and the eSIM details are on it: ```json op="GET /v1/numbers/{numberId}" dir=response status=200 // 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 [#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. | Market | Name the phone displays | Texts the network sends | | -------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | Belgium | MOBILE | Not confirmed yet | | Denmark | Telgea | At 80% and 100% of the data allowance, and a welcome text when the phone starts roaming | | France | Telgea | Not confirmed yet | | Germany | Mobilfunk | At 80% and 100% of the monthly data allowance, the second saying speed is now throttled, and when the phone connects to a network outside Germany | | Netherlands | TELGEA | Not confirmed yet | | Poland | Not confirmed yet | Not confirmed yet | | Spain | MOBILE | Not confirmed yet | | Sweden | Teleco | When 20% of the data allowance is left, and when none is | | United Kingdom | Telgea | Not confirmed yet | | United States | Telgea | None | Tell your customers to expect these, so a text from their network is not mistaken for one from you.