API: eUICC profile localization
An eSIM is a particular SIM able to host and enable multiple SIM profiles – each profile comprising of the operator and subscriber data that would have otherwise been stored on a traditional SIM card - even belonging to different operators and to switch to one to another. It is like having multiple virtual SIMs
A bootstrap profile, a sort of default profile, is always initially present on the eUICC just to allow fetching and activating a commercial profile, that will enable the end-user to make traffic and be charged accordingly
The term “localization” is used in IoTA to refer to the remote provisioning procedure that brings an eUICC to download, activate and switch through various profiles: from the bootstrap profile to a commercial profile of a given operator, between commercial profiles of two different operators or rollback from a commercial profile to the bootstrap (namely “delocalization”).
The present document provides instructions to configure and bring an eUICC SIM from a bootstrap profile to a commercial profile, just using a subset of APIs of the wider localization API group of IoTA.
Preconditions: You should know your eUICCId (defined into the IoTA inventory in advance) and the IoTA account login credentials belonging to it.
Your device shall be switched on with the eUICC inside it.
The API calls can be implemented and fired from any REST client: here the Developer Portal swagger page will be used.
The entire localization procedure via API goes through a given logical order, that will be detailed in the next sections.
- Reach the localization API swagger web page
- Get the API token in order to authenticate the next coming API calls
- Query the current eUICC profile and retrieve some necessary parameters
- Kick out the localization process
- Query the new actual eUICC Profile
Since the token lasts 60s, step 2 might be repeated any time just before firing the next API call.
1. Reach the Localization page
1.1 Go to the Localization API swagger page of the Developer Portal and scroll down to reach the login-form API.
2. Get the API token
2.1 Click on that line to expand the structure and syntax of that API
2.2 Click now on the "Try-Out" button to reveal the fields that shall be filled with the credentials belonging to your eUICC account
2.3 Add your credentials (username/password) to those empty fields
2.4 Push the "Execute" button
2.5 Control that the API response returned a token. That token will be automatically inserted by the swagger in any further API call sent within 1 minute.
3. Query the current profile
3.1 Point now the GET /euiccs/{id} API and click on it to expand the panel
3.2 Click on the "Try-out" button
3.3 Add the eUICC id
3.4 Press the "Execute" button
3.5 Check that you get back a response that looks like in this example and take note of the values in correspondence of the attributes green highlighted.
The actual Id under the locale list shall correspond to one of the actual destination Commercial Profiles that are available for your eUICC for the target localization.
Verify that the eUICC state is “Unlocalized” because still in the bootstrap profile
{
"subscriptions": [
{
"imsi": "1234567890",
"state": "ACTIVE_NO_BILLING",
"operatorId": "01010101",
"operatorName": "Operator1",
"msisdn": "1234567890",
"iccid": "1234567890",
"localeList": [
{
"id": "Switzerland2",
"name": "Operator1 CSP01"
}
]
},
{
"imsi": "1234567890",
"state": "ACTIVE_NO_BILLING",
"operatorId": "010101",
"operatorName": "Telia Company",
"msisdn": "1234567890",
"iccid": "1234567890",
"localeList": [
{
"id": "SW2",
"name": "Sweden SP2"
},
{
"id": "SW1",
"name": "Sweden SP1"
},
{
"id": "SW3",
"name": "Sweden SP3"
}
]
},
{
"imsi": "1234567890",
"state": "ACTIVE",
"operatorId": "010101",
"operatorName": "Telia Company",
"msisdn": "1234567890",
"iccid": "1234567890",
"localeList": []
}
],
"euiccId": "89033023311330000000000XXXXXX",
"companyId": "06XXXXXX",
"companyName": "DCP Trial Fifteen",
"state": "UNLOCALIZED",
"label": "BLAB_Rome",
"localeName": null,
"bootstrapIcc": "1234567890",
"enabledIcc": "1234567890",
"bootstrapCompanyId": "06000384",
"localizationTableId": 10786
}4. Kick out the Localization process
If the token expired then repeat step 2 firing another /login-form API call:
4.1 Look for POST/euiccs/{id}/localization API click on it to expand the panel
4.2 Click on the "Try-out" button
4.3 Copy and paste the three values of the attributes noted in the previous step
4.4 Press the "Execute" button
4.5 Check the response just like:
{
"serviceRequestId": "REQ200157881224",
"success": true
}
5. Query the new actual eUICC Profile
5.1 Point now the GET /euiccs/{id} API and click on it to expand the panel
5.2 Click on the "Try-out" button
5.3 Add the eUICC id
5.4 Press the "Execute" button
The response returned should carry now the state changed to “Localized”:
{
"subscriptions": [
{
"imsi": "1234567890",
"state": "ACTIVE_NO_BILLING",
"operatorId": "010101",
"operatorName": "Operator1",
"msisdn": "1234567890",
"iccid": "1234567890",
"localeList": [
{
"id": "Switzerland2",
"name": "Operator1 CSP01"
}
]
},
{
"imsi": "1234567890",
"state": "ACTIVE",
"operatorId": "010101",
"operatorName": "Telia Company",
"msisdn": "1234567890",
"iccid": "1234567890",
"localeList": [
{
"id": "SW2",
"name": "Sweden SP2"
},
{
"id": "SW1",
"name": "Sweden SP1"
},
{
"id": "SW3",
"name": "Sweden SP3"
}
]
},
{
"imsi": "1234567890",
"state": "ACTIVE_NO_BILLING",
"operatorId": "010101",
"operatorName": "Telia Company",
"msisdn": "1234567890",
"iccid": "1234567890",
"localeList": []
}
],
"euiccId": "89033023311330000000000XXXXXX",
"companyId": "06XXXXX",
"companyName": "DCP Trial Fifteen",
"state": "LOCALIZED",
"label": "BLAB_Rome",
"localeName": "Sweden SP1",
"bootstrapIcc": "1234567890",
"enabledIcc": "1234567890",
"bootstrapCompanyId": "06XXXXXX",
"localizationTableId": 10786
}