Table of Contents

eSIM Group Search API Documentation

Overview

This API allows searching for eSIM product groups based on providers and a target country code. It returns a list of available eSIM solutions (groups) with details like validity, data allowance, price range, covered countries, and other relevant features.

API Endpoint

  • URL: {{host}}/hub/esim/groups/search
  • Method: POST
  • Content-Type: application/json

Headers

Key Value Description
Authorization Bearer {token} Access token (Required)
Content-Type application/json Request/Response format

Request Body Parameters

Main Parameters

Field Type Required Description Example/Values
providers String ✅ Yes Comma-separated list of provider codes. "esim.provider1"
countryCode String ✅ Yes 2-letter ISO country code for search. "vn"

Sample Request

curl --location '{{host}}/hub/esim/groups/search' \
--header 'Authorization: Bearer {token}' \
--header 'Content-Type: application/json' \
--data '{
    "providers": "esim.provider1",
    "countryCode": "vn"
}'

Sample Response

{
  "solutions": [
    {
      "providerCode": "esim.provider1",
      "solutionId": "MTAxNA==",
      "maxValidity": "30",
      "minValidity": "3",
      "minData": "5 GB",
      "maxData": "20 GB",
      "maxPrice": 710000.0,
      "minPrice": 156000.0,
      "currency": "VND",
      "countriesNameFilter": "Vietnam",
      "parentProductName": "Asia 11 countries",
      "countries": ["cn", "hk", "jp", "kr", "mo", "my", "ph", "sg", "th", "vn"],
      "networkType": "Roaming",
      "phoneNumber": "No",
      "operators": "China (China Unicom), Hong Kong (SmarTone), Macau (CTM), Singapore (StarHub), Malaysia (Celcom), Thailand (AIS), Indonesia (XL), Vietnam (Viettel, Vinaphone), Philippines (Globe), Japan (KDDI, softbank), South Korea (SKT, KT), ccc",
      "parentProductShortDescription": "Data only, no phone number , Come with data and a Vietnamese phone number to receive ",
      "hotspot": "Yes",
      "topupExtension": "No"
    },
    {
      "providerCode": "esim.provider1",
      "solutionId": "MTAyMg==",
      "maxValidity": "15",
      "minValidity": "15",
      "minData": "5 GB",
      "maxData": "5 GB",
      "maxPrice": 149000.0,
      "minPrice": 149000.0,
      "currency": "VND",
      "countriesNameFilter": "Vietnam",
      "parentProductName": "Vietnam Viettel",
      "countries": ["vn"],
      "networkType": "Roaming",
      "phoneNumber": "Yes",
      "operators": "Viettel",
      "parentProductShortDescription": " Data only, no phone number",
      "hotspot": "Yes",
      "parentProductLabel": "Local",
      "topupExtension": "No"
    },
    {
      "providerCode": "esim.provider1",
      "solutionId": "MTkz",
      "maxValidity": "1",
      "minValidity": "1",
      "minData": "0.0 GB",
      "maxData": "0.0 GB",
      "maxPrice": 1000.0,
      "minPrice": 1000.0,
      "currency": "VND",
      "countriesNameFilter": "Vietnam",
      "parentProductName": "Vietnam Itel",
      "countries": ["vn"],
      "networkType": "Local",
      "phoneNumber": "No",
      "operators": "Itel",
      "parentProductShortDescription": " Data only, no phone number",
      "hotspot": "Yes",
      "parentProductLabel": "Local w Phone",
      "otherInfo": "<i class=&#x27;preserveHtml&#x27; class=&#x27;preserveHtml&#x27; class=&#x27;preserveHtml&#x27; class=&#x27;preserveHtml&#x27; class=&#x27;preserveHtml&#x27; class=&#x27;preserveHtml&#x27;> other </i>",
      "topupExtension": "No"
    },
    {
      "providerCode": "esim.provider1",
      "solutionId": "MTk0",
      "maxValidity": "15",
      "minValidity": "7",
      "minData": "2 GB",
      "maxData": "5 GB",
      "maxPrice": 179000.0,
      "minPrice": 139000.0,
      "currency": "VND",
      "countriesNameFilter": "Vietnam",
      "parentProductName": "Vietnam Vinaphone",
      "countries": ["vn"],
      "networkType": "Local",
      "phoneNumber": "Yes",
      "operators": "Vinaphone",
      "parentProductShortDescription": "Come with data and a Vietnamese phone number and on-net calls",
      "hotspot": "Yes",
      "parentProductLabel": "Local w Phone",
      "otherInfo": "",
      "topupExtension": "No"
    },
    {
      "providerCode": "esim.provider1",
      "solutionId": "MjA=",
      "maxValidity": "30",
      "minValidity": "1",
      "minData": "0.5 GB",
      "maxData": "2 GB",
      "maxPrice": 1170000.0,
      "minPrice": 63000.0,
      "currency": "VND",
      "countriesNameFilter": "Vietnam",
      "parentProductName": "Asialink 7 countries 01",
      "countries": ["hk", "id", "kh", "mo", "my", "sg", "th", "vn"],
      "networkType": "Roaming",
      "phoneNumber": "No",
      "parentProductShortDescription": " Data only, no phone number",
      "hotspot": "Yes",
      "topupExtension": "No"
    }
  ]
}

Response Field Description

This section describes the fields returned in the API response. All field description tables in this section follow the | Field | Type | Example | Description | format.

Root Level Field

The response is a JSON object with a single root key.

Field Type Example Description
solutions Array [{}, {}, ...] An array of Solution Objects.

Solution Object

These objects are found within the solutions array. Each object represents an eSIM product group.

Field Type Example Description
providerCode String "esim.provider1" Code of the eSIM provider.
solutionId String "MTAxNA==" Unique identifier for the eSIM solution group.
maxValidity String "30" Maximum validity period in days.
minValidity String "3" Minimum validity period in days.
minData String "5 GB" Minimum data allowance (e.g., "1 GB", "500 MB").
maxData String "20 GB" Maximum data allowance.
maxPrice Number 710000.0 Maximum price for options within this group.
minPrice Number 156000.0 Minimum price for options within this group.
currency String "VND" Currency code for the prices (e.g., "VND", "USD").
countriesNameFilter String "Vietnam" Name of the country used for filtering, can be a primary country in a group.
parentProductName String "Asia 11 countries" Display name of the eSIM product group/package.
countries Array ["cn", "hk", "vn"] Array of 2-letter ISO country codes covered by this eSIM group.
networkType String "Roaming", "Local" Type of network connection (e.g., Roaming, Local).
phoneNumber String "No", "Yes" Indicates if the eSIM comes with a phone number ("Yes" or "No").
operators String "Viettel, Vinaphone" Comma-separated list of network operators.
parentProductShortDescription String "Data only, no phone number" A short description of the product group.
hotspot String "Yes", "No" Indicates if hotspot/tethering is supported ("Yes" or "No").
topupExtension String "No", "Yes" Indicates if top-up or extension is possible ("Yes" or "No").
parentProductLabel String "Local", "Local w Phone" An optional label for the product (e.g., Local, Local w Phone).
otherInfo String " _other_ ", "" Optional additional information, may contain HTML.

Notes

  • The solutionId might be a base64 encoded string or another form of unique ID.
  • maxValidity and minValidity represent the range of days the eSIM can be active for.
  • minData and maxData represent the range of data allowances available within this group.
  • maxPrice and minPrice provide the price range for different options (e.g., different validity/data combinations) within the same parentProductName.
  • The countries array lists all countries where the eSIMs in this group can be used.
  • operators can be a detailed list including the country and operator name.