eSIMs API overview
FX-Port eSIMs API — browse the package catalog, place orders, top up existing eSIMs, and track usage across 190+ countries.
Sell travel data eSIMs across 190+ countries from a single API surface. FX-Port sources packages from multiple eSIM suppliers and applies agency-specific pricing automatically — you never call a supplier directly, and which supplier fulfills a given package is an internal implementation detail.
Coverage and pricing grow automatically. FX-Port continuously onboards more eSIM suppliers,
and each supplier independently expands its own network of mobile operators over time — both
add new countries, package sizes, and better rates/connectivity to the catalog. Your integration
picks up new packages with no code changes — always read package_id from the catalog response
rather than hard-coding it.
eSIM concepts
Read these before integrating.
eSIM pricing
What each price field means and the 12% agency commission.
Supplier continuity
Why a topup can occasionally be unavailable, and how FX-Port protects your balance.
Endpoints
| Method | Path | Permission | Description |
|---|---|---|---|
GET | /api/v1/esims/packages | Read | List the package catalog, optionally filtered by country/type |
GET | /api/v1/esims/compatible-devices | Read | List devices known to support eSIM |
POST | /api/v1/esims/orders | Read+Write | Create a new eSIM order |
GET | /api/v1/esims/topup-packages/{iccid} | Read | List packages available to top up a specific ICCID |
POST | /api/v1/esims/topups | Read+Write | Top up an existing eSIM |
GET | /api/v1/esims/usage/{iccid} | Read | Data usage for a single ICCID |
GET | /api/v1/esims/usage/bulk | Read | Data usage for every eSIM owned by the agency |
GET | /api/v1/esims/bookings | Read | List the agency's eSIM/topup bookings |
GET | /api/v1/esims/bookings/{iccid}/topup-history | Read | Topup history for one ICCID |
GET | /api/v1/esims/bookings/{booking_id}/setup-instructions | Read | Setup data (QR code, APN) for a booking |
GET | /api/v1/esims/instructions/{iccid} | Read | Installation instructions for an ICCID |
Only order creation and topup creation write anything (they debit your agency balance and provision the eSIM). Every other endpoint is read-only.
Traveler contact details
first_name and last_name follow the same Latin/ASCII-only naming rule used by flights — no
accents, diacritics, or non-Latin scripts.
email and phone are required on order and topup creation —
not optional. FX-Port asks the supplier to email the QR code and installation instructions directly
to that address as soon as the eSIM is provisioned, so the traveler receives setup instructions
without you relaying the QR code yourself. Only pass the traveler's/client's own contact details —
never include billing, pricing, or account information in email or phone, since they are
forwarded to the supplier as customer-facing contact details.
Error responses
| HTTP | Cause |
|---|---|
400 | Missing required field (package_id, iccid, email, phone, etc.) |
401 | Missing or invalid API key |
402 | Insufficient agency balance |
403 | Key lacks write permission, or agency is not active |
404 | Package, ICCID, or booking not found |
409 | Duplicate order/topup detected — an identical request is already in flight |
503 | Supplier API temporarily unavailable |
Questions?
Email the FX-Port developer team at [email protected] for integration help, feature requests, or to report an API error.