Skip to main content

eSIMfly Business API

Deliver eSIM data packages via the eSIMfly Business API. Step-by-step overview.

Quick Start​

  1. Create an account at eSIMfly Business
  2. Deposit funds for testing
  3. Copy your Access Code from Settings → API Keys
  4. Make your first API call:
curl --location 'https://esimfly.net/api/v1/business/balance' \
--header 'RT-AccessCode: YOUR_ACCESS_CODE' \
--header 'RT-RequestID: 550e8400-e29b-41d4-a716-446655440000' \
--header 'RT-Timestamp: 1628670421000' \
--header 'RT-Signature: YOUR_CALCULATED_SIGNATURE'

Official SDK (Node.js / TypeScript)​

Using Node.js? Skip the signing code entirely:

npm install @esimfly/sdk
import { ESIMfly } from '@esimfly/sdk';

const esimfly = new ESIMfly({
  accessCode: process.env.ESIMFLY_ACCESS_CODE!,
  secretKey: process.env.ESIMFLY_SECRET_KEY!,
});

const { balance, currency } = await esimfly.balance.get();
const order = await esimfly.orders.create({ packageCode: '1648812', idempotencyKey: 'my-order-1' });
console.log(order.esims[0].lpaString);

Zero dependencies, typed responses, automatic HMAC signing, idempotent retries, paced catalogue sync and webhook verification. Source and full README: github.com/eSimfly-Official/esimfly-sdk-nodejs. PHP and Python SDKs are planned; until then use the code examples.

Using an AI agent?​

Connect Claude.ai, ChatGPT, Claude Code, Cursor or any MCP client to the API with the official MCP server: add https://mcp.esimfly.net/mcp and sign in with your business account (or run it locally with npx -y @esimfly/mcp). Read-only by default; orders and top-ups need an explicit confirmation step.

Building with an AI assistant?​

Copy the complete integration prompt into ChatGPT, Claude, Cursor or Copilot. It contains every endpoint plus the recommended architecture — sync the package catalogue into your own database, use idempotency keys on orders — so the generated code stays fast and well inside the rate limits. Every endpoint page also has its own prompt.

Version - V1​

Version 1.0 - August 2025 - Initial Release

  • HMAC-SHA256 authentication
  • Balance query endpoint
  • Package listing with profit margins
  • eSIM ordering and management
  • eSIM topup functionality
  • Order history tracking

Environments and Endpoints​

Production:

  • Base URL: https://esimfly.net/api/v1/business
  • Rate Limit: 1000 requests per hour

Test Environment:

  • Use your live environment for testing
  • Request test funds from support

Authentication​

All API requests require HMAC-SHA256 signature authentication using:

  • RT-AccessCode: Your API access code
  • RT-RequestID: Unique request ID (UUID v4)
  • RT-Timestamp: Request timestamp in milliseconds
  • RT-Signature: HMAC-SHA256 signature

Learn more about authentication →

Standards​

  • Time codes: UTC format
  • Country codes: ISO Alpha-2
  • Data values: Gigabytes (GB)
  • Currency: USD

Rate Limit​

Limits are set per API key and shown in your Business Dashboard (typically 100 requests per minute, 1,000 per hour and 10,000 per day). Bulk jobs (such as a catalogue sync) should be paced at one request per second. Rate limit information is included in response headers:

  • X-RateLimit-Limit: Maximum requests allowed
  • X-RateLimit-Remaining: Requests remaining
  • X-RateLimit-Reset: Time when limit resets

Response Format​

All API responses follow this format:

Success Response​

{
  "success": true,
  "data": {
    // Response data
  }
}

Error Response​

{
  "success": false,
  "error": "Error message",
  "code": "ERROR_CODE" // Optional error code
}

Main Endpoints​

Balance Management​

  • GET /balance - Check account balance

Package Management​

  • GET /esims/packages - List available packages with pricing

eSIM Operations​

  • POST /esims/order - Order new eSIMs
  • GET /esims - List your eSIMs
  • GET /orders - View order history

eSIM Topup Operations​

  • GET /topup/packages - Get available topup packages for an eSIM
  • POST /topup/order - Process topup orders

Support​