User plans

The user plan object

Provision SIM cards, phone numbers, and data plans for users.

List all user plans

Retrieves a paginated list of user plans in your organization. A user plan represents the association between a user and their telecommunications resources (SIM cards, phone numbers, data plans).

Use filters to narrow results by user, team, or plan status. Supports pagination for large datasets.

Requires the permission user-plans: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/user-plans" \
  -H "x-api-key: $TELGEA_API_KEY"

{
  "page": 1,
  "pageSize": 50,
  "itemsCount": 2,
  "items": [
    {
      "id": "f7a8b9c0-d1e2-3456-f789-012345678901",
      "userId": "9c1f2a6e-3b7d-4e0a-8f21-5d6c7b8a9e01",
      "firstName": "Anna",
      "lastName": "Holm",
      "email": "[email protected]",
      "status": "ACTIVE",
      "localPhoneNumber": "+4520123456",
      "teamId": "2f6b0d3a-8c1e-4a7f-9b2d-1e3c4d5f6a70",
      "teamName": "Field Sales"
    },
    {
      "id": "5a1c8e37-2d64-4b90-8fa2-6c0e9d4b7132",
      "userId": "3e5d1b42-7c90-4a18-b6f3-0d9e2a4c7f85",
      "firstName": "Jonas",
      "lastName": "Berg",
      "email": "[email protected]",
      "status": "PROVISIONING",
      "localPhoneNumber": null,
      "teamId": null,
      "teamName": null
    }
  ]
}

Create a new user plan

Provisions a local line for an existing user: a market-bound phone number and the eSIM that carries it.

The user must exist in your organization before creating a plan. Use the users endpoint to create users first if needed.

Provisioning flow: 1. The user plan is created and returns PROVISIONING — a local number id, and travelNumberId: null 2. A SIM is assigned from available inventory and the number allocated with the local market's operator 3. The plan reaches ACTIVE, and GET /v1/user-plans/{userId} carries the local number's sim.activationCode

A travel eSIM is not part of this call. One is added afterwards, on its own, and only for an organization whose contract includes one and which holds a data pool outside its home zone — poll GET /v1/user-plans/{userId} to see whether a travelNumber appeared.

To install the eSIM yourself, take sim.activationCode — a GSMA LPA:1$… string — from GET /v1/user-plans/{userId} and encode it as a QR code; any QR library will do.

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 user-plans:create 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/user-plans" \
  -H "x-api-key: $TELGEA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "userId": "9c1f2a6e-3b7d-4e0a-8f21-5d6c7b8a9e01",
  "countryCode": "DK"
}'

{
  "status": "PROVISIONING",
  "localNumberId": "8238c1b9-c2c0-4455-9b03-4bd787052709",
  "travelNumberId": null
}

Search for a user plan

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).

Requires the permission user-plans: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/user-plans/search" \
  -H "x-api-key: $TELGEA_API_KEY"

{
  "userId": "9c1f2a6e-3b7d-4e0a-8f21-5d6c7b8a9e01",
  "email": "[email protected]",
  "firstName": "Anna",
  "lastName": "Holm",
  "status": "ACTIVE",
  "teamId": "2f6b0d3a-8c1e-4a7f-9b2d-1e3c4d5f6a70",
  "terminationScheduledAt": null,
  "localNumber": {
    "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"
    }
  },
  "travelNumber": null
}

Get user plan details

Retrieves detailed information about a specific user's telecommunications plan, including assigned phone numbers, SIM card details, data allowances, and usage statistics.

Use this endpoint to view the complete telecommunications setup for a particular user.

Requires the permission user-plans: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/user-plans/9c1f2a6e-3b7d-4e0a-8f21-5d6c7b8a9e01" \
  -H "x-api-key: $TELGEA_API_KEY"

{
  "userId": "9c1f2a6e-3b7d-4e0a-8f21-5d6c7b8a9e01",
  "email": "[email protected]",
  "firstName": "Anna",
  "lastName": "Holm",
  "status": "ACTIVE",
  "teamId": "2f6b0d3a-8c1e-4a7f-9b2d-1e3c4d5f6a70",
  "terminationScheduledAt": null,
  "localNumber": {
    "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"
    }
  },
  "travelNumber": null
}

Replace a SIM card

Initiates a SIM card replacement (eSIM swap) for a specific number within a user's plan. 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 number inside the cooldown your organization's SIM-swap offering sets, counted from when the number'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/user-plans/{userId} reports the number with sim: null — its state is REPLACING, and SIM details are published only in READY 3. Back in READY, the number'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.

Scopes: numbers:replace-sim and user-plans:read — the number is checked against the addressed user's plan before any replacement is started.

Requires the permissions numbers:replace-sim and user-plans:read 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/user-plans/9c1f2a6e-3b7d-4e0a-8f21-5d6c7b8a9e01/sim-replacement" \
  -H "x-api-key: $TELGEA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "numberId": "8238c1b9-c2c0-4455-9b03-4bd787052709"
}'

{
  "status": "accepted"
}

Stop a customer's mobile data

Stops mobile data for one of your customers — for someone 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.

Not every market offers stopping data on its own. 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/user-plans/9c1f2a6e-3b7d-4e0a-8f21-5d6c7b8a9e01/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 customer's mobile data

Undoes a stop made with POST /v1/user-plans/{userId}/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/user-plans/9c1f2a6e-3b7d-4e0a-8f21-5d6c7b8a9e01/data-restriction" \
  -H "x-api-key: $TELGEA_API_KEY"

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

Suspend a customer's number

Stops all traffic on one of a customer's numbers, 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 200 means the service is genuinely stopped.

Suspending a number 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

Request body

Responses

Problems this endpoint can return

curl -X POST "https://api.telgea.com/v1/user-plans/9c1f2a6e-3b7d-4e0a-8f21-5d6c7b8a9e01/suspension" \
  -H "x-api-key: $TELGEA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "numberId": "8238c1b9-c2c0-4455-9b03-4bd787052709"
}'

{
  "numbers": [
    "+4520123456"
  ]
}

Restore a customer's number

Undoes a suspension made with POST /v1/user-plans/{userId}/suspension, and returns once the line is live again at the network.

Restoring a number 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/user-plans/9c1f2a6e-3b7d-4e0a-8f21-5d6c7b8a9e01/suspension" \
  -H "x-api-key: $TELGEA_API_KEY"

{
  "numbers": [
    "+4520123456"
  ]
}

End a customer's plan

Ends the customer's line on the date you name — the date they 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/user-plans/{userId} 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.

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/user-plans/9c1f2a6e-3b7d-4e0a-8f21-5d6c7b8a9e01/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"
  ]
}