---
title: "Replace a SIM card"
method: POST
path: "/v1/user-plans/{userId}/sim-replacement"
tags: ["User Plans"]
---

# Replace a SIM card

`POST /v1/user-plans/{userId}/sim-replacement`

## Request

- Base URL: `https://api.telgea.com`
- URL: `https://api.telgea.com/v1/user-plans/{userId}/sim-replacement`
- Auth: API key in header `x-api-key`

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.

## Path parameters

- `userId` string, uuid, required: UUID of the user whose plan this is.

## Headers

- `idempotency-key` string: A value unique to this request, of 1 to 255 printable ASCII characters — a UUID is the usual choice. Retry with the same key within 24 hours and you get the original response back, even if it was a failure, and nothing is done twice. Send a new key whenever you change the request. Keys are private to your API key and organisation.

## Request body

- ReplaceSimBody
  - `numberId` string, uuid, required: UUID of the number to replace the SIM for. Obtain from the user plan details endpoint (localNumber.id or travelNumber.id).

## Response `202`

SIM replacement request accepted and processed asynchronously. Poll GET /v1/user-plans/{userId} until the number is READY again with its new SIM.

- ReplaceSimResponse
  - `status` string, required: Status of the SIM replacement request

## 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 replace SIM cards
- `404`: User plan or number not found
- `429`: The number's last SIM replacement finished too recently for another: your organization's SIM-swap offering sets the cooldown (a German number is replaced once per calendar day), and `Retry-After` says when to retry. The same status also answers a key that has used its request quota.
- `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)