TEtelgea
Numbers

List lines

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.

get/v1/numbers

Request

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

Query parameters

pageinteger

Page to return, starting at 1.

Example:1
pageSizeinteger

Items per page, at most 100. Defaults to 50.

Example: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.

Example:createdAt
orderDirection'asc' | 'desc'

Sort direction. Only meaningful together with orderBy.

Example:asc
msisdnstring

Only the line on this number, in E.164 format. Matched exactly.

Example:+4520123456
iccidstring

Only the line whose eSIM has this ICCID. Matched exactly; a line with no SIM never matches.

Example:8945000000000000001
userIdstring uuid

Only the lines this user holds.

Example:9c1f2a6e-3b7d-4e0a-8f21-5d6c7b8a9e01
type'local' | 'travel'

Only lines of this kind.

Example:local
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.

Example:READY

Response

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

pageinteger required

The page these items came from.

pageSizeinteger required

Items per page, as requested.

itemsCountinteger required

Total items across all pages. Divide by pageSize to get the number of pages.

Example response

{
  "page": 1,
  "pageSize": 50,
  "itemsCount": 142,
  "items": [
    {
      "id": "8238c1b9-c2c0-4455-9b03-4bd787052709",
      "type": "local",
      "countryCode": "DK",
      "phoneNumber": "+4520123456",
      "state": "READY",
      "sim": {
        "iccid": "8945000000000000001",
        "activationCode": "LPA:1$SMDP.TELGEA.COM$34682-73063-9140",
        "pinOne": "1234",
        "pinTwo": "5678",
        "pukOne": "12345678",
        "pukTwo": "87654321"
      },
      "userId": "9c1f2a6e-3b7d-4e0a-8f21-5d6c7b8a9e01",
      "createdAt": "2026-09-17T08:15:00.000Z"
    }
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.