Skip to main content
GET
/
esim
/
{iccid}
/
countries
Get eSIM Countries
curl --request GET \
  --url https://api.fyatu.com/api/v3/esim/{iccid}/countries \
  --header 'Authorization: Bearer <token>'
{
  "success": true,
  "status": 200,
  "message": "<string>",
  "data": {
    "iccid": "<string>",
    "esimId": "<string>",
    "packageType": "local",
    "destination": "<string>",
    "countries": [
      {
        "code": "<string>",
        "name": "<string>",
        "flagUrl": "<string>",
        "networks": [
          {
            "name": "<string>",
            "types": [
              "<string>"
            ]
          }
        ]
      }
    ],
    "totalCountries": 123
  }
}

​
Overview

Retrieve the list of countries where an eSIM can be used, along with network coverage information for each country.

​
Path Parameters

ParameterTypeDescription
iccidstringThe eSIM’s ICCID (also accepts esimId for backwards compatibility)

​
When to Use

  • Display coverage map to users before travel
  • Verify an eSIM works in a specific country
  • Show available networks in each covered country
  • Help users understand regional/global eSIM coverage

​
Response Fields

FieldTypeDescription
iccidstringThe eSIM’s ICCID
esimIdstringThe eSIM identifier
packageTypestringlocal, regional, or global
destinationstringPrimary destination name
countriesarrayList of covered countries
totalCountriesintegerNumber of countries covered

​
Country Object

FieldTypeDescription
codestringISO country code (e.g., “FR”, “US”)
namestringCountry name
flagUrlstringURL to country flag image
networksarrayAvailable networks with coverage types

​
Network Object

FieldTypeDescription
namestringNetwork operator name
typesarrayCoverage types (e.g., [“5G”, “LTE”, “3G”])

​
Example Usage

const iccid = '8910300000000012345';

// Get country coverage
const response = await fetch(`https://api.fyatu.com/api/v3/esim/${iccid}/countries`, {
  headers: {
    'Authorization': `Bearer ${accessToken}`
  }
});

const { data } = await response.json();

console.log(`Coverage: ${data.packageType}`);
console.log(`Countries covered: ${data.totalCountries}`);

data.countries.forEach(country => {
  console.log(`${country.name} (${country.code})`);
  country.networks.forEach(network => {
    console.log(`  - ${network.name}: ${network.types.join(', ')}`);
  });
});

​
Example Response (Local eSIM)

{
  "success": true,
  "status": 200,
  "message": "Countries retrieved successfully",
  "data": {
    "iccid": "8910300000000012345",
    "esimId": "ESIM-20260105-ABC12345",
    "packageType": "local",
    "destination": "France",
    "countries": [
      {
        "code": "FR",
        "name": "France",
        "flagUrl": "https://cdn.fyatu.com/flags/fr.svg",
        "networks": [
          {
            "name": "Orange",
            "types": ["5G", "LTE", "3G"]
          },
          {
            "name": "SFR",
            "types": ["LTE", "3G"]
          }
        ]
      }
    ],
    "totalCountries": 1
  }
}

​
Example Response (Regional eSIM)

{
  "success": true,
  "status": 200,
  "message": "Countries retrieved successfully",
  "data": {
    "iccid": "8910300000000054321",
    "esimId": "ESIM-20260105-DEF67890",
    "packageType": "regional",
    "destination": "Europe",
    "countries": [
      {
        "code": "FR",
        "name": "France",
        "flagUrl": "https://cdn.fyatu.com/flags/fr.svg",
        "networks": [
          {
            "name": "Orange",
            "types": ["5G", "LTE"]
          }
        ]
      },
      {
        "code": "DE",
        "name": "Germany",
        "flagUrl": "https://cdn.fyatu.com/flags/de.svg",
        "networks": [
          {
            "name": "Deutsche Telekom",
            "types": ["5G", "LTE", "3G"]
          }
        ]
      },
      {
        "code": "ES",
        "name": "Spain",
        "flagUrl": "https://cdn.fyatu.com/flags/es.svg",
        "networks": [
          {
            "name": "Movistar",
            "types": ["LTE", "3G"]
          }
        ]
      }
    ],
    "totalCountries": 39
  }
}

​
Package Types

TypeDescriptionTypical Coverage
localSingle country1 country
regionalMulti-country region10-50 countries
globalWorldwide100+ countries
For local eSIMs with single-country coverage, the response still uses the countries array with one entry and totalCountries: 1. This provides a consistent response structure across all package types.

​
Error Handling

Error CodeHTTPDescription
ESIM_NOT_FOUND404eSIM doesn’t exist or not owned by you
PACKAGE_NOT_FOUND404Unable to determine package information

​
Use Cases

Use the country list with flag URLs to display an interactive map showing where the eSIM works.
For premium users, show available networks so they can manually select preferred carriers.
Help users verify their eSIM covers all countries in their travel itinerary.

Authorizations

​
Authorization
string
header
required

JWT access token obtained from /auth/token

Path Parameters

​
iccid
string
required

eSIM ICCID (19-20 digits) or esimId (ESIM-XXXXXXXX)

Response

Countries retrieved successfully

​
success
boolean
Example:

true

​
status
integer
Example:

200

​
message
string
​
data
object