---
title: "Create a new user plan"
method: POST
path: "/v1/user-plans"
tags: ["User Plans"]
---

# Create a new user plan

`POST /v1/user-plans`

## Request

- Base URL: `https://api.telgea.com`
- URL: `https://api.telgea.com/v1/user-plans`
- Auth: API key in header `x-api-key`

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.

## Headers

- `idempotency-key` string: 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.

## Request body

- CreateUserPlanBody
  - `userId` string, uuid, required: UUID of an existing user to provision a plan for
  - `countryCode` string, 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.

## Response `200`

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

- CreateUserPlanResponse
  - `status` 'INACTIVE' | 'PROVISIONING' | 'PORTING' | 'PORTING_FAILED' | 'ACTIVE' | 'TERMINATING' | 'TERMINATING_WITH_DELETION', required: Current status of the user plan
  - `localNumberId` string, nullable, required: UUID of the provisioned local number
  - `travelNumberId` string, 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.

## Other responses

- `400`: Request failed schema validation, or the country code is not a supported ISO 3166-1 alpha-2 code
- `401`: Missing or invalid API key in the X-API-Key header
- `403`: Insufficient permissions, or the requested country is not available for your organization: nothing it can buy covers the country, or the country requires business verification your organization has not passed.
- `404`: User not found in your organization, or no local plan is available for the requested market.
- `409`: The user already has an active plan, so nothing was created.
- `429`: The API key has used its request quota for the current window. `Retry-After` says how many seconds until it resets.
- `500`: Internal server error. Contact support if this persists.

---

[API](https://skmtc.dev/telgea/apis/telgea-api.md) - [All operations](https://skmtc.dev/telgea/apis/telgea-api/llms.txt) - [OpenAPI document](https://skmtc.dev/telgea/apis/telgea-api/revisions/4e8f8c04fe9e?raw)