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.

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

{
  "status": "accepted"
}