Skip to main content
GET
/
esim
/
list
List eSIMs
curl --request GET \
  --url https://api.fyatu.com/api/v3/esim/list \
  --header 'Authorization: Bearer <token>'
{
  "success": true,
  "status": 200,
  "message": "<string>",
  "data": {
    "esims": [
      {
        "esimId": "<string>",
        "iccid": "<string>",
        "status": "ready",
        "package": {
          "id": "<string>",
          "name": "<string>",
          "destination": "<string>"
        },
        "validity": {
          "activatedAt": "2023-11-07T05:31:56Z",
          "expiresAt": "2023-11-07T05:31:56Z",
          "daysRemaining": 123
        },
        "createdAt": "2023-11-07T05:31:56Z"
      }
    ],
    "pagination": {
      "page": 123,
      "perPage": 123,
      "totalItems": 123,
      "totalPages": 123
    }
  },
  "meta": {
    "requestId": "req_abc123def456",
    "timestamp": "2023-11-07T05:31:56Z"
  }
}

​
Overview

Retrieve a paginated list of all eSIMs purchased by your business app.

​
Query Parameters

ParameterTypeDefaultMaxDescription
pageinteger1-Page number
perPageinteger50100Items per page
statusstring--Filter by status
searchstring--Search by esimId, iccid, or destination

​
eSIM Statuses

StatusDescription
inactivePurchased but not yet activated on a device
activeCurrently in use
expiredValidity period has ended
consumedData allowance fully used

​
Response Fields

Each eSIM includes:
FieldTypeDescription
esimIdstringUnique identifier
iccidstringeSIM ICCID
customNamestringUser-assigned name (if set)
statusstringCurrent status
packageobjectPackage info (id, name, destination)
dataobjectData usage (total, used, remaining MB)
validityobjectActivation and expiration dates
createdAtstringPurchase timestamp

​
Example Usage

// Get all active eSIMs
const response = await fetch('https://api.fyatu.com/api/v3/esim/list?status=active&perPage=20', {
  headers: {
    'Authorization': `Bearer ${accessToken}`
  }
});

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

console.log(`Showing ${data.esims.length} of ${data.pagination.totalItems} eSIMs`);

data.esims.forEach(esim => {
  const usagePercent = esim.data.totalMb > 0
    ? Math.round((esim.data.usedMb / esim.data.totalMb) * 100)
    : 0;

  console.log(`${esim.esimId}: ${esim.package.destination}`);
  console.log(`  Status: ${esim.status}`);
  console.log(`  Usage: ${esim.data.usedMb}MB / ${esim.data.totalMb}MB (${usagePercent}%)`);

  if (esim.validity.expiresAt) {
    console.log(`  Expires: ${esim.validity.expiresAt}`);
  }
});

// Handle pagination
if (data.pagination.page < data.pagination.totalPages) {
  console.log(`Page ${data.pagination.page} of ${data.pagination.totalPages}`);
}

​
Example Response

{
  "success": true,
  "status": 200,
  "message": "eSIMs retrieved successfully",
  "data": {
    "esims": [
      {
        "esimId": "ESIM-20260105-ABC12345",
        "iccid": "8910300000000012345",
        "customName": "John's Travel eSIM",
        "status": "active",
        "package": {
          "packageId": "merhaba-7days-5gb",
          "name": "Merhaba 7 Days 5GB",
          "destination": "Turkey",
          "destinationType": "local"
        },
        "data": {
          "totalMb": 5120,
          "usedMb": 2048,
          "remainingMb": 3072
        },
        "validity": {
          "activatedAt": "2026-01-03T14:30:00Z",
          "expiresAt": "2026-01-10T14:30:00Z"
        },
        "createdAt": "2026-01-03T10:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "perPage": 20,
      "totalItems": 45,
      "totalPages": 3
    }
  }
}

​
Filtering Examples

// All inactive (not yet used)
GET /esim/list?status=inactive

// Search by destination
GET /esim/list?search=france

// Search by ICCID
GET /esim/list?search=8910300000000012345

// Combine filters
GET /esim/list?status=active&perPage=50&page=2

​
Use Cases

  • Dashboard Overview: Show all eSIMs with status and usage
  • Usage Monitoring: Identify eSIMs with low data remaining
  • Expiration Alerts: Find eSIMs expiring soon
  • Customer Lookup: Search for specific customer’s eSIM

Authorizations

​
Authorization
string
header
required

JWT access token obtained from /auth/token

Query Parameters

​
page
integer
default:1
​
perPage
integer
default:50
Required range: x <= 100
​
status
enum<string>
Available options:
ready,
active,
expired,
depleted

Response

eSIMs retrieved successfully

​
success
boolean
Example:

true

​
status
integer
Example:

200

​
message
string
​
data
object
​
meta
object