Version: v2.0

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"
}
}
}

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 proccess 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.

Connect SDK or Direct Install#

Either using our SDKs or via direct eUICC API integration you can use the API information to trigger a local install. Just like in the QRCode method, you need the smdp url and the matching id values to trigger the installation process. Get in touch with your Truphone account manager to learn more about our SDKs.