5-Minute Quickstart

Go from zero to your first eSIM order using the Tourist eSIM Partner API. Follow the steps below — each one builds on the last.

⚡ ~5 minutes 🔐 OAuth 2.0 🌍 200+ Countries 📡 REST / JSON

Get Your API Credentials

API access requires a verified partner account. If you don't have one yet, register and complete KYC first.

Prerequisites:
1. Create a partner account at partners.touristesim.net
2. Complete KYC verification
3. Request API access from your dashboard — admin will provide client_id and client_secret

Your credentials look like: client_id = client_abc123... and client_secret = secret_xyz789...

Get an Access Token

Exchange your credentials for an OAuth 2.0 Bearer token. Tokens are valid for 1 hour — cache and reuse them.

# POST to the token endpoint
curl -X POST https://api.touristesim.net/v1/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

<?php
$response = file_get_contents('https://api.touristesim.net/v1/oauth/token', false,
    stream_context_create(['http' => [
        'method'  => 'POST',
        'header'  => "Content-Type: application/x-www-form-urlencoded",
        'content' => http_build_query([
            'grant_type'    => 'client_credentials',
            'client_id'     => 'YOUR_CLIENT_ID',
            'client_secret' => 'YOUR_CLIENT_SECRET',
        ]),
    ]])
);
$token = json_decode($response, true)['access_token'];
// Store $token and reuse for 1 hour

import axios from 'axios';

const { data } = await axios.post(
  'https://api.touristesim.net/v1/oauth/token',
  new URLSearchParams({
    grant_type:    'client_credentials',
    client_id:     'YOUR_CLIENT_ID',
    client_secret: 'YOUR_CLIENT_SECRET',
  })
);
const token = data.access_token; // cache until data.expires_in

import requests

res = requests.post('https://api.touristesim.net/v1/oauth/token', data={
    'grant_type':    'client_credentials',
    'client_id':     'YOUR_CLIENT_ID',
    'client_secret': 'YOUR_CLIENT_SECRET',
})
token = res.json()['access_token']  # cache for 1 hour

200 OK POST /oauth/token

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...",
  "token_type":   "Bearer",
  "expires_in":   3600
}

⚠️ Token caching: Request a new token only when the current one is about to expire. Requesting a new token on every API call wastes quota and slows your integration.

Browse Available Plans

Fetch the eSIM catalog. Filter by country, region, data size, or validity. Store plan_slug — it's the stable identifier you'll use to create orders.

# List all plans (paginated, 20 per page by default)
curl -H "Authorization: Bearer $TOKEN" \
  "https://api.touristesim.net/v1/plans?country=US&type=local"

# Or browse a specific country
curl -H "Authorization: Bearer $TOKEN" \
  "https://api.touristesim.net/v1/plans?country=GB&data_min=5&validity_max=30"

$ch = curl_init('https://api.touristesim.net/v1/plans?country=US');
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER    => ["Authorization: Bearer {$token}"],
    CURLOPT_RETURNTRANSFER => true,
]);
$plans = json_decode(curl_exec($ch), true);
curl_close($ch);

foreach ($plans['data'] as $plan) {
    echo $plan['plan_slug'] . ' — $' . $plan['price'] . PHP_EOL;
}

const { data } = await axios.get(
  'https://api.touristesim.net/v1/plans',
  {
    params: { country: 'US', type: 'local' },
    headers: { Authorization: `Bearer ${token}` },
  }
);

data.data.forEach(plan => {
  console.log(plan.plan_slug, '$' + plan.price);
});

plans = requests.get(
    'https://api.touristesim.net/v1/plans',
    params={'country': 'US', 'type': 'local'},
    headers={'Authorization': f'Bearer {token}'},
).json()

for plan in plans['data']:
    print(plan['plan_slug'], '$' + plan['price'])

200 OK GET /plans?country=US

{
  "success": true,
  "data": [
    {
      "plan_slug":     "us-5gb-30days",  // ← use this to create orders
      "name":          "USA 5GB - 30 Days",
      "price":         "12.50",
      "currency":      "USD",
      "validity_days": 30,
      "type":          "local",
      "reloadable":    true
    }
  ],
  "pagination": { "total": 120, "per_page": 20, ... }
}

💡 Tip: Cache the plan catalog locally — call GET /plans once per day and store the results. This keeps your integration fast and reduces API calls.

Create an eSIM Order

Use the plan_slug from step 3 to place an order. Provide the customer email so they can receive their eSIM installation details.

curl -X POST https://api.touristesim.net/v1/orders \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "plan_slug": "us-5gb-30days", "quantity": 1 }
    ],
    "customer": {
      "email": "traveler@example.com",
      "name": "Jane Doe"
    },
    "reference": "my-order-001",
    "webhook_url": "https://yourapp.com/webhooks/esim"
  }'

$payload = json_encode([
    'items'       => [['plan_slug' => 'us-5gb-30days', 'quantity' => 1]],
    'customer'    => ['email' => 'traveler@example.com', 'name' => 'Jane Doe'],
    'reference'   => 'my-order-001',
    'webhook_url' => 'https://yourapp.com/webhooks/esim',
]);

$ch = curl_init('https://api.touristesim.net/v1/orders');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => $payload,
    CURLOPT_HTTPHEADER     => [
        "Authorization: Bearer {$token}",
        'Content-Type: application/json',
    ],
    CURLOPT_RETURNTRANSFER => true,
]);
$order = json_decode(curl_exec($ch), true);
curl_close($ch);

echo $order['data']['order_number']; // e.g. "PO-260519MKAUVE"

const { data } = await axios.post(
  'https://api.touristesim.net/v1/orders',
  {
    items:       [{ plan_slug: 'us-5gb-30days', quantity: 1 }],
    customer:    { email: 'traveler@example.com', name: 'Jane Doe' },
    reference:   'my-order-001',
    webhook_url: 'https://yourapp.com/webhooks/esim',
  },
  { headers: { Authorization: `Bearer ${token}` } }
);

console.log(data.data.order_number); // "PO-260519MKAUVE"

201 Created POST /orders

{
  "success":  true,
  "data": {
    "order_number": "PO-260519MKAUVE",
    "status":       "pending",   // → processing → completed
    "amount":       "12.50",
    "currency":     "USD"
  }
}

Get the eSIM & Handle Status

Orders move through pending → processing → completed. The preferred approach is webhooks — you'll receive a push notification the moment the eSIM is ready. Alternatively, poll GET /orders/{id}.

# Check order status
curl -H "Authorization: Bearer $TOKEN" \
  "https://api.touristesim.net/v1/orders/ord_ABC123XYZ789"

# Get eSIM installation details by ICCID
curl -H "Authorization: Bearer $TOKEN" \
  "https://api.touristesim.net/v1/esims/8901234567890123456/instructions"

📬 Webhooks are strongly recommended over polling. Register your endpoint via POST /webhooks to receive real-time push events for order.completed, order.failed, esim.depleted, and more.

What's next?

You've completed the core flow. Explore these topics to build a production-ready integration.

📋

5-Minute Quickstart

Get Your API Credentials

Get an Access Token

Browse Available Plans

Create an eSIM Order

Get the eSIM & Handle Status

What's next?

Plan Catalog

eSIM Management

Webhooks

Balance & Billing

Official SDKs

Full API Reference