Hubby eSIM API Quickstart Guide

Welcome to Hubby! This quickstart guide will help you get started with Hubby's eSIM API, allowing you to make your first API call and begin integrating eSIM booking capabilities into your application.

API Endpoints

Hubby provides two API endpoints:

Production: https://api.hubbyesim.com/api - Use this for live applications
Staging: https://api-staging.hubby.dev/api - Use this for testing and development

Make sure to use the appropriate endpoint based on your needs. The staging environment is perfect for testing your integration before going live.

Step 1: Get Your API Keys

Contact Hubby support at support@hubbyesim.com to get your API credentials
You will receive:
- Public API Key (x-api-key)
- Secret Key (for generating signatures)

Step 2: Authentication

All API requests must include the following headers:

x-api-key: Your public API key
x-timestamp: Current Unix timestamp in milliseconds
x-signature: HMAC-SHA256 signature

Here's how to generate the HMAC signature:

const cryptoJs = require('crypto-js');

// Configuration values that would normally come from environment
const secretKey = "YOUR_API_SECRET";
const publicKey = "YOUR_API_KEY";
const baseUrl = "YOUR_BASE_URL";

// Function to generate headers for API request
function generateApiHeaders(method, path) {
    // Get current timestamp in milliseconds
    const timestamp = Date.now().toString();

    // Ensure path is a string
    let processedPath = String(path);

    // Remove baseUrl from the path if present
    processedPath = processedPath.replace(baseUrl, '');

    // Create query string if needed
    const queryString = new URL(path).search;
    if (queryString) {
        processedPath += queryString;
    }

    // Validate public key
    if (!publicKey) {
        throw new Error("Public key is required");
    }

    // Create the payload - include query parameters if present
    // Sample payload: 1715558400000GET/api/bookings?bookingId=1234567890
    const payload = timestamp + method + processedPath;

    // Generate the HMAC signature
    const signature = cryptoJs.HmacSHA256(payload, secretKey).toString(cryptoJs.enc.Hex);

    // Return headers object
    return {
        'x-timestamp': timestamp,
        'x-signature': signature,
        'x-api-key': publicKey,
        'Accept': 'application/json'
    };
}

Step 3: Create Your First Booking

A Booking in the Hubby API maps directly to the travel booking you already have — a traveler, a departure date, and one or more destinations. You specify where the traveler is going and how much data they need; Hubby handles the rest. If you've ever created a hotel or flight booking via API, this will feel familiar — that's by design.

Let's create a booking for an eSIM package. Use the staging URL for testing:

Note on external_user_id: The Hubby WebView and Native eSIM Integration guides require an external_user_id field on each entry in package_specifications. Do not include this field for standard bookings (email-based delivery, promo codes) — it is ignored in the traditional flow, and supplying it incorrectly will route the package into the eSIM management flow. Only add it when you are implementing the WebView or Native integration.

# For testing (staging):
curl -X POST https://api-staging.hubby.dev/api/bookings \

# For production:
# curl -X POST https://api.hubbyesim.com/api/bookings \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-H "x-timestamp: 1715558400000" \
-H "x-signature: YOUR_GENERATED_SIGNATURE" \
-d '{
  "departure_date": "2026-01-03",
  "email": "customer@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "departure_location": "JFK",
  "custom_branding": "your-brand-id",
  "package_specifications": [
    {
      "destination": "USA",
      "size": "500MB"
    }
  ]
}'

Response Example

{
  "success": true,
  "message": "Booking created successfully",
  "data": {
    "id": "booking_id",
    "email": "customer@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "departure_date": "2026-01-03",
    "departure_location": "JFK",
    "custom_branding": "your-brand-id",
    "promo_codes": [
      {
        "promo_code": "XXXX-YYYY-ZZZZ",
        "package_id": "package_id",
        "package_size": "500MB",
        "destination": "US"
      }
    ]
  }
}

Step 4: View Available Bundles for a Destination

Before creating a booking, you might want to browse the available bundles for a specific destination. Each destination has one or more bundles — data products with different sizes, durations, and prices:

# For testing (staging):
curl -X GET "https://api-staging.hubby.dev/api/destinations/US" \

# For production:
# curl -X GET "https://api.hubbyesim.com/api/destinations/US" \
-H "x-api-key: YOUR_API_KEY" \
-H "x-timestamp: 1715558400000" \
-H "x-signature: YOUR_GENERATED_SIGNATURE"

You can also list all available destinations with GET /api/destinations.

Step 5: Retrieve Booking Details

You can retrieve booking details using the booking ID:

# For testing (staging):
curl -X GET "https://api-staging.hubby.dev/api/bookings/YOUR_BOOKING_ID?includeUsage=true" \

# For production:
# curl -X GET "https://api.hubbyesim.com/api/bookings/YOUR_BOOKING_ID?includeUsage=true" \
-H "x-api-key: YOUR_API_KEY" \
-H "x-timestamp: 1715558400000" \
-H "x-signature: YOUR_GENERATED_SIGNATURE"

Response Example

{
  "success": true,
  "message": "Booking details retrieved successfully",
  "data": {
    "id": "booking_id",
    "email": "customer@example.com",
    "departure_date": "2026-01-03",
    "promo_codes": [
      {
        "promo_code": "XXXX-YYYY-ZZZZ",
        "package_id": "package_id",
        "package_size": "500MB",
        "destination": "US"
      }
    ]
  }
}

Step 6: Understanding Package Types

The Hubby API supports four different types of eSIM packages. Here are examples of each:

Starter Package

Limited data for a short duration (perfect for trials):

# For testing (staging):
curl -X POST https://api-staging.hubby.dev/api/bookings \

# For production:
# curl -X POST https://api.hubbyesim.com/api/bookings \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-H "x-timestamp: 1715558400000" \
-H "x-signature: YOUR_GENERATED_SIGNATURE" \
-d '{
  "departure_date": "2026-01-03",
  "email": "customer@example.com",
  "package_specifications": [
    {
      "destination": "USA",
      "size": "500MB",
      "package_type": "starter",
      "package_duration": 1
    }
  ]
}'

Data-Limited Package (Default)

Traditional packages with a specific data allowance:

# For testing (staging):
curl -X POST https://api-staging.hubby.dev/api/bookings \

# For production:
# curl -X POST https://api.hubbyesim.com/api/bookings \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-H "x-timestamp: 1715558400000" \
-H "x-signature: YOUR_GENERATED_SIGNATURE" \
-d '{
  "departure_date": "2026-01-03",
  "email": "customer@example.com",
  "package_specifications": [
    {
      "destination": "USA",
      "size": "1GB",
      "package_type": "data-limited",
      "package_duration": 365
    }
  ]
}'

Unlimited Package

Unrestricted data usage for heavy data users:

# For testing (staging):
curl -X POST https://api-staging.hubby.dev/api/bookings \

# For production:
# curl -X POST https://api.hubbyesim.com/api/bookings \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-H "x-timestamp: 1715558400000" \
-H "x-signature: YOUR_GENERATED_SIGNATURE" \
-d '{
  "departure_date": "2026-01-03",
  "email": "customer@example.com",
  "package_specifications": [
    {
      "destination": "USA",
      "package_type": "unlimited",
      "package_duration": 30
    }
  ]
}'

Time-Limited Package

Full-speed data with both data and time limits:

# For testing (staging):
curl -X POST https://api-staging.hubby.dev/api/bookings \

# For production:
# curl -X POST https://api.hubbyesim.com/api/bookings \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-H "x-timestamp: 1715558400000" \
-H "x-signature: YOUR_GENERATED_SIGNATURE" \
-d '{
  "departure_date": "2026-01-03",
  "email": "customer@example.com",
  "package_specifications": [
    {
      "destination": "USA",
      "size": "5GB",
      "package_type": "time-limited",
      "package_duration": 3
    }
  ]
}'

Note: If you don't specify package_type, it defaults to data-limited. For more details, see our Package Types guide.

Error Handling

The API uses standard HTTP status codes and returns detailed error messages:

{
  "success": false,
  "error": {
    "code": 400,
    "message": "Validation error",
    "details": {
      "departure_date": "Must be a future date"
    }
  }
}

Common error codes:

400: Validation error
401: Authentication error (check timestamp format and signature calculation)
404: Resource not found
500: Server error

Next Steps

Explore the full API documentation for more endpoints and features
Join our community to connect with other developers
Contact support@hubbyesim.com for technical assistance

Need help? Email us at support@hubbyesim.com

Hubby eSIM API Quickstart Guide

API Endpoints

Step 1: Get Your API Keys

Step 2: Authentication

Step 3: Create Your First Booking

Response Example

Step 4: View Available Bundles for a Destination

Step 5: Retrieve Booking Details

Response Example

Step 6: Understanding Package Types

Starter Package

Data-Limited Package (Default)

Unlimited Package

Time-Limited Package

Error Handling

Next Steps

Was this helpful?