eSIM Exchange

Welcome to the TCXC eSIM Exchange , your gateway to global mobile data connectivity.

These APIs let you integrate eSIM provisioning directly into your platform, enabling your customers to stay connected anywhere in the world without swapping physical SIM cards.

What You Can Do

Endpoint	Purpose
eSIM Market	Browse available eSIM packages by country or region
eSIM Countries	Get the full list of supported destinations
Purchase eSIM	Provision a new eSIM instantly and receive activation credentials (QR code, LPA string)
List Purchased eSIMs	Retrieve all eSIMs on your account with status, usage, and activation details
Orders History	Review past purchases for billing reconciliation and reporting
Top-up Packages	Discover available data add-ons for any active eSIM
Purchase Top-up	Extend data or validity on an existing eSIM

Universal vs. Regional eSIMs

Not all eSIMs are created equal.

Regional eSIMs are destination-specific. Heading to a new country? Install another eSIM profile.

Universal eSIMs work globally. New destination? Just add a data package. Same device. Same eSIM. Any country.

The TCXC eSIM Exchange provides Universal eSIMs by default — one profile, unlimited destinations, seamless top-ups.

Quick Start

Call eSIM Countries to see where coverage is available
Search eSIM Market to find packages for your target destination
Use Purchase eSIM with your chosen i_esim_package and i_account
Deliver the QR code or LPA string to your end user for instant activation

Base URLhttps://apiv2.telecomsxchange.com

AuthenticationHTTP Digest

Buyer

Buyer APIs

The Buyer folder contains endpoints for TelecomsXChange (TCXC) customers who act as buyers on the TCXC platform. These APIs allow you to discover, provision, and manage eSIMs offered by sellers in the TCXC exchange..

Use these endpoints after you have created and activated a TCXC buyer account and obtained your API credentials as described in the main TelecomsXChange (TCXC) collection overview.

#List Countries

GEThttps://apiv2.telecomsxchange.com/buyers/esim/countries

Retrieves a comprehensive list of all countries where eSIM packages are currently available. Use this endpoint to populate country selection dropdowns or validate country availability before querying the marketplace.

Request Parameters

None required

Response

Returns an array of country objects with uppercase country names.

No parameters. Authentication is the only requirement.

curl --digest \
  -u "$TCXC_USERNAME:$TCXC_API_KEY" \
  "https://apiv2.telecomsxchange.com/buyers/esim/countries"

Supported destinations3 results

AFGHANISTAN
ALBANIA
ALGERIA

Rendered from the example response.

#Market View (eSIM)

POSThttps://apiv2.telecomsxchange.com/buyers/esim/market

Searches the eSIM marketplace for available data packages filtered by country. Returns package details including pricing, validity period, data allowance, and vendor information. Use this endpoint to display available eSIM options to end users or to programmatically select packages for purchase.

Response Fields

i_esim_package — Unique package identifier (required for purchase)
price_with_fee — Total price including platform fees (USD)
validity_days — Package validity period in days
data_gb — Data allowance in gigabytes

Body parameters

application/x-www-form-urlencoded

countrystringrequired

Target country name in uppercase (e.g., UKRAINE, UNITED STATES). Use the List Countries endpoint to retrieve valid country names.

Example JAPAN

esim_vendorstringrequired

Seller login/username, for e.g eSIM, Airalo

Example eSIMP

i_vendorintegerrequired

Seller numeric ID, for e.g. 484 for eSIMP, 485 for Airalo.

Example 484

max_pricenumberrequired

Maximum price cap, for e.g. 5.0

Example 5.0

data_GBintegerrequired

Data size filter (0.5, 1, 5, 10, 20, -1 for unlimited)

Example 1

pagerintegerrequired

Results per page (default 20)

Example 5

offintegerrequired

Pagination offset. Use 0 for the first page. Increment by the pager value for subsequent pages.

Example 0

curl --digest \
  -u "$TCXC_USERNAME:$TCXC_API_KEY" \
  -X POST \
  "https://apiv2.telecomsxchange.com/buyers/esim/market" \
  -d "country=JAPAN" \
  -d "esim_vendor=eSIMP" \
  -d "i_vendor=484" \
  -d "max_price=5.0" \
  -d "data_GB=1" \
  -d "pager=5" \
  -d "off=0"

eSIM packages3 packages

Japan 1 GB 7 Days$3.49

JP · KDDI Rakuten Mobile Inc.

1 GBdata7 daysvalidity

Japan 3 GB 15 Days$7.99

3 GBdata15 daysvalidity

Japan 5 GB 30 Days$11.99

JP · KDDI Rakuten Mobile Inc.

5 GBdata30 daysvalidity

Rendered from the example response.

#Purchase eSIM

POSThttps://apiv2.telecomsxchange.com/buyers/esim/purchase

Initiates the purchase of a new eSIM package. Upon successful completion, returns the eSIM credentials including ICCID, LPA string, and QR code for device installation. The purchase amount is immediately deducted from the specified account balance.

Response Fields

iccid — Integrated Circuit Card Identifier (unique eSIM identifier)
i_esim_order — Internal order reference number
order_uuid — Universally unique order identifier for tracking
lpa — Local Profile Assistant string for manual eSIM installation
qr_base64 — Base64-encoded QR code image for eSIM activation

Body parameters

application/x-www-form-urlencoded

i_accountintegerrequired

Account ID to be charged for this purchase. Must have sufficient balance to cover the package cost.

Example 1181

i_esim_packageintegerrequired

Unique package identifier obtained from the List Packages endpoint.

Example 267

curl --digest \
  -u "$TCXC_USERNAME:$TCXC_API_KEY" \
  -X POST \
  "https://apiv2.telecomsxchange.com/buyers/esim/purchase" \
  -d "i_account=1181" \
  -d "i_esim_package=267"

eSIM ready to installorder #23

ICCID8910300000050257244

Activation codeLPA:1$consumer.e-sim.global$TN20251216153212D5009E7E

Install on iPhone

Rendered from the example response.

#Top-up Packages

POSThttps://apiv2.telecomsxchange.com/buyers/esim/topup/list

Retrieves all available top-up packages compatible with a specific eSIM. Returns packages that can extend data allowance or validity for an existing eSIM profile. Use this endpoint to offer data renewal options to users with active eSIMs.

Response Fields

package_type_id — Unique identifier required for top-up purchase
price_with_fee — Total top-up cost including platform fees (USD) - Final price
data_GB — Additional data allowance in gigabytes
validity_days — Extended validity period in days
activation_policy — Description of when the top-up validity begins
supported_countries — Array of countries where the top-up is valid

Body parameters

application/x-www-form-urlencoded

iccidintegerrequired

The 18-22 digit ICCID of the eSIM to query top-up options for. Must be a valid, previously purchased eSIM.

Example 89103000000273190001

curl --digest \
  -u "$TCXC_USERNAME:$TCXC_API_KEY" \
  -X POST \
  "https://apiv2.telecomsxchange.com/buyers/esim/topup/list" \
  -d "iccid=89103000000273190001"

Top-up packages2 packages

Ukraine 1 GB 7 Days$1.10

Data Only

1 GBdata7 Daysvalidity

Ukraine 3 GB 30 Days$3.30

Data Only

3 GBdata30 Daysvalidity

Rendered from the example response.

#Purchase topup package

POSThttps://apiv2.telecomsxchange.com/buyers/esim/topup/purchase

Applies a data top-up to an existing eSIM profile. Extends the data allowance and/or validity period of the specified eSIM. The top-up is applied immediately upon successful purchase and the amount is deducted from the specified account.

Form-Data Parameters

Parameter	Type	Required	Description
`iccid`	string	Yes	The ICCID of the target eSIM to apply the top-up to. Must be a valid, active eSIM owned by your account.
`package_type_id`	integer	Yes	Top-up package identifier obtained from the List Top-Up Packages endpoint.
`i_account`	integer	Yes	Account ID to be charged for this top-up. Must have sufficient balance.

Response Fields

order_uuid — Universally unique identifier for the top-up transaction

No parameters. Authentication is the only requirement.

curl --digest \
  -u "$TCXC_USERNAME:$TCXC_API_KEY" \
  -X POST \
  "https://apiv2.telecomsxchange.com/buyers/esim/topup/purchase"

Top-up result

Order: c40d0f55-8993-40cf-8d83-108ff80ff4ed

Rendered from the example response.

#Orders history

POSThttps://apiv2.telecomsxchange.com/buyers/esim/orders

Retrieves a paginated history of all eSIM orders including initial purchases and top-ups. Use this endpoint for transaction reconciliation, order tracking, and generating purchase reports. Orders are returned in reverse chronological order (newest first).

Form-Data Parameters

Parameter	Type	Required	Description
`date_from`	string	Yes	Start date for the query range. Format: `YYYY-MM-DD HH:MM:SS` (e.g., `2024-01-01 00:00:00`).
`date_to`	string	Yes	End date for the query range. Format: `YYYY-MM-DD HH:MM:SS` (e.g., `2025-12-31 23:59:59`).
`pager`	integer	Yes	Maximum number of orders to return per request. Recommended range: 10-100.
`off`	integer	Yes	Pagination offset. Use `0` for the first page. Increment by the `pager` value to retrieve subsequent pages.

Response Fields

i_esim_order — Unique order identifier
order_type — Transaction type: purchase (new eSIM) or top-up (data reload)
amount_charged — Total amount charged (USD)
status — Order status: complete, pending, or failed
order_uuid — UUID for external reference and support inquiries
create_ts — Order timestamp (UTC)
iccid — Associated eSIM identifier
package_name — Human-readable package description

Body parameters

application/x-www-form-urlencoded

date_fromdatetimerequired: Example 2020-01-01 00:00:00
date_todatetimerequired: Example 2026-07-01 00:00:00
pagerintegerrequired: Example 4
offintegerrequired: Example 0

curl --digest \
  -u "$TCXC_USERNAME:$TCXC_API_KEY" \
  -X POST \
  "https://apiv2.telecomsxchange.com/buyers/esim/orders" \
  -d "date_from=2020-01-01 00:00:00" \
  -d "date_to=2026-07-01 00:00:00" \
  -d "pager=4" \
  -d "off=0"

Order history3 orders

Date	Package	Type	ICCID	Status	Charged
2025-12-18 · 22:15:49	India 1 GB 7 Days INDIA	top-up	8910300000027319600	complete	$3.49
2025-12-18 · 22:07:12	India 1 GB 7 Days INDIA	purchase	8910300000027319600	complete	$3.49
2025-12-16 · 00:38:54	Kuwait 3 GB 15 Days KUWAIT	top-up	8910300000030228001	complete	$10.99

Rendered from the example response.

#List Purchased eSIMs

POSThttps://apiv2.telecomsxchange.com/buyers/esim/list

Retrieves a paginated inventory of all eSIMs associated with your account. Returns comprehensive details including activation status, remaining data, expiry information, and installation credentials. Use this endpoint for eSIM lifecycle management and status monitoring.

Form-Data Parameters

Parameter	Type	Required	Description
`pager`	integer	Yes	Maximum number of eSIM records to return per request. Recommended range: 10-100.
`off`	integer	Yes	Pagination offset. Use `0` for the first page. Increment by the `pager` value for subsequent pages.

Response Fields

iccid — Unique eSIM identifier
esim_status — Current eSIM state: RELEASED, DOWNLOADED, INSTALLED, ENABLED
esim_status_message — Human-readable status description
data_usage_remaining_bytes — Remaining data allowance in bytes
data_allowance_bytes — Total data allowance in bytes
days_left_to_expiry — Days remaining until package expiration
lpa — LPA string for manual installation
qr_base64 — Base64-encoded QR code for device activation
sm_dp_address — SM-DP+ server address
activation_code — Activation code for manual entry

Body parameters

application/x-www-form-urlencoded

iccidintegerrequired

Filter by exact ICCID

Example 8910300000050257244

pagerintegerrequired

Results per page (max items returned

Example 3

offintegerrequired

Pagination offset

Example 0

curl --digest \
  -u "$TCXC_USERNAME:$TCXC_API_KEY" \
  -X POST \
  "https://apiv2.telecomsxchange.com/buyers/esim/list" \
  -d "iccid=8910300000050257244" \
  -d "pager=3" \
  -d "off=0"

Your eSIMs3 results

Package	ICCID	Status	Charged
Europe 1 GB 7 Days 1 GB · 7 days	19220000000184396	installed	$1.10
Israel 1 GB 7 Days 1 GB · 7 days	19220000000173165	error	$1.10
Africa 1 GB 7 Days 1 GB · 7 days	19220000000191207	downloaded	$1.10

Rendered from the example response.