Skip to main content

Replace a SIM

Preview

To replace the SIM associated with an existing subscription, submit an order request using Orders API. This allows organizations to o change the SIMs from physical SIM to eSIM seamlessly.

[!NOTE]
This documentation covers the preview version of the Orders API. Please note that this preview API is provided for early access to new features and for feedback collection. Therefore, it is not intended for use in a production environment.

How it works​

To swap the SIM from to eSIM, perform the below steps

Submit a Change SIM Profile Request​

Send a POST request to the Submit an Order, to create the order subscription.. This request includes all necessary parameters to define the current subscription and the new SIM profile details.

POST https://api.1global.com/enterprise/orders

The request body includes the necessary details in a JSON payload structure. Specify the typeas change_sim_profile.

curl -X POST \
  https://api.1global.com/enterprise/orders \
   -H 'Authorization: Bearer $ACCESS_TOKEN' \
   -H 'Content-Type: application/json' \
   -d --data @body.json

Example request body.json: The request body contains all the subscription details required to change the physical SIM to eSIM.

{
    "type": "change_sim_profile",
    "account_id": "acc_01AAAABBE00AAAA8AABAA4R37A",
    "subscription_id": "sub_01AAAA1AA1A11AA1AA1A11196X9",
    "sim_profile": {
        "sim_type": "esim",
        "delivery": {
            "type": "email",
            "to": ["j.doe@star-industries.com"]
        }
    }
}

Example Response​

Upon successful submission, the API responds with an initial order IDand status. The status is marked as pending, indicating the process has started. Refer Order Status for more information.

Example Initial Response:

{
    "id": "order_01HZS5KETGM8XXF53WZJWDDV4C",
    "status": "pending",
    "type": "change_sim_profile",
    "account_id": "acc_01DKVAGTE00ECXW8AYBVB4R37Q",
    "subscription_id": "sub_01DRGT6VG8C79TX5CW1W9696X9",
    "sim_profile": {
        "sim_type": "esim",
        "delivery": {
            "type": "email",
            "to": ["j.doe@stark-industries.com"]
        }
    },
    "_links": {
        "self": {
            "href": "https://api.staging.1global.com/ordering/orders/orders/order_01HZS5KETGM8XXF53WZJWDDV4C"
        }
    }
}

Asynchronous Processing​

The order is processed asynchronously and may require some time to complete. It is required to implement logic to periodically check the order status. Clients should query the status of their order using the Order API status endpoint. Monitor the order status until the order reaches the status=complete.

Example GET Request:

curl -X GET \
  https://api.1global.com/enterprise/orders/order_01HZS5KETGM8XXF53WZJWDDV4C \
   -H 'Authorization: Bearer $ACCESS_TOKEN' \
   -H 'Content-Type: application/json'

[!IMPORTANT]

  • The provisioning actions usually require a few minutes to complete. However, it is possible that occasionally some requests could take longer, depending on resources availability.
  • Upon completion of the order, the previous SIM associated with the subscription is terminated.

Receive New eSIM QR Code​

When the order status transitions to completed the API automatically sends the new eSIM QR code to the specified email addresses - primary email and any ccEmail - provided during the request submission. Upon completion of the SIM provisioning process, you will receive a subscription identifier (subscription_id).

Example Response status=completed

{
    "id": "order_01HZS5KETGM8XXF53WZJWDDV4C",
    "status": "completed",
    "type": "change_sim_profile",
    "account_id": "acc_01DKVAGTE00ECXW8AYBVB4R37Q",
    "subscription_id": "sub_01DRGT6VG8C79TX5CW1W9696X9",
    "sim_profile": {
        "sim_type": "esim",
        "iccid": "8944478100000780801",
        "delivery": {
            "type": "email",
            "to": ["j.doe@stark-industries.com"]
        }
    },
    "_links": {
        "self": {
            "href": "https://api.staging.1global.com/ordering/orders/orders/order_01HZS5KETGM8XXF53WZJWDDV4C"
        }
    }
}

[!IMPORTANT]
Although not likely to happen, the status=cancelled exists to accommodate any unforseen event that makes it impossible to fulfill your request. Your Account Manager can provide you additional info.