Skip to main content

Getting a new eSIM

How to order an eSIM profile with a product via Connect and install it on a device.

1. Placing the Order​

The first step to get a new eSIM is to place an order through Connect's order API. The order request will include the ID of the product that will be activated via the order, check the Product Catalogue guide in order to understand how to access the product catalogue.

Example Request​

curl -X POST \
  https://services.truphone.com/connect-api/v2/orders \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-Correlation-ID: unique-id-from-requester-123' \
  -d '{
      "operation_type": "ACTIVATION",
      "sim_type": "ESIM",
      "country": "GB",
      "product": {
        "id": "kn8etk9XBX0gG7pFP5KErXvWVNN4jOERTMVMNEkX-Ak="
      },
      "subscriber": {
        "email": "john@doe.com",
        "first_name": "John",
        "last_name": "Doe",
        "country_of_residence": "US",
        "device": {
          "operating_system": "ios",
          "model": "iPhone",
          "id": "1234567"
        }
      }
}'

Example Response​

{
  "id": "6d41c4ff-1877-4d13-82b0-7dad02c4b02a",
  "status": "ACCEPTED",
  "created_date": "2020-01-01T00:00:00Z",
  "_metadata": {
    "_links": {
      "_self": "{BASE_URL}/v2/orders/6d41c4ff-1877-4d13-82b0-7dad02c4b02a"
    }
  }
}

When placing an order you can set a customised activation and expiration date. If no activation date has been provided, the subscription will be created and activated automatically. On the other hand, if no expiration date has been provided, the subscription will be calculated based on the duration of the plan. Note that this expiration date cannot be longer than the duration of the selected plan and that making it shorter will not change any other plan settings, such as price or data allowance.

2. Checking the Order status​

Order fulfilment is not synchronous, so after placing an order, the order status needs to be periodically checked until completion using a polling mechanism. For this your code can use the order API or just use the metadata links available in the response from order creation. You can fin the full list of order status here.

Example Request​

curl -X GET \
  https://services.truphone.com/connect-api/v2/orders/3a6acf89-1ccf-4611-9424-453930f57ef1 \
   -H "Authorization: Bearer $ACCESS_TOKEN" \
   -H 'Cache-Control: no-cache' \
   -H 'Content-Type: application/json' \
   -H 'X-Correlation-ID: unique-id-from-requester-123'

Example Response​

{
  "id": "6d41c4ff-1877-4d13-82b0-7dad02c4b02a",
  "status": "COMPLETED",
  "created_date": "2021-02-24T09:00:00Z",
  "output": {
    "matching_id": "6C-DA326D-K86D",
    "iccid": "8944000013283712983321",
    "subscription_id": "Q-hzHc6EErZPQcgw2L02_nDdruGtr6lDrM-jmja_xuE="
  },
  "_metadata": {
    "links": {
      "_lpa": "1$rsp.truphone.com$6C-DA326D-K86D",
      "_sim": "{BASE_URL}/v2/sims/8944000013283712983321",
      "_qrcode": "https://services.truphone.com/connect/qrcode/v1/esim/LPA:1$rsp.truphone.com$FDSAA-ASD",
      "_smdp": "rsp.truphone.com",
      "_subscription": "{BASE_URL}/v2/subscription/Q-hzHc6EErZPQcgw2L02_nDdruGtr6lDrM-jmja_xuE=",
      "_self": "{BASE_URL}/v2/orders/6d41c4ff-1877-4d13-82b0-7dad02c4b02a"
    }
  }
}

3. Installing the eSIM​

As soon as the order is completed, there are currently 3 options for installing the eSIM profile:

QRCode​

There is a couple of different ways of generating a QRCode to install the eSIM profile

QRCode Image​

You can use the image generated in the order status request included in the _qrcode parameter. These URLs are public so they can be directly referenced from your code e.g. in a img tag in html. Below there is an example of the output of the URL.

Point your eSIM enabled smartphone to the image to try it out

NOTE: The above QRCode triggers the installation process but doesn't point to an actual eSIM profile

LPA url​

If you require an extra level of control, the API already provides the _lpa parameter, this is the string that needs to be encoded in a QRCode, or that can be passed to a mobile OS LPA API in case of a direct integration. This is the string that is recognizable by the target device to start the installation process in mobile platforms.

Build it yourself​

Ultimately, the API provides the smdp url in _smdp (always rsp.truphone.com) and the matching id matching_id which are used to generate a lpa url and respective QRCode. The final string used to generate the QRCode should be as follows:

LPA:1${SMDP_URL}${MATCHINGID}

Push Install (iOS only)​

By providing the EID of the target device as described in the example request, Connect is able to trigger a request which will display a push notification in the target device to trigger the installation.

Note: If you have an iOS device and wish to use the push install feature (More details below), you need to specify device.eid field. If the device.type is not ios, the device.eid field is ignored.