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&region=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
}
Updated at, Thursday, October 24, 2024