---
title: "Get a line"
method: GET
path: "/v1/numbers/{numberId}"
tags: ["Numbers"]
---

# Get a line

`GET /v1/numbers/{numberId}`

## Request

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

Retrieves one line in full: the number, where it is in the provisioning lifecycle, its eSIM, when it last changed state, when it first went into service, the eSIMs it carried before its current one, and the date it is due to end if a termination is scheduled.

Take `sim.activationCode` — a GSMA `LPA:1$…` string — and encode it as a QR code to install the eSIM; any QR library will do. SIM details are published only while the line is `READY`, so during a replacement `sim` reads `null` rather than handing out a code that has been revoked.

A line in another organization answers exactly as one that does not exist.

## Path parameters

- `numberId` string, uuid, required: UUID of the line.

## Response `200`

Successfully retrieved the line.

- NumberDetails: One line in full.
  - `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.
  - `stateUpdatedAt` string, nullable, required: When the line last reached the state it is in, as an ISO 8601 UTC time. Null for a line with no state yet.
  - `terminationScheduledAt` string, nullable, required: The date this line is scheduled to end, or null when no termination is scheduled. Set by POST /v1/numbers/{numberId}/termination.
  - `activatedAt` string, nullable, required: When the line first went into service, as an ISO 8601 UTC time: when it was provisioned, or when its number was ported in. Null until then.
  - `previousSims` PreviousSim[], required: The eSIMs the line carried before its current one, newest first. Each SIM replacement adds one. Empty for a line whose eSIM has never been replaced.
    - `iccid` string, required: ICCID of the eSIM profile.
    - `inServiceFrom` string, required: When this eSIM was issued to the line, as an ISO 8601 UTC time.
    - `inServiceTo` string, required: When the eSIM that replaced it was issued, 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 read lines
- `404`: No line in your organization has this id.
- `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)