TEtelgea
User Plans

Create a new user plan

Provisions a local line for an existing user: a market-bound phone number and the eSIM that carries it.

The user must exist in your organization before creating a plan. Use the users endpoint to create users first if needed.

Provisioning flow:

  1. The user plan is created and returns PROVISIONING — a local number id, and travelNumberId: null
  2. A SIM is assigned from available inventory and the number allocated with the local market's operator
  3. The plan reaches ACTIVE, and GET /v1/user-plans/{userId} carries the local number's sim.activationCode

A travel eSIM is not part of this call. One 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 — poll GET /v1/user-plans/{userId} to see whether a travelNumber appeared.

To install the eSIM yourself, take sim.activationCode — a GSMA LPA:1$… string — from GET /v1/user-plans/{userId} and encode it as a QR code; any QR library will do.

Organizations with Telgea's end-user communications enabled also send the user installation instructions by email. White-label integrations have them switched off, so that activation code is the only delivery and presenting it is yours to do.

post/v1/user-plans

Request

  • Base URL
    https://api.telgea.com
  • Auth
    API key in header x-api-key

Headers

idempotency-keystring

A value unique to this request, of 1 to 255 printable ASCII characters — a UUID is the usual choice. Retry with the same key within 24 hours and you get the original response back, even if it was a failure, and nothing is done twice. Send a new key whenever you change the request. Keys are private to your API key and organisation.

Example:0b7e4f1c-6a2d-4c9e-8f35-d1a7b2c93e60

Request body

userIdstring uuid required

UUID of an existing user to provision a plan for

countryCodestring required

Two-character ISO country code for the user plan. Must be a valid ISO 3166-1 alpha-2 code (e.g., "DK", "US", "GB") and available in your organization's list of supported markets. Case-insensitive. Invalid codes are rejected immediately. Contact support to enable additional countries.

Example request

{
  "userId": "9c1f2a6e-3b7d-4e0a-8f21-5d6c7b8a9e01",
  "countryCode": "DK"
}

Response

User plan created successfully. Returns the complete plan details including assigned phone numbers and SIM information.

status'INACTIVE' | 'PROVISIONING' | 'PORTING' | 'PORTING_FAILED' | 'ACTIVE' | 'TERMINATING' | 'TERMINATING_WITH_DELETION' required

Current status of the user plan

localNumberIdstring nullable required

UUID of the provisioned local number

travelNumberIdstring nullable required

Always null. This call provisions the local line alone. A travel eSIM is added afterwards, and only for an organization whose contract includes one and which holds a data pool outside its home zone. Read travelNumber from GET /v1/user-plans/{userId} to see whether one exists.

Example response

{
  "status": "PROVISIONING",
  "localNumberId": "8238c1b9-c2c0-4455-9b03-4bd787052709"
}

Changes

No recorded changes to this operation across all 1 revision of this API.