SIM Swap

The SIM swap process (also known as change SIM) allows organizations to replace the SIM associated with an existing subscription, enabling a seamless transition from any xSIM (physical or digital SIM) to an eSIM.

Submit an Order

To initate the swap, send a HTTP POST request to the Create Order endpoint.

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

The header should contain the URL, Request Access Token, and content-type as shown below:

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

In the body.json file, the JSON payload should contain the following parameters:

• type (string, required): Must be "change_sim_profile" for a change sim.
• account_id (string, required): Identifies the account where the change SIM will be triggered.
• subscription_id (string, required): Identifies the subscription which the change SIM will be applied to.
• sim_type (string, required): Must be "esim".
• delivery (object, required): Details about eSIM delivery:
  • type (string, required): Delivery method. Use "email".
  • to (array, required): Recipient email(s) for the eSIM QR code.
  • cc (array, optional): Additional email(s) for the eSIM QR code.

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

Example Response

Upon successful submission, the API returns an order Id and the status pending, indicating that the order processing has begun.

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

Monitor Order Status

Due to asynchronous processing, implement periodic polling to check the order status until it reaches a final state: completed or cancelled. Send a GET request to check the current status of the order.

GET  https://api.1global.com/enterprise/orders/{order_Id}

Replace order_Id with the unique order ID received from the initial response (e.g., order_01HZS5KETGM8XXF53WZJWDDV4C).

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

::: note The provisioning actions usually require a few minutes to complete. However, it is possible that some requests can take longer, depending on resources availability. :::

Example Response

When the order status transitions to completed the API automatically sends the new eSIM QR code to the specified email addresses. This includes the primary emails and any CC email provided during the initial request.

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

note

Upon completion of the order, the previous SIM associated with the subscription will be automatically terminated.