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?
Returns everything needed to render any screen in a native eSIM integration: user info, package queues, current eSIM state, active packages, and partner details.
This is the central endpoint for the Native eSIM Integration. One call gives you the traveler's full state.
When to call:
Authentication: HMAC-SHA256 (same as all partner endpoints).
curl -i -X GET \
'https://docs.hubbyesim.com/_mock/apis/openapi/native/user-dashboard?external_user_id=user_abc123'{ "success": true, "data": { "user": { … }, "package_queues": [ … ], "current_esim": { … }, "current_esim_packages": [ … ], "partner": { … } } }
Returns AI-generated, device-specific eSIM installation instructions tailored to the traveler's exact device model, OS version, locale, and current eSIM state.
The service resolves the user's eSIM status, activation string, and partner visual identity automatically from the external_user_id, then generates branded, device-aware instructions.
You do not need to hard-code or maintain installation content in your app — Hubby keeps instructions current for every device and OS version.
Authentication: HMAC-SHA256 (same as all partner endpoints).
curl -i -X POST \
https://docs.hubbyesim.com/_mock/apis/openapi/native/instructions \
-H 'Content-Type: application/json' \
-d '{
"format": "html",
"external_user_id": "user_abc123",
"deviceName": "Google Pixel 10",
"deviceType": "phone",
"os": "android",
"osVersion": "15",
"locale": "mk-MK"
}'{ "success": true, "data": {} }
curl -i -X POST \
https://docs.hubbyesim.com/_mock/apis/openapi/native/device-compatibility \
-H 'Content-Type: application/json' \
-d '{
"phone_brand": "Google",
"phone_model": "Pixel 10",
"phone_os": "android",
"os_version": "15"
}'{ "success": true, "data": { "phone_brand": "Google", "phone_model": "Pixel 10", "phone_os": "android", "os_version": "15", "is_compatible": true } }
curl -i -X GET \
https://docs.hubbyesim.com/_mock/apis/openapi/native/device-compatibility{ "success": true, "data": { "devices": [ … ] } }
Redeems a package queue entry, provisioning the package onto the traveler's universal eSIM. The package queue entry is consumed and the eSIM is updated with the new package.
Use the package_queue_id from the user dashboard response (GET /native/user-dashboard) to identify which package queue to redeem.
Authentication: HMAC-SHA256 (same as all partner endpoints).
curl -i -X POST \
https://docs.hubbyesim.com/_mock/apis/openapi/native/redeem-package \
-H 'Content-Type: application/json' \
-d '{
"external_user_id": "user_abc123",
"package_queue_id": "pq_xyz789"
}'{ "success": true, "message": "Package queue redeemed successfully", "data": { "packageQueue": { … }, "current_esim": { … }, "current_esim_packages": [ … ] } }