---
title: "Get user plan details"
method: GET
path: "/v1/user-plans/{userId}"
tags: ["User Plans"]
---

# Get user plan details

`GET /v1/user-plans/{userId}`

## Request

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

Retrieves detailed information about a specific user's telecommunications plan, including assigned phone numbers, SIM card details, data allowances, and usage statistics.

Use this endpoint to view the complete telecommunications setup for a particular user.

## Path parameters

- `userId` string, uuid, required: UUID of the user whose plan this is.

## Response `200`

Successfully retrieved user plan details. Includes phone numbers, SIM information, and plan configuration.

- UserPlanDetails
  - `userId` string, required: UUID of the user who holds the plan.
  - `email` string, email, required: Email address of the user.
  - `firstName` string, required: First name of the user.
  - `lastName` string, required: Last name of the user.
  - `status` 'INACTIVE' | 'PROVISIONING' | 'PORTING' | 'PORTING_FAILED' | 'ACTIVE' | 'TERMINATING' | 'TERMINATING_WITH_DELETION', required: Current status of the user plan
  - `teamId` string, nullable, required: UUID of the user's team, or null. Teams are an enterprise concept and stay null for partners.
  - `localNumber` UserPlanNumber, nullable, required: The local line: the number, where it is in provisioning, and its eSIM.
    - `id` string, required: UUID of the number. This is what SIM replacement and suspension act on.
    - `type` 'local' | 'travel', required: Which line this is.
    - `countryCode` string, required: Market the number belongs to, ISO 3166-1 alpha-2.
    - `phoneNumber` string, nullable, required: The number in E.164 format, or null until it has been provisioned.
    - `state` 'PENDING' | 'PORTING' | 'PORTING_FAILED' | 'PROVISIONING' | 'READY' | 'REPLACING' | 'CHANGING' | 'SUSPENDING' | 'SUSPENDED' | 'RESTORING' | 'RECONFIGURING' | 'DEACTIVATING' | 'DEACTIVATED' | 'PORTING_DISCARDED' | 'PORTING_OUT' | 'PORTED_OUT' | 'null', nullable, required: Current state of the phone number in the provisioning lifecycle
    - `sim` UserPlanSimDetails, nullable, required: SIM details, included only when the number state is READY
      - `iccid` string, required: ICCID of the eSIM profile.
      - `activationCode` string, nullable, required: GSMA activation string for the eSIM. Render it as a QR code, or build an install link from it. Null until the profile has been issued.
      - `pinOne` string, nullable, required: PIN1 of the SIM, or null.
      - `pinTwo` string, nullable, required: PIN2 of the SIM, or null.
      - `pukOne` string, nullable, required: PUK1, needed after three wrong PIN1 entries, or null.
      - `pukTwo` string, nullable, required: PUK2, needed after three wrong PIN2 entries, or null.
  - `travelNumber` UserPlanTravelNumber, nullable, required: The travel line and its eSIM, when the organization has one. Null for a local-only plan.
    - `id` string, required: UUID of the travel number.
    - `type` 'local' | 'travel', required: Which line this is.
    - `phoneNumber` string, nullable, required: The travel number in E.164 format, or null when the profile carries data only.
    - `state` 'PENDING' | 'PORTING' | 'PORTING_FAILED' | 'PROVISIONING' | 'READY' | 'REPLACING' | 'CHANGING' | 'SUSPENDING' | 'SUSPENDED' | 'RESTORING' | 'RECONFIGURING' | 'DEACTIVATING' | 'DEACTIVATED' | 'PORTING_DISCARDED' | 'PORTING_OUT' | 'PORTED_OUT' | 'null', nullable, required: Current state of the phone number in the provisioning lifecycle
    - `sim` UserPlanSimDetails, nullable, required: SIM details, included only when the number state is READY
      - `iccid` string, required: ICCID of the eSIM profile.
      - `activationCode` string, nullable, required: GSMA activation string for the eSIM. Render it as a QR code, or build an install link from it. Null until the profile has been issued.
      - `pinOne` string, nullable, required: PIN1 of the SIM, or null.
      - `pinTwo` string, nullable, required: PIN2 of the SIM, or null.
      - `pukOne` string, nullable, required: PUK1, needed after three wrong PIN1 entries, or null.
      - `pukTwo` string, nullable, required: PUK2, needed after three wrong PIN2 entries, or null.
  - `terminationScheduledAt` string, nullable, required: The date this plan is scheduled to end, or null when no termination is scheduled. Set by POST /v1/user-plans/{userId}/termination.

## Other responses

- `400`: Request failed schema validation, or was refused by a business rule
- `401`: Missing or invalid API key in the X-API-Key header
- `403`: Insufficient permissions to view user plan details
- `404`: User not found. The specified user ID does not belong to a user in your organization.
- `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)