Numbers

The number object

The lines you sell: obtain one, look it up, replace its SIM, stop it and end it.

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.

Requires the permission numbers:read on the key.

Try it in the playground → Calls run against your live organization; there is no sandbox.

Parameters

Responses

Problems this endpoint can return

This endpoint returns no domain-specific problems.

curl -X GET "https://api.telgea.com/v1/numbers" \
  -H "x-api-key: $TELGEA_API_KEY"

{
  "page": 1,
  "pageSize": 50,
  "itemsCount": 2,
  "items": [
    {
      "id": "8238c1b9-c2c0-4455-9b03-4bd787052709",
      "userId": "9c1f2a6e-3b7d-4e0a-8f21-5d6c7b8a9e01",
      "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"
      },
      "createdAt": "2026-09-17T08:15:00.000Z"
    },
    {
      "id": "5a1c8e37-2d64-4b90-8fa2-6c0e9d4b7132",
      "userId": "3e5d1b42-7c90-4a18-b6f3-0d9e2a4c7f85",
      "type": "local",
      "countryCode": "SE",
      "phoneNumber": null,
      "state": "PROVISIONING",
      "sim": null,
      "createdAt": "2026-09-18T11:02:00.000Z"
    }
  ]
}

Obtain a line

Obtains a local line for one of your customers: a market-bound phone number and the eSIM that carries it.

The user must exist in your organization first — create one with POST /v1/users.

Provisioning flow: 1. This call returns the line's id and state: PROVISIONING 2. A SIM is assigned from available inventory and the number allocated with the local market's operator 3. The line reaches READY, and GET /v1/numbers/{numberId} carries its sim.activationCode

Organizations with Telgea's end-user communications enabled also send the user installation instructions by email. White-label integrations have them switched off, so that activation code is the only delivery and presenting it is yours to do.

Requires the permission numbers:create-local on the key.

Try it in the playground → Calls run against your live organization; there is no sandbox.

Parameters

Request body

Responses

Problems this endpoint can return

curl -X POST "https://api.telgea.com/v1/numbers" \
  -H "x-api-key: $TELGEA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "userId": "9c1f2a6e-3b7d-4e0a-8f21-5d6c7b8a9e01",
  "countryCode": "DK"
}'

{
  "numberId": "8238c1b9-c2c0-4455-9b03-4bd787052709",
  "state": "PROVISIONING"
}

Get a line

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.

Requires the permission numbers:read on the key.

Try it in the playground → Calls run against your live organization; there is no sandbox.

Parameters

Responses

Problems this endpoint can return

curl -X GET "https://api.telgea.com/v1/numbers/8238c1b9-c2c0-4455-9b03-4bd787052709" \
  -H "x-api-key: $TELGEA_API_KEY"

{
  "id": "8238c1b9-c2c0-4455-9b03-4bd787052709",
  "userId": "9c1f2a6e-3b7d-4e0a-8f21-5d6c7b8a9e01",
  "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"
  },
  "createdAt": "2026-09-17T08:15:00.000Z",
  "stateUpdatedAt": "2026-10-01T10:00:00.000Z",
  "terminationScheduledAt": null,
  "activatedAt": "2026-09-17T08:20:00.000Z",
  "previousSims": [
    {
      "iccid": "89462000099812030017",
      "inServiceFrom": "2026-09-17T08:20:00.000Z",
      "inServiceTo": "2026-10-01T10:00:00.000Z"
    }
  ]
}

Get a line's connection status

Reads what the network reports about one line: its status there (active, suspended or inactive), when it last saw activity on the line, the country and operator the line is attached to, the network type, and the IP address, APN and device IMEI in use.

A line is read at most once per 5-minute window. The windows are fixed, starting on the clock's 5-minute marks rather than at a request. A request inside a window gets the answer the network gave at checkedAt, whoever asked first, without the network being asked again — so polling more often returns the same answer. The first request in the next window reads the line again, however recent the last read. A failed read is answered again the same way until its window ends. Reads of many lines are answered a few at a time per network, so a loop over a large roster takes a while.

Some lines cannot be read: those in a market whose network does not report connection status, those with no phone number or eSIM yet, and those still being ported in or already ended. They answer 200 with available: false and every other field null.

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

Requires the permission numbers:read on the key.

Try it in the playground → Calls run against your live organization; there is no sandbox.

Parameters

Responses

Problems this endpoint can return

curl -X GET "https://api.telgea.com/v1/numbers/8238c1b9-c2c0-4455-9b03-4bd787052709/connection" \
  -H "x-api-key: $TELGEA_API_KEY"

{
  "available": true,
  "status": "active",
  "lastSeenAt": "2026-10-19T11:58:00.000Z",
  "countryCode": "DK",
  "servingNetwork": "TDC",
  "accessTechnology": "4G",
  "ipAddress": "10.20.30.40",
  "apn": "internet",
  "imei": "356938035643809",
  "checkedAt": "2026-10-19T12:00:00.000Z"
}

Replace a SIM card

Initiates a SIM card replacement (eSIM swap) on one line. This provisions a new eSIM and deactivates the previous one.

Important: This endpoint should only be used when the end-user changes devices and the existing eSIM activation QR code (LPA string) has been confirmed to be expired or no longer working. Do not use this endpoint to troubleshoot connectivity issues — contact support instead.

Rate limit: one replacement per line inside the cooldown your organization's SIM-swap offering sets, counted from when the line's last replacement finished — and once per calendar day for a German number. A request inside the window gets a 429 naming when to retry.

Flow: 1. A new eSIM profile is provisioned and the old SIM is deactivated 2. Until the new profile is ready, GET /v1/numbers/{numberId} reports the line with sim: null — its state is REPLACING, and SIM details are published only in READY 3. Back in READY, the line's sim.activationCode is the new one to render as a QR code

Organizations with Telgea's end-user communications enabled also email the user the new activation code. White-label integrations have them switched off and present it themselves.

Requires the permission numbers:replace-sim on the key.

Try it in the playground → Calls run against your live organization; there is no sandbox.

Parameters

Responses

Problems this endpoint can return

curl -X POST "https://api.telgea.com/v1/numbers/8238c1b9-c2c0-4455-9b03-4bd787052709/sim-replacement" \
  -H "x-api-key: $TELGEA_API_KEY"

{
  "status": "accepted"
}

Suspend a line

Stops all traffic on one line, domestic and international — for a phone that has been lost or stolen. To stop only mobile data and leave the line usable, use the data-restriction endpoint.

The call returns once the line is down at the network, so a 204 means the service is genuinely stopped.

Suspending a line that is already suspended returns 409 and changes nothing.

Not every market offers suspension. Where it does not, this returns 400 and the line stays live — the Markets page in the documentation lists which is which.

Requires the permission numbers:suspend on the key.

Try it in the playground → Calls run against your live organization; there is no sandbox.

Parameters

Responses

Problems this endpoint can return

curl -X POST "https://api.telgea.com/v1/numbers/8238c1b9-c2c0-4455-9b03-4bd787052709/suspension" \
  -H "x-api-key: $TELGEA_API_KEY"

{
  "type": "https://developer.telgea.com/errors/http/BAD_REQUEST",
  "title": "Bad request",
  "status": 400,
  "detail": "This request was refused, and no more specific code describes why.",
  "code": "BAD_REQUEST",
  "requestId": "req_123"
}

Restore a suspended line

Undoes a suspension made with POST /v1/numbers/{numberId}/suspension, and returns once the line is live again at the network.

Restoring a line that is not suspended returns 409.

Requires the permission numbers:unsuspend on the key.

Try it in the playground → Calls run against your live organization; there is no sandbox.

Parameters

Responses

Problems this endpoint can return

curl -X DELETE "https://api.telgea.com/v1/numbers/8238c1b9-c2c0-4455-9b03-4bd787052709/suspension" \
  -H "x-api-key: $TELGEA_API_KEY"

{
  "type": "https://developer.telgea.com/errors/http/BAD_REQUEST",
  "title": "Bad request",
  "status": 400,
  "detail": "This request was refused, and no more specific code describes why.",
  "code": "BAD_REQUEST",
  "requestId": "req_123"
}

Stop a line's mobile data

Stops mobile data on one line — for a customer who has used up what they paid for. Calls and texts keep working; use the suspension endpoint to stop the whole line.

The call returns once the change has taken effect at the network, so a 200 means the data is genuinely off. Nothing here is queued for later.

Stopping data that is already stopped returns 409 and changes nothing. Our own automated processes never undo a stop you made — only DELETE on this path does.

Data is stopped against the data pool the line draws on, so a line in none of your pools returns 422. Not every market offers stopping data on its own either; where it does not, this returns 422 and nothing changes — the Markets page in the documentation lists which is which.

Requires the permission numbers:suspend on the key.

Try it in the playground → Calls run against your live organization; there is no sandbox.

Parameters

Request body

Responses

Problems this endpoint can return

curl -X POST "https://api.telgea.com/v1/numbers/8238c1b9-c2c0-4455-9b03-4bd787052709/data-restriction" \
  -H "x-api-key: $TELGEA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "Customer exceeded their agreed data allowance."
}'

{
  "numbers": [
    "+4520123456"
  ],
  "effectiveAt": "2026-09-14T09:30:00.000Z"
}

Restore a line's mobile data

Undoes a stop made with POST /v1/numbers/{numberId}/data-restriction, and returns once data is live again at the network.

Restoring data that is not stopped returns 409. Data stays off if the customer is also over an allowance you set — clear that first.

Requires the permission numbers:unsuspend on the key.

Try it in the playground → Calls run against your live organization; there is no sandbox.

Parameters

Responses

Problems this endpoint can return

curl -X DELETE "https://api.telgea.com/v1/numbers/8238c1b9-c2c0-4455-9b03-4bd787052709/data-restriction" \
  -H "x-api-key: $TELGEA_API_KEY"

{
  "numbers": [
    "+4520123456"
  ],
  "effectiveAt": "2026-09-14T09:30:00.000Z"
}

End a line

Ends the line on the date you name — the date the customer agreed to stop.

The line is suspended on that date and deactivated at the network 14 days later. The call returns as soon as the termination is scheduled, so a 202 means it is booked, not that the line is already down. Read it back on GET /v1/numbers/{numberId} as terminationScheduledAt.

Billing is not prorated. The customer keeps the period they already bought: the line stops on your date, and billing runs to activeUntil in the response. The plan does not renew afterwards.

Send deleteUser: true to delete the end-user along with the line. Otherwise the user remains, and DELETE /v1/users/{userId} succeeds once the line is suspended — you do not have to wait out the grace period.

The response lists every line the termination ends, which can be more than the one you named: a travel eSIM raised against this line's plan ends with it.

Requires the permission orders:cancel on the key.

Try it in the playground → Calls run against your live organization; there is no sandbox.

Parameters

Request body

Responses

Problems this endpoint can return

curl -X POST "https://api.telgea.com/v1/numbers/8238c1b9-c2c0-4455-9b03-4bd787052709/termination" \
  -H "x-api-key: $TELGEA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "terminationDate": "2026-10-01",
  "deleteUser": true
}'

{
  "terminationDate": "2026-10-01",
  "activeUntil": "2026-12-31T00:00:00.000Z",
  "numberIds": [
    "8238c1b9-c2c0-4455-9b03-4bd787052709"
  ]
}