SOTEL
Sotel eSIMs API simplifies eSIM management by enabling businesses to activate, provision, and switch eSIMs across global networks. This API allows fintechs, banks, travel agencies, tourism companies, and aviation firms to seamlessly offer eSIMs to their customers, providing a streamlined and scalable global connectivity experience.
Authenticating your API calls
Key Encryption
This service allows you to generate a bearer token that will be used in authenticating your API calls to Sotel. It expects a string of your 'Live API Key' in a JSON request. Sotel in turn returns the bearer token in the encrytedKey field. See sample request and response below:
Endpoint : https://api.termii.com/api/esim/authenticate
Request Type : POST
Request Sample
curl --location 'https://api.termii.com/api/esim/authenticate' \ --header 'Content-Type: application/json' \ --data '{ "api_key":"YOUR_LIVE_API_KEY" }'
Response
{
"token": "eyJhbGciOiJIUzUxMiJ9.eyJhcHAiOjEsInN1YiI6MSwiY291bnRyeSI6Ik5pZ2VyaWEiLCJjcmVhdGVkIjoxNzI4Mzk1OTU5NjE5LCJpc3MiOjEsImFkbWluIjoxLCJncmFudCI6IiIsImV4cCI6MTcyODQ4MjM1OSwiaWF0IjoxNzI4Mzk1OTU5LCJlbWFpbCI6ImFkZW9sYS5lbGVnYmVkZUB0ZXJtaWkuY29tIn0.q6Whz1g4NISj4gdAtpbECWK_XsaSv005U2zg0sL6cKEmWVlWEXg0sRDiX1cmjOhwb5eJC7am_6XiLHI-Ow22YQ"
}
Get Data Plan
When Subscribing to a new product plan or creating a new eSIM, the Product ID must be included in the request body. You can query product plans specific to a country or region by using this endpoint, filtering by country and region. Sotel will return a list of all available product plans for the specified country or region. Alternatively, if no country or region is provided in the query parameters, the endpoint will return a list of all available product plans globally. See sample request and response below:
Endpoint : https://api.termii.com/api/esim/data/plan/all
Request Type : GET
Request Sample
The code snippet below shows an example request to get list of products
curl --location 'https://api.termii.com/api/esim/data/plan/all?country=Nigeria®ion=Africa' \ --header 'X-Token: bearer-token' \'
Response
{
"content": [
{
"id": 1359,
"uuid": "9668cdc1-1de9-46b5-b524-464641f3b25b",
"active": true,
"version": 0,
"createdAt": "2024-10-19 17:09:08",
"updatedAt": "2024-10-19 17:09:08",
"productId": "66b5db0b899f794eccc7ff55",
"name": "Latin America Bundle-1 GB 5 Days",
"dataUsageAllowance": 1.0,
"timeAllowance": 5.0,
"country": "Paraguay",
"countryIso3": "PRY",
"region": "South America",
"dataPlanType": "REGION"
},
{
"id": 1358,
"uuid": "ff8d0ab1-112f-4a2b-973a-a8c5695db48a",
"active": true,
"version": 0,
"createdAt": "2024-10-19 17:09:08",
"updatedAt": "2024-10-19 17:09:08",
"productId": "66b5db0b899f794eccc7fee7",
"name": "Europe Bundle-1 GB 5 Days",
"dataUsageAllowance": 1.0,
"timeAllowance": 5.0,
"country": "Sweden",
"countryIso3": "SWE",
"region": "Europe",
"dataPlanType": "REGION"
},
{
"id": 1356,
"uuid": "7242deac-e91d-4ea3-99d6-a38bdde118ce",
"active": true,
"version": 0,
"createdAt": "2024-10-19 17:09:08",
"updatedAt": "2024-10-19 17:09:08",
"productId": "66b5db0b899f794eccc7ff98",
"name": "Middle East Bundle 2-10 GB 30 Days",
"dataUsageAllowance": 10.0,
"timeAllowance": 30.0,
"country": "Iran",
"countryIso3": "IRN",
"region": "Middle East",
"dataPlanType": "REGION"
},
{
"id": 1357,
"uuid": "6aec07c2-f07c-4e52-84a4-6a27e3a3a22b",
"active": true,
"version": 0,
"createdAt": "2024-10-19 17:09:08",
"updatedAt": "2024-10-19 17:09:08",
"productId": "66b5db0b899f794eccc7ff44",
"name": "Kuwait-3 GB 7 Days",
"dataUsageAllowance": 3.0,
"timeAllowance": 7.0,
"country": "Kuwait",
"countryIso3": "KWT",
"region": "Middle East",
"dataPlanType": "DESTINATION"
},
{
"id": 1355,
"uuid": "3a900379-93fe-4999-aed4-aae68316fa71",
"active": true,
"version": 0,
"createdAt": "2024-10-19 17:09:08",
"updatedAt": "2024-10-19 17:09:08",
"productId": "66b5db0b899f794eccc7fe99",
"name": "Colombia-1 GB 5 Days",
"dataUsageAllowance": 1.0,
"timeAllowance": 5.0,
"country": "Colombia",
"countryIso3": "COL",
"region": "South America",
"dataPlanType": "DESTINATION"
},
{
"id": 1354,
"uuid": "3d8f5d68-5032-457c-aa9d-0792adb6e01c",
"active": true,
"version": 0,
"createdAt": "2024-10-19 17:09:08",
"updatedAt": "2024-10-19 17:09:08",
"productId": "66b5db0b899f794eccc8001e",
"name": "Oceania Bundle-3 GB 7 Days",
"dataUsageAllowance": 3.0,
"timeAllowance": 7.0,
"country": "Australia",
"countryIso3": "AUS",
"region": "Oceania",
"dataPlanType": "REGION"
},
{
"id": 1353,
"uuid": "d85249e6-4a64-4ff4-b6e5-1497c87054d6",
"active": true,
"version": 0,
"createdAt": "2024-10-19 17:09:07",
"updatedAt": "2024-10-19 17:09:08",
"productId": "66b5db0b899f794eccc7fefc",
"name": "Europe Bundle-3 GB 7 Days",
"dataUsageAllowance": 3.0,
"timeAllowance": 7.0,
"country": "Ukraine",
"countryIso3": "UKR",
"region": "Europe",
"dataPlanType": "REGION"
},
{
"id": 1352,
"uuid": "a5a2ba2c-a384-41ae-9e98-1b6973f8b111",
"active": true,
"version": 0,
"createdAt": "2024-10-19 17:09:07",
"updatedAt": "2024-10-19 17:09:07",
"productId": "66b5db0b899f794eccc7ff52",
"name": "Isle of Man-1 GB 5 Days",
"dataUsageAllowance": 1.0,
"timeAllowance": 5.0,
"country": "Isle of Man",
"countryIso3": "IMN",
"region": "Europe",
"dataPlanType": "DESTINATION"
},
{
"id": 1350,
"uuid": "34018cad-f697-4a75-b3dd-8405ebf5387f",
"active": true,
"version": 0,
"createdAt": "2024-10-19 17:09:07",
"updatedAt": "2024-10-19 17:09:07",
"productId": "66b5db0b899f794eccc7fe34",
"name": "Algeria-10 GB 30 Days",
"dataUsageAllowance": 10.0,
"timeAllowance": 30.0,
"country": "Algeria",
"countryIso3": "DZA",
"region": "Africa",
"dataPlanType": "DESTINATION"
},
{
"id": 1351,
"uuid": "c00854d4-4ea3-40aa-89c1-d8c7ae19e196",
"active": true,
"version": 0,
"createdAt": "2024-10-19 17:09:07",
"updatedAt": "2024-10-19 17:09:07",
"productId": "66b5db0b899f794eccc8000e",
"name": "Middle East Bundle 2-5 GB 15 Days",
"dataUsageAllowance": 5.0,
"timeAllowance": 15.0,
"country": "Tunisia",
"countryIso3": "TUN",
"region": "Africa",
"dataPlanType": "REGION"
},
{
"id": 1349,
"uuid": "35eb4ba4-9204-4901-bdfe-08a06db0ede1",
"active": true,
"version": 0,
"createdAt": "2024-10-19 17:09:07",
"updatedAt": "2024-10-19 17:09:07",
"productId": "66b5db0b899f794eccc7fed6",
"name": "Faroe Islands-5 GB 15 Days",
"dataUsageAllowance": 5.0,
"timeAllowance": 15.0,
"country": "Faroe Islands",
"countryIso3": "FRO",
"region": "Europe",
"dataPlanType": "DESTINATION"
},
{
"id": 1346,
"uuid": "b323fe26-c9de-4ece-a230-9f37147fd619",
"active": true,
"version": 0,
"createdAt": "2024-10-19 17:09:07",
"updatedAt": "2024-10-19 17:09:07",
"productId": "66b5db0b899f794eccc7ff50",
"name": "Kenya-5 GB 15 Days",
"dataUsageAllowance": 5.0,
"timeAllowance": 15.0,
"country": "Kenya",
"countryIso3": "KEN",
"region": "Africa",
"dataPlanType": "DESTINATION"
},
{
"id": 1347,
"uuid": "481d8c1e-2bbb-4463-8a84-f8d1d593badf",
"active": true,
"version": 0,
"createdAt": "2024-10-19 17:09:07",
"updatedAt": "2024-10-19 17:09:07",
"productId": "66b5db0b899f794eccc7fe30",
"name": "Asia Bundle 2-5 GB 15 Days",
"dataUsageAllowance": 5.0,
"timeAllowance": 15.0,
"country": "China",
"countryIso3": "CHN",
"region": "Asia",
"dataPlanType": "REGION"
},
{
"id": 1348,
"uuid": "80d90fa1-05bc-4086-be69-81ee6576ca06",
"active": true,
"version": 0,
"createdAt": "2024-10-19 17:09:07",
"updatedAt": "2024-10-19 17:09:07",
"productId": "66b5db0b899f794eccc7ffaf",
"name": "Latin America Bundle-5 GB 15 Days",
"dataUsageAllowance": 5.0,
"timeAllowance": 15.0,
"country": "Costa Rica",
"countryIso3": "CRI",
"region": "Central America",
"dataPlanType": "REGION"
},
{
"id": 1344,
"uuid": "70b58702-2c40-4d83-b705-12d46d195cdc",
"active": true,
"version": 0,
"createdAt": "2024-10-19 17:09:07",
"updatedAt": "2024-10-19 17:09:07",
"productId": "66b5db0b899f794eccc7fe68",
"name": "Cameroon-5 GB 15 Days",
"dataUsageAllowance": 5.0,
"timeAllowance": 15.0,
"country": "Cameroon",
"countryIso3": "CMR",
"region": "Africa",
"dataPlanType": "DESTINATION"
}
],
"pageable": {
"pageNumber": 0,
"pageSize": 15,
"sort": {
"sorted": true,
"empty": false,
"unsorted": false
},
"offset": 0,
"paged": true,
"unpaged": false
},
"last": false,
"totalElements": 1359,
"totalPages": 91,
"first": true,
"size": 15,
"number": 0,
"sort": {
"sorted": true,
"empty": false,
"unsorted": false
},
"numberOfElements": 15,
"empty": false
}
Create eSIM
To provision an eSIM, the business must include the Product ID in the request payload. The Product ID represents the specific eSIM product the customer wishes to subscribe to. Upon successful provisioning, Sotel will return all relevant information, including the ICCID of the newly provisioned eSIM, along with other necessary details. See sample request and response below:
Endpoint : https://api.termii.com/api/esim/create
Request Type : POST
Request Sample
The code snippet below shows an example request to create a new eSIM
curl --location 'https://api.termii.com/api/esim/create' \
--header 'Content-Type: application/json' \
--header 'X-Token: bearer-token' \'
--data '{
"productId": "66b5db0b899f794eccc7ff50",
"iso3": "KEN"
}'
Response
{
"sim": {
"id": 6,
"iccid": "8910300000025420282",
"productId": "66b5db0b899f794eccc7ff50",
"imsi": "260012161254922",
"state": "RELEASED",
"lastOperationDate": "2024-10-02 08:51:35",
"activationCode": "TN20241001174236A10DF7B2",
"smdp": "consumer.e-sim.global"
},
"dataPlan": {
"productId": "66b5db0b899f794eccc7ff50",
"name": "Kenya-5 GB 15 Days",
"dataUsageAllowance": 5.0,
"timeAllowance": 15.0,
"country": "Kenya",
"iso3": "KEN",
"region": "Africa"
}
}
Get QR Code
To activate an eSIM that has been created, you can either activate with your QR Code or with the activation code sent in the response payload as at the time the eSIM was created. The Get QR Code allows you to fetch the QR Code for an eSIM that has already been created.
Endpoint : https://api.termii.com/api/esim/activate/{ICCID}/qr/code
Request Type : GET
Request Sample
The code snippet below shows an example request to get QR Code on an eSIM that has been created
curl --location 'https://api.termii.com/api/esim/activate/8910300000022866726/qr/code' \
--header 'X-Token: eyJhbGciOiJIUzUxMiJ9.eyJhcHAiOjEsInN1YiI6MSwiY291bnRyeSI6IlVuaXRlZCBTdGF0ZXMiLCJjcmVhdGVkIjoxNzI5Njk4NzI0NDQwLCJpc3MiOjIsImFkbWluIjoxLCJncmFudCI6IiIsImV4cCI6MTcyOTc4NTEyNCwiaWF0IjoxNzI5Njk4NzI0LCJlbWFpbCI6InRlY2hAdGVybWlpLmNvbSJ9'
Create Product Subscription
To subscribe an existing eSIm to a new product plan, the business must provide the customer’s ICCID and **Product ID ** in the request payload. This ensures the new subscription is applied to the correct eSIM associated with the provided ICCID. Upon successful subscription, Sotel will return all relevant details, including information about the newly activated plan. See sample request and response below:
Endpoint : https://api.termii.com/api/esim/data/plan/subscribe
Request Type : POST
Request Sample
The code snippet below shows an example request to subscribe to a new product for an existing eSIM
curl --location 'https://api.termii.com/api/esim/data/plan/subscribe' \
--header 'Content-Type: application/json' \
--header 'X-Token: bearer-token' \'
--data '{
"product":"66b5db0b899f794eccc7fff7",
"iccid":"8910300000022866726",
"iso3":"NGA"
}'
Response
{
"sim": {
"id": null,
"iccid": "8910300000022866726",
"productId": "66b5db0b899f794eccc7fff7",
"imsi": "310840106056290",
"state": "RELEASED",
"lastOperationDate": "2024-07-05 06:53:19",
"activationCode": "TN20240704143141ACE8B480",
"smdp": "consumer.e-sim.global"
},
"dataPlan": {
"productId": "66b5db0b899f794eccc7fff7",
"name": "Nigeria-5 GB 15 Days",
"dataUsageAllowance": 5.0,
"timeAllowance": 15.0,
"country": "Nigeria",
"iso3": "NGA",
"region": "Africa"
}
}
Get euICCID Profile
To retrieve details for a specific ICCID, the business must include the customer’s ICCID in the request payload. Sotel will return all relevant information associated with the eSIM, including the profile details and other necessary data. See sample request and response below:
Endpoint : https://api.termii.com/api/esim/euicc/{ICCID}
Request Type : GET
Request Sample
The code snippet below shows an example request to get profile of a particular eSIM
curl --location 'https://api.termii.com/api/esim/euicc/8910300000022866725' \
--header 'X-Token: eyJhbGciOiJIUzUxMiJ9..T0FUYi5l'
Response
{
"iccid": "8910300000022866725",
"imsi": "310840106056289",
"state": "RELEASED",
"last_operation_date": 1729697176897,
"reuse_remaining_count": 5,
"cc_required": false,
"release_date": 1720162399239,
"activationCode": "TN2024070414314",
"smdp": "consumer.e-sim.global"
}
Get Data Usage
To retrieve data usage details for a specific ICCID, the business must include the customer’s ICCID and the existing Product ID in the request payload. Sotel will return all relevant information, including the total data used out of the total data purchased. See sample request and response below:
Endpoint : https://api.termii.com/api/esim/subscriptions/usage/{ICCID}
Request Type : GET
Request Sample
The code snippet below shows an example request to get data usage for a particular eSIM
curl --location --request GET 'https://api.termii.com/api/esim/subscriptions/usage/8910300000015900472' \
--header 'Content-Type: application/json' \
--header 'X-Token: bearer-token'
Response
{
"data_total_gigabyte": 5.0,
"data_used_gigabyte": 5.0
}
Get List of eSIMs Created
To retrieve a list of eSIMs created by a business, the business must include their Termii API Key in the request payload. Sotel will return the list of all eSIMs created by the business including all relevant information of the data plan for each eSIM See sample request and response below:
Endpoint : https://api.termii.com/api/esim/fetch/esims
Request Type : GET
Request Sample
The code snippet below shows an example request to get list of eSIMs created by a business
curl --location 'https://api.termii.com/api/esim/fetch/esims?page=0&size=15' \
--header 'X-Token: eyJhbGciOiJIUzUxMiJ9..'
Response
{
"content": [
{
"id": 3,
"iccid": "8910300000022866727",
"productId": "66b5db0b899f794eccc7fdfb",
"imsi": "310840106056291",
"state": "RELEASED",
"lastOperationDate": "2024-07-05 06:53:19",
"activationCode": "TN202407041431417E8E3073",
"smdp": "consumer.e-sim.global"
},
{
"id": 2,
"iccid": "8910300000022866726",
"productId": "66b5db0b899f794eccc7fdfb",
"imsi": "310840106056290",
"state": "RELEASED",
"lastOperationDate": "2024-07-05 06:53:19",
"activationCode": "TN20240704143141ACE8B480",
"smdp": "consumer.e-sim.global"
},
{
"id": 1,
"iccid": "8910300000022866725",
"productId": "66b5db0b899f794eccc7fdfb",
"imsi": "310840106056289",
"state": "RELEASED",
"lastOperationDate": "2024-07-05 06:53:19",
"activationCode": "TN2024070414314198333481",
"smdp": "consumer.e-sim.global"
}
],
"pageable": {
"pageNumber": 0,
"pageSize": 15,
"sort": {
"sorted": true,
"empty": false,
"unsorted": false
},
"offset": 0,
"paged": true,
"unpaged": false
},
"last": true,
"totalElements": 3,
"totalPages": 1,
"first": true,
"size": 15,
"number": 0,
"sort": {
"sorted": true,
"empty": false,
"unsorted": false
},
"numberOfElements": 3,
"empty": false
}