SimSwapSubscription

Overview

• Method: POST
• Endpoint: /api/SimSwapSubscription
• Description: Replaces the SIM card for an existing subscription, allowing for a switch between a physical SIM and an eSIM or vice versa.

POST /api/SimSwapSubscription
Content-Type: application/json
{
    "subscriptionId": "###3Vp17###7Xg79e",
    "phoneNumber": "06-######969",
    "eSim": true,
    "email": "customer@example.com",
    "confirmationCode": "8E9!#"
}

---

Request Body Parameters

The request body should be a JSON object with the following structure:

• subscriptionId (string, required if phoneNumber is not provided): Identifier for the subscription that requires a SIM swap.
• phoneNumber (string, required if subscriptionId is not provided): Phone number associated with the subscription.
• referenceNumber (string, optional, max 15 characters): Internal reference number for tracking.
• newSimCardNumber (string, required for physical SIM swaps): The number of the new SIM card.
• eSim (boolean, optional): Indicates whether the new SIM is an eSIM.
• email (string, required if eSim is true): Email address for eSIM delivery.
• confirmationCode (string max 10, required for eSIM swaps): A custom code that the customer will need to enter during eSIM installation.

Warning

• If both newSimCardNumber and esim=true are provided, the request will be handled as an eSIM swap.
• For eSIM swaps, the customer will receive an email with a QR code for installation and will be required to enter the confirmationCode during setup. This confirmation code must be provided separately by your system.

---

Response Structure

The response will return an Activation object with the following details:

{
    "id": "###XCksM###YNCiKI",
    "createdAt": "2025-02-03T14:38:50.707+01:00",
    "modifiedAt": "2025-02-03T15:10:55.098+01:00",
    "status": "BUSY",
    "activationType": "SIMSWAP",
    "referenceNumber": "",
    "subscriptionId": "###3Vp17###7Xg79e",
    "phoneNumber": "06-######969",
    "activatedDate": "2025-02-03T16:06:50+01:00",
    "info": {
        "eSim": true,
        "email": "customer@example.com",
        "confirmationCode": "##########"
    }
}

Field Descriptions

• id: A unique identifier for the SIM swap request.
• status: The current status of the SIM swap request:
  • BUSY: The request is being processed.
  • DONE: The SIM swap was successfully completed.
  • ERROR: The request failed.
• activationType: Always SIMSWAP for this request.
• subscriptionId: The ID of the subscription undergoing the SIM swap.
• phoneNumber: The phone number associated with the subscription.
• info: Additional metadata related to the swap request.

Info

Optional fields included in the request will be reflected in the response.

---

Usage Notes

• This API replaces the SIM card for an active subscription.
• Either subscriptionId or phoneNumber must be provided.
• For physical SIM swaps, specify newSimCardNumber.
• For eSIM swaps, set esim=true and provide email.
• The confirmationCode is required for eSIM swaps and must be shared separately with the customer.
• The response includes a unique id for tracking the SIM swap request.

---

Querying SIM Swap Status

Simswap to eSim:

POST /api/SimSwapSubscription
Content-Type: application/json
{
    "subscriptionId": "###3Vp17###7Xg79e",
    "eSim":true,
    "email": "customer@example.com",
    "confirmationCode":"1234567890"
}

The response will look like:

{
    "id": "###XCksM###YNCiKI",
    "createdAt": "2025-02-03T14:38:50.7076242+01:00",
    "modifiedAt": "2025-02-03T14:38:50.7076242+01:00",
    "status": "INIT",
    "activationType": "SIMSWAP",
    "referenceNumber": "",
    "subscriptionId": "###3Vp17###7Xg79e",
    "phoneNumber": "06-#####969",
    "info": {
        "eSim": true,
        "email": "customer@example.com",
        "confirmationCode": "1234567890"
    }
}

To get the current status of the SimSwapSubscription you perform a QueryActivation request:

GET /api/QueryActivation?id=###XCksM###YNCiKI

Example Response:

{
    "offset": 0,
    "total": 79,
    "results": [
        {
            "id": "###XCksM###YNCiKI",
            "createdAt": "2025-02-03T14:38:50.707+01:00",
            "modifiedAt": "2025-02-03T14:38:56.071+01:00",
            "status": "BUSY",
            "activationType": "SIMSWAP",
            "referenceNumber": "",
            "subscriptionId": "###3Vp17###7Xg79e",
            "providerOrderNumber": "03####0/2##5",
            "phoneNumber": "06-#####969",
            "info": {
                "eSim": true,
                "email": "customer@example.com",
                "confirmationCode": "1234567890"
            }
        }
    ],
    "meta": {}
}

After the eSIM has been installed, request QueryActivation again to confirm completion:

GET /api/QueryActivation?id=###XCksM###YNCiKI

Updated Response:

{
    "offset": 0,
    "total": 79,
    "results": [
        {
            "id": "###XCksM###YNCiKI",
            "createdAt": "2025-02-03T14:38:50.707+01:00",
            "modifiedAt": "2025-02-03T15:10:55.098+01:00",
            "status": "DONE",
            "activationType": "SIMSWAP",
            "referenceNumber": "",
            "providerOrderNumber": "03####0/2##5",
            "subscriptionId": "###3Vp17###7Xg79e",
            "phoneNumber": "06-#####969",
            "activatedDate": "2025-02-03T16:06:50+01:00",
            "info": {
                "eSim": true,
                "email": "customer@example.com",
                "confirmationCode": "1234567890"
            }
        }
    ],
    "meta": {}
}

---

Summary

The /api/SimSwapSubscription endpoint facilitates SIM swaps for active subscriptions, including physical and eSIM replacements.

• Requires either a subscriptionId or phoneNumber to identify the subscription.
• Physical SIM swaps require newSimCardNumber.
• eSIM swaps require esim=true, email, and confirmationCode.
• Returns a unique id for tracking the swap request.
• The SIM swap status can be queried using QueryActivation.

Use this API to manage SIM replacements efficiently.