---
title: "List lines"
method: GET
path: "/v1/numbers"
tags: ["Numbers"]
---

# List lines

`GET /v1/numbers`

## Request

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

Retrieves a paginated list of the lines in your organization — the numbers you sell and the eSIMs that carry them.

Every filter is optional and they combine, so this one endpoint answers both "the next page of my roster" and "the line on this number". Narrow by `msisdn` or `iccid` to look one up, by `userId` for the lines one customer holds, and by `type` or `state` for a slice of the roster.

A line that was just ordered appears here with `state: null` until its first lifecycle event, and its SIM details are published only once it reaches `READY`.

## Query parameters

- `page` integer: Page to return, starting at 1.
- `pageSize` integer: Items per page, at most 100. Defaults to 50.
- `orderBy` 'createdAt' | 'phoneNumber' | 'type': Field to sort by. Defaults to the order the lines were created in. `state` is not sortable: it is derived per line, so sorting by it would resolve the state of every line in your organization before a page could be picked. Narrow by it instead.
- `orderDirection` 'asc' | 'desc': Sort direction. Only meaningful together with orderBy.
- `msisdn` string: Only the line on this number, in E.164 format. Matched exactly.
- `iccid` string: Only the line whose eSIM has this ICCID. Matched exactly; a line with no SIM never matches.
- `userId` string, uuid: Only the lines this user holds.
- `type` 'local' | 'travel': Only lines of this kind.
- `state` 'PENDING' | 'PORTING' | 'PORTING_FAILED' | 'PROVISIONING' | 'READY' | 'REPLACING' | 'CHANGING' | 'SUSPENDING' | 'SUSPENDED' | 'RESTORING' | 'RECONFIGURING' | 'DEACTIVATING' | 'DEACTIVATED' | 'PORTING_DISCARDED' | 'PORTING_OUT' | 'PORTED_OUT': Only lines in this state. Costs more than the other filters, since the state of each of your lines is resolved to answer it.

## Response `200`

Successfully retrieved lines. Returns a paginated list with the total count.

- ListNumbersResponse
  - `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` NumberListItem[], required: Lines on this page.
    - `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.
    - `userId` string, required: UUID of the user who holds the line.
    - `createdAt` string, required: When the line was created, as an ISO 8601 UTC time.

## 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 lines
- `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)