Welcome to the Hubby API documentation. This API enables partners to seamlessly integrate eSIM booking and management capabilities into their applications.
Key Features:
The API supports four types of packages:
Starter packages: Hybrid packages that are both data and time limited. They provide a small data allowance within a short time period (default: 2 days). Perfect for first-time users and trials.
Data-limited packages: Traditional packages with a specific data allowance that expires after a certain period (default: 365 days). This is the primary package type and the default for most use cases.
Unlimited packages: Packages that provide unrestricted data usage for a specified duration. Subject to fair use policy. Ideal for heavy data users and digital nomads.
Time-limited packages: Packages that provide a fixed data allowance for a specific duration with full-speed access. These packages expire when either the data limit or time limit is reached.
Note: Top-ups are always data-limited packages, regardless of the original package type.
Authentication: All API requests must include the following headers:
The HMAC signature must be generated for each request using:
Note: Swagger UI cannot be used to test the API directly as each request requires a unique HMAC signature. Please implement the authentication in your client application.
Example Node.js Implementation:
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) {
//Timestamp is in milliseconds e.g. 1715558400000
const timestamp = Math.floor(Date.now()).toString();
// Ensure url is a string
let path = String(url);
// Remove baseUrl from the url if present
path = processedUrl.replace(baseUrl, '');
// Create query string if needed
const queryString = new URL(url).search;
if (queryString) {
processedUrl += queryString;
}
// Validate public key
if (!publicKey) {
throw new Error("Public key is required");
}
// Create the payload
// Sample payload: 1715558400000GET/bookings?bookingId=1234567890
const payload = timestamp + method + path;
// 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'
};
}Need Help?
Per-package usage event data. These events are emitted per package, not per eSIM. For data-limited packages, thresholds are based on data consumption. For time-limited packages, thresholds are based on duration elapsed.
Type of package
{ "event": "package.usage.20_percent", "timestamp": "2019-08-24T14:15:22Z", "data": { "external_user_id": "partner_user_456", "booking_id": "booking_abc", "package_id": "pkg_xyz", "destination": "GR", "size": "1GB", "package_type": "data-limited", "used_bytes": 858993459, "remaining_bytes": 214748365, "duration_days": 30, "elapsed_days": 24, "remaining_days": 6, "usage_percent": 80 } }
Per-package usage event data. These events are emitted per package, not per eSIM. For data-limited packages, thresholds are based on data consumption. For time-limited packages, thresholds are based on duration elapsed.
Type of package
{ "event": "package.usage.50_percent", "timestamp": "2019-08-24T14:15:22Z", "data": { "external_user_id": "partner_user_456", "booking_id": "booking_abc", "package_id": "pkg_xyz", "destination": "GR", "size": "1GB", "package_type": "data-limited", "used_bytes": 858993459, "remaining_bytes": 214748365, "duration_days": 30, "elapsed_days": 24, "remaining_days": 6, "usage_percent": 80 } }
Per-package usage event data. These events are emitted per package, not per eSIM. For data-limited packages, thresholds are based on data consumption. For time-limited packages, thresholds are based on duration elapsed.
Type of package
{ "event": "package.usage.80_percent", "timestamp": "2019-08-24T14:15:22Z", "data": { "external_user_id": "partner_user_456", "booking_id": "booking_abc", "package_id": "pkg_xyz", "destination": "GR", "size": "1GB", "package_type": "data-limited", "used_bytes": 858993459, "remaining_bytes": 214748365, "duration_days": 30, "elapsed_days": 24, "remaining_days": 6, "usage_percent": 80 } }
{ "event": "esim.installed", "timestamp": "2019-08-24T14:15:22Z", "data": { "external_user_id": "partner_user_456", "booking_id": "booking_abc", "iccid": "8901234567890123456" } }
{ "event": "esim.removed", "timestamp": "2019-08-24T14:15:22Z", "data": { "external_user_id": "partner_user_456", "booking_id": "booking_abc", "iccid": "8901234567890123456" } }
{ "event": "package.activated", "timestamp": "2019-08-24T14:15:22Z", "data": { "external_user_id": "partner_user_456", "booking_id": "booking_abc", "package_id": "pkg_xyz", "destination": "GR", "size": "1GB", "activated_at": "2026-07-15T16:00:00Z", "expires_at": "2027-07-15T16:00:00Z" } }
{ "event": "promo_code.redeemed", "timestamp": "2019-08-24T14:15:22Z", "data": { "promocode": "SUMMER2026GR", "booking_id": "booking_abc", "redeemed_at": "2026-07-10T12:00:00Z" } }
Triggered when the booking's departure date enters the configured cutoff window (default: 7 days). This is the optimal time for travelers to install their eSIM while still at home on Wi-Fi. The esim_installed field indicates whether the traveler has already installed — use it to decide whether to send an installation reminder or a confirmation.
Event-specific payload
ISO 8601 departure datetime with timezone
{ "event": "booking.within_cutoff", "timestamp": "2019-08-24T14:15:22Z", "data": { "external_user_id": "partner_user_456", "booking_id": "booking_abc", "departure_date": "2026-07-15T14:30:00+02:00", "days_until_departure": 7, "esim_installed": false } }
Triggered when departure is imminent (default: 2 hours before the time in departure_date). This is the last-chance reminder for travelers who haven't installed their eSIM. Requires a full datetime with timezone in departure_date (e.g., 2026-07-15T14:30:00+02:00) — if only a date string was provided, this event cannot fire.
Event-specific payload
ISO 8601 departure datetime with timezone
{ "event": "booking.about_to_depart", "timestamp": "2019-08-24T14:15:22Z", "data": { "external_user_id": "partner_user_456", "booking_id": "booking_abc", "departure_date": "2026-07-15T14:30:00+02:00", "hours_until_departure": 2, "esim_installed": false } }