Getting a new eSIM

1. Placing the Order

The first step you need to do in order to get a fresh new eSIM is to place an order through the order API. It is a pretty straightforward request as described in the example below. Part of the order request is the productId that will be activated via the order, check the Product Catalogue guide in order to understand how to access the right Ids.

Example Request

curl -X POST \  https://services.truphone.com/connect-api/v1/order \  -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 '{        "input": {            "operationType": "NEW_ESIM",            "countryCode": "PT",            "customer": {                "email": "john@doe.com",                "countryOfResidence": "US"            },            "device": {                "id": "123456789",                "model": "iPhone",                "type": "ios"                # Include EID Parameter for Push Install                # "eid": "89001012012341234012345678901224"            },            "subscriptions": [{                "product_id": "cm9kIiwiY2xpZW50QWRkcmVzcyI",                "activationDate": "2019-09-13T12:00:00Z",                "price": 10,                "currency": "USD"            }]        }      }'

Example Response

{  "id": "3a6acf89-1ccf-4611-9424-453930f57ef1",  "externalId": "3a6acf89-1ccf-4611-9424-453930f57ef1",  "status": "ACCEPTED"}

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 (check the full list of order status here)

Example Request

curl -X GET \  https://services.truphone.com/connect-api/v1/order/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

{  "output": {    "matchingId": "5C-M1OIY-QHWKD1",    "iccid": "8944478600000205337",    "smdpUrl": "rsp.truphone.com",    "lpa_url": "LPA:1$%rsp.truphone.com$%5C-M1OIY-QHWKD1",    "qrcode_url": "https://services.truphone.com/connect/qrcode/v1/esim/LPA:1$rsp.truphone.com$FDSAA-ASD",    "subscription_id": "a-5gVXH2sjvICL7U5roet1hMC35UYSCCi4Mbiszdceo=",  },  "status": "COMPLETED",  "externalId": "b27ec0e7-ad36-45ab-8e2f-c291441a2355",  "id": "b27ec0e7-ad36-45ab-8e2f-c291441a2355"}

3. Installing the eSIM

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

QRCode

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

QRCode Image

You can simply use the image generated in the order status request included in the qrcode_url 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_url 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 (always rsp.truphone.com) and the 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 representative to learn more about our SDKs.