---
title: "Search for a user plan"
method: GET
path: "/v1/user-plans/search"
tags: ["User Plans"]
---

# Search for a user plan

`GET /v1/user-plans/search`

## Request

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

Search for a user plan by email address, phone number (MSISDN), or ICCID (SIM card identifier). This endpoint is useful for looking up user plans when you only have contact identifiers.

Exactly one search parameter (email, msisdn, or iccid) must be provided.

The phone number must be in E.164 format (e.g., +4520123456).

## Query parameters

- `email` string, email: Email address of the user to search for
- `msisdn` string: Phone number in E.164 format to search for
- `iccid` string: ICCID (SIM card identifier) to search for

## Response `200`

Successfully found the user plan. Returns the same detailed information as the get user plan details endpoint.

- 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`: Exactly one of email, msisdn or iccid must be provided, and it must be well formed. Sending none, or more than one, is refused here.
- `401`: Missing or invalid API key in the X-API-Key header
- `403`: Insufficient permissions to search user plans
- `404`: No user plan found matching the provided search criteria
- `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)