---
title: "List all user plans"
method: GET
path: "/v1/user-plans"
tags: ["User Plans"]
---

# List all user plans

`GET /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`

Retrieves a paginated list of user plans in your organization. A user plan represents the association between a user and their telecommunications resources (SIM cards, phone numbers, data plans).

Use filters to narrow results by user, team, or plan status. Supports pagination for large datasets.

## Query parameters

- `page` integer: Page to return, starting at 1.
- `pageSize` integer: Items per page, at most 100. Defaults to 50.
- `orderBy` 'firstName' | 'localPhoneNumber' | 'status' | 'teamName': Field to sort by. Defaults to the order the plans were created in.
- `orderDirection` 'asc' | 'desc': Sort direction. Only meaningful together with orderBy.

## Response `200`

Successfully retrieved user plans. Returns a paginated list with total count and plan details.

- ListUserPlansResponse
  - `page` integer, required: The page these items came from.
  - `pageSize` integer, required: Items per page, as requested.
  - `itemsCount` integer, required: Total items across all pages. Divide by pageSize to get the number of pages.
  - `items` UserPlanItem[], required: User plans on this page.
    - `id` string, required: UUID of the user plan.
    - `userId` string, required: UUID of the user who holds the plan.
    - `firstName` string, required: First name of the user.
    - `lastName` string, required: Last name of the user.
    - `email` string, email, required: Email address of the user.
    - `status` 'INACTIVE' | 'PROVISIONING' | 'PORTING' | 'PORTING_FAILED' | 'ACTIVE' | 'TERMINATING' | 'TERMINATING_WITH_DELETION', required: Current status of the user plan
    - `localPhoneNumber` string, nullable, required: The local number in E.164 format, or null until it has been provisioned.
    - `teamId` string, nullable, required: UUID of the user's team, or null. Teams are an enterprise concept and stay null for partners.
    - `teamName` string, nullable, required: Name of the user's team, or null. Teams are an enterprise concept and stay null for partners.

## 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 list user plans
- `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)