List all bookings

Hubby API (2.1.0)

Welcome to the Hubby API documentation. This API enables partners to seamlessly integrate eSIM booking and management capabilities into their applications.

Key Features:

Create and manage eSIM bookings for your customers
Access our global package catalog with country-specific offerings
Track booking statuses and package activations
Support for multiple package types (starter, data-limited, unlimited, time-limited)

Package Types

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:

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

The HMAC signature must be generated for each request using:

Concatenate: timestamp + HTTP method + request path Example: "1678901234GET/bookings"
Generate HMAC-SHA256 using your secret key
Convert to hex string

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?

Technical Support: support@hubbyesim.com

Download OpenAPI description

openapi.json

openapi.yaml

Servers

Mock server

https://docs.hubbyesim.com/_mock/apis/openapi/

Production server

https://europe-west4-hubby-esim.cloudfunctions.net/api_v2/

Booking

Operations

List all bookings

Request

Retrieves a paginated list of bookings for the authenticated partner. The response is always fresh and not cached (uses Cache-Control headers).

Query

perPageinteger

Number of records to return per page (minimum 1)

Default 10

cursorstring

Cursor for pagination (use nextCursor/prevCursor from previous response)

curl -i -X GET \
  'https://docs.hubbyesim.com/_mock/apis/openapi/bookings?cursor=string&perPage=10'

Responses

A paginated list of bookings

Bodyapplication/json

successboolean

Example: true

messagestring

Example: "Success message"

dataArray of objects(BookingResponse)

paginationobject(PaginationMeta)

Response

application/json

{
  "success": true,
  "message": "Success message",
  "data": [
    { … }
  ],
  "pagination": {
    "perPage": 0,
    "hasNextPage": true,
    "hasPrevPage": true,
    "nextCursor": "string",
    "prevCursor": "string"
  }
}

Create a new booking

Request

Creates a new booking with the specified details. The booking is identified by the email or booking_id parameter. When no package specifications are provided, the end user will be queried for the destination and size will be determined by the partner settings.

Bodyapplication/jsonrequired

departure_datestring(date-time)required

ISO 8601 departure date. Example: '2026-01-03'.

return_datestring(date-time)

ISO 8601 return date. Must be after departure_date. Optional if not provided by the partner.

emailstring(email)

Traveler's email. Required if booking_id is not provided.

booking_idstring>= 3 characters

Booking ID. Required if email is not provided.

external_idstring or null[ 3 .. 100 ] characters

External ID Usable by your organization to further identify the booking (optional).

phonestring^\+\d{1,3}\d{1,14}$

Phone number in E.164 format (e.g., +123456789).

first_namestring[ 1 .. 100 ] characters

last_namestring[ 1 .. 100 ] characters

full_namestring[ 1 .. 200 ] characters

titlestring

Enum"mr.""ms.""mrs.""miss""dr.""prof."

paxinteger>= 1

Number of passengers.

flight_numberstring^[a-zA-Z0-9]{1,10}$

genderstring

Enum"M""F""O"

date_of_birthstring(date-time)

Date of birth in ISO 8601 format.

localestring[ 2 .. 5 ] characters

Locale or language code (e.g., "en", "nl").

dataobject

Additional metadata about the booking.

communication_optionsobject

Optional communication preferences for sending messages. If not provided, messages will not be sent.

custom_brandingstring or null

Sets a specific visual style for the app experience. The brand identifier must correspond to a brand configuration that exists in the Hubby platform. Contact support to set up custom branding for your organization.

departure_locationstring or null

The departure location for the booking (e.g., airport code, city name, or address). Used to provide context about where the traveler is departing from.

package_specificationsArray of objectsnon-emptyrequired

A list of package specifications. At least one entry is required. Each entry is resolved either by package_id (direct reference) or by other properties (destination, size, package_type, etc.); when package_id is present, other fields in that entry are ignored for resolution.

package_specifications[].external_user_idstring

Your own identifier for the traveler receiving this package.

⚠️ This field is required for Hubby WebView and Native eSIM Integration. Omit it for all other integration types — it is ignored in the traditional booking flow (email-based delivery, promo codes, etc.) and supplying it incorrectly will route the package into the eSIM management flow.

With external_user_id (required for WebView and Native): The package is linked to the traveler's universal eSIM. Use the same value across all subsequent calls (redirect tokens, dashboard, redeem, top-ups).
Without external_user_id (traditional flow): The package follows the standard booking flow. The field is ignored.

Example: "user_abc123"

package_specifications[].destinationstring or Array of strings

Destination code(s) for the booking. Can be a single destination or an array of destinations for multi-destination trips with ESIM optimization. (optional)

One of:

Destination code(s) for the booking. Can be a single destination or an array of destinations for multi-destination trips with ESIM optimization. (optional)

string^[A-Z]{2,3}$

Destination code(s) for the booking. Can be a single destination or an array of destinations for multi-destination trips with ESIM optimization. (optional)

package_specifications[].sizestring^[0-9]\d*(\.\d+)?(MB|GB)$

Package size (e.g., '500MB', '1GB', '3GB', '5GB', '10GB', '20GB')

package_specifications[].package_idstring

Identifier for the package (optional).

package_specifications[].package_typestring

Type of package to create.

data-limited: Traditional packages with specific data allowance (default)
time-limited: Unlimited data for a specific duration
starter: Both data and time limited packages

Default "data-limited"

Enum"starter""data-limited""unlimited""time-limited"

package_specifications[].package_durationinteger>= 1

Duration of the package in days.

Defaults to 365 days for data-limited packages
Defaults to 2 days for starter and time-limited packages

Default 365

curl -i -X POST \
  https://docs.hubbyesim.com/_mock/apis/openapi/bookings \
  -H 'Content-Type: application/json' \
  -d '{
    "departure_date": "2019-08-24T14:15:22Z",
    "return_date": "2019-08-24T14:15:22Z",
    "email": "user@example.com",
    "booking_id": "string",
    "external_id": "string",
    "phone": "string",
    "first_name": "string",
    "last_name": "string",
    "full_name": "string",
    "title": "mr.",
    "pax": 1,
    "flight_number": "string",
    "gender": "M",
    "date_of_birth": "2019-08-24T14:15:22Z",
    "locale": "strin",
    "data": {},
    "communication_options": {
      "should_send_message": true,
      "channels": [
        "EMAIL"
      ]
    },
    "custom_branding": "string",
    "departure_location": "string",
    "package_specifications": [
      {
        "external_user_id": "user_abc123",
        "destination": "string",
        "size": "string",
        "package_id": "string",
        "package_type": "starter",
        "package_duration": 365
      }
    ]
  }'

Responses

Successful response

Bodyapplication/json

successboolean

Example: true

messagestring

Example: "Success message"

dataArray of objects(BookingResponse)

Response

application/json

{
  "success": true,
  "message": "Success message",
  "data": [
    { … }
  ]
}

Get booking details

Request

Retrieves details of a specific booking

Path

idstringrequired

Booking ID

curl -i -X GET \
  'https://docs.hubbyesim.com/_mock/apis/openapi/bookings/{id}'

Responses

Successful response

Bodyapplication/json

successboolean

Example: true

messagestring

Example: "Success message"

dataobject(BookingResponse)

Response

application/json

{
  "success": true,
  "message": "Success message",
  "data": {
    "external_id": "string",
    "id": "string",
    "title": "string",
    "first_name": "string",
    "last_name": "string",
    "full_name": "string",
    "pax": 0,
    "email": "user@example.com",
    "phone": "string",
    "booking_id": "string",
    "return_date": "2019-08-24T14:15:22Z",
    "departure_date": "2019-08-24T14:15:22Z",
    "gender": "M",
    "locale": "string",
    "promo_codes": [ … ],
    "created_at": "2019-08-24T14:15:22Z",
    "updated_at": "2019-08-24T14:15:22Z",
    "created_by": "string",
    "updated_by": "string",
    "custom_branding": "string",
    "departure_location": "string"
  }
}

Cancel booking

Request

Cancels a specific booking by setting its status to CANCELLED and anonymizing all personal data fields.

The following fields are hashed with MD5 using a configurable salt (ANONYMIZATION_SALT environment variable): first_name, last_name, full_name, phone, flight_number, departure_location. The email field is replaced with a non-identifiable address. Fields title, gender, and pax are cleared. The booking_id and external_id are preserved intact.

The booking record is not deleted from the database.

Path

idstringrequired

Booking ID

curl -i -X DELETE \
  'https://docs.hubbyesim.com/_mock/apis/openapi/bookings/{id}'

Responses

Successful response

Bodyapplication/json

successboolean

Example: true

messagestring

Example: "Success message"

dataobject

Empty object

Example: {}

Response

application/json

{
  "success": true,
  "message": "Success message",
  "data": {}
}

Cancel booking by booking ID

Request

Cancels a booking using its external booking ID by setting its status to CANCELLED and anonymizing all personal data fields.

The booking record is not deleted from the database.

Path

idstringrequired

External booking ID (booking_id)

curl -i -X DELETE \
  'https://docs.hubbyesim.com/_mock/apis/openapi/bookings/{id}/byExternalBookingId'

Responses

Successful response

Bodyapplication/json

successboolean

Example: true

messagestring

Example: "Success message"

dataobject

Empty object

Example: {}

Response

application/json

{
  "success": true,
  "message": "Success message",
  "data": {}
}

Update all promo codes for a booking

Request

Updates the package_specification on all promo codes for the booking. Promo codes that have already been used are skipped; the response includes updated_count and skipped_count.

Authentication: HMAC keys.

Path

booking_idstringrequired

The external booking ID (e.g. "BK-12345").

Bodyapplication/jsonrequired

package_specificationobject(PackageSpecification)required

Package specification for updating promo codes. At least one of package_id or package_type must be provided.

When only package_id is sent: The package's properties (package_type, size, package_duration, destination) are resolved automatically from the referenced package.

When package_id is sent with package_type: The explicit fields from the request body are used instead of the package's own properties.

When only package_type is sent: The conditional field requirements apply based on the type.

Package type requirements:

data-limited — size: required, package_duration: not required
time-limited — size: required, package_duration: required
unlimited — size: not required, package_duration: required
starter — size: required, package_duration: required

package_specification.package_idstring

ID of an existing package. At least one of package_id or package_type must be provided.

When package_id is provided without package_type: The package's properties (package_type, size, package_duration, destination) are resolved automatically from the referenced package.

When package_id is provided with package_type: The explicit fields from the request body are used instead of the package's own properties.

package_specification.package_typestring

Type of package. At least one of package_id or package_type must be provided.

starter: Small data allowance for short duration, ideal for trials
data-limited: Traditional packages with specific data allowance
unlimited: Unrestricted data usage with fair use policy
time-limited: Fixed data allowance with time constraint for full-speed access

Enum"starter""data-limited""unlimited""time-limited"

package_specification.sizestring^[0-9]\d*(\.\d+)?(MB|GB)$

Package size (e.g. "1GB", "5GB"). Required when package_type is data-limited, time-limited, or starter. Not required for unlimited.

package_specification.package_durationinteger>= 1

Duration of the package in days. Required when package_type is time-limited, unlimited, or starter. Not required for data-limited.

package_specification.destinationstring or Array of strings

Country ISO3 code or IATA code, or an array for multi-destination. Optional — omit for destination-agnostic promo codes.

One of:

Country ISO3 code or IATA code, or an array for multi-destination. Optional — omit for destination-agnostic promo codes.

string^[A-Z]{2,3}$

Country ISO3 code or IATA code, or an array for multi-destination. Optional — omit for destination-agnostic promo codes.

curl -i -X PUT \
  'https://docs.hubbyesim.com/_mock/apis/openapi/bookings/{booking_id}/updatePackageSpecifications' \
  -H 'Content-Type: application/json' \
  -d '{
    "package_specification": {
      "package_id": "string",
      "package_type": "starter",
      "size": "string",
      "package_duration": 1,
      "destination": "ESP"
    }
  }'

Responses

Successfully updated package specifications. When some promo codes were skipped (already redeemed), message is "Updated N promo code(s). Skipped M already redeemed." and data includes both updated_count and skipped_count. When all promo codes were updated, message is "Successfully updated package specification for booking." and skipped_count is omitted.

Bodyapplication/json

successboolean

Example: true

messagestring

Example: "Updated 3 promo code(s). Skipped 1 already redeemed."

dataobject(UpdatePackageSpecForPromoCodesResponse)

Response

application/json

{
  "success": true,
  "message": "Updated 3 promo code(s). Skipped 1 already redeemed.",
  "data": {
    "external_id": "string",
    "id": "string",
    "title": "string",
    "first_name": "string",
    "last_name": "string",
    "full_name": "string",
    "pax": 0,
    "email": "user@example.com",
    "phone": "string",
    "booking_id": "string",
    "return_date": "2019-08-24T14:15:22Z",
    "departure_date": "2019-08-24T14:15:22Z",
    "gender": "M",
    "locale": "string",
    "promo_codes": [ … ],
    "created_at": "2019-08-24T14:15:22Z",
    "updated_at": "2019-08-24T14:15:22Z",
    "created_by": "string",
    "updated_by": "string",
    "custom_branding": "string",
    "departure_location": "string",
    "updated_count": 0,
    "skipped_count": 0
  }
}

Update a single promo code by UUID

Request

Updates the package_specification on only the promo code whose uuid matches the path parameter. If that promo code is already redeemed, the API returns 400 Bad Request.

Authentication: HMAC keys.

Path

booking_idstringrequired

The external booking ID.

uuidstring(uuid)required

The promo code's UUID.

Bodyapplication/jsonrequired

package_specificationobject(PackageSpecification)required

Package specification for updating promo codes. At least one of package_id or package_type must be provided.

When only package_id is sent: The package's properties (package_type, size, package_duration, destination) are resolved automatically from the referenced package.

When package_id is sent with package_type: The explicit fields from the request body are used instead of the package's own properties.

When only package_type is sent: The conditional field requirements apply based on the type.

Package type requirements:

data-limited — size: required, package_duration: not required
time-limited — size: required, package_duration: required
unlimited — size: not required, package_duration: required
starter — size: required, package_duration: required

package_specification.package_idstring

ID of an existing package. At least one of package_id or package_type must be provided.

When package_id is provided without package_type: The package's properties (package_type, size, package_duration, destination) are resolved automatically from the referenced package.

When package_id is provided with package_type: The explicit fields from the request body are used instead of the package's own properties.

package_specification.package_typestring

Type of package. At least one of package_id or package_type must be provided.

starter: Small data allowance for short duration, ideal for trials
data-limited: Traditional packages with specific data allowance
unlimited: Unrestricted data usage with fair use policy
time-limited: Fixed data allowance with time constraint for full-speed access

Enum"starter""data-limited""unlimited""time-limited"

package_specification.sizestring^[0-9]\d*(\.\d+)?(MB|GB)$

Package size (e.g. "1GB", "5GB"). Required when package_type is data-limited, time-limited, or starter. Not required for unlimited.

package_specification.package_durationinteger>= 1

Duration of the package in days. Required when package_type is time-limited, unlimited, or starter. Not required for data-limited.

package_specification.destinationstring or Array of strings

Country ISO3 code or IATA code, or an array for multi-destination. Optional — omit for destination-agnostic promo codes.

One of:

Country ISO3 code or IATA code, or an array for multi-destination. Optional — omit for destination-agnostic promo codes.

string^[A-Z]{2,3}$

Country ISO3 code or IATA code, or an array for multi-destination. Optional — omit for destination-agnostic promo codes.

curl -i -X PUT \
  'https://docs.hubbyesim.com/_mock/apis/openapi/bookings/{booking_id}/updatePackageSpecification/{uuid}' \
  -H 'Content-Type: application/json' \
  -d '{
    "package_specification": {
      "package_id": "string",
      "package_type": "starter",
      "size": "string",
      "package_duration": 1,
      "destination": "ESP"
    }
  }'

Responses

Successfully updated the single promo code. updated_count is always 1; there is no skipped_count.

Bodyapplication/json

successboolean

Example: true

messagestring

Example: "Successfully updated package specification for booking."

dataobject(UpdatePackageSpecForPromoCodesResponse)

Response

application/json

{
  "success": true,
  "message": "Successfully updated package specification for booking.",
  "data": {
    "external_id": "string",
    "id": "string",
    "title": "string",
    "first_name": "string",
    "last_name": "string",
    "full_name": "string",
    "pax": 0,
    "email": "user@example.com",
    "phone": "string",
    "booking_id": "string",
    "return_date": "2019-08-24T14:15:22Z",
    "departure_date": "2019-08-24T14:15:22Z",
    "gender": "M",
    "locale": "string",
    "promo_codes": [ … ],
    "created_at": "2019-08-24T14:15:22Z",
    "updated_at": "2019-08-24T14:15:22Z",
    "created_by": "string",
    "updated_by": "string",
    "custom_branding": "string",
    "departure_location": "string",
    "updated_count": 0,
    "skipped_count": 0
  }
}

Destination

Operations

PromoCode

Operations

eSIM

Operations

WebView

Operations

Native eSIM Integration

Operations

Hubby API (2.1.0)

Package Types

Booking

List all bookings

Request

Responses

Was this helpful?

Create a new booking

Request

Responses

Was this helpful?

Get booking details

Request

Responses

Was this helpful?

Cancel booking

Request

Responses

Was this helpful?

Cancel booking by booking ID

Request

Responses

Was this helpful?

Update all promo codes for a booking

Request

Responses

Was this helpful?

Update a single promo code by UUID

Request

Responses

Was this helpful?

Destination

PromoCode

eSIM

WebView

Native eSIM Integration

Webhooks

Hubby API (2.1.0)

Package Types

Booking

List all bookings

Request

Responses

Was this helpful?

Create a new booking

RequestExpand all

Responses

Was this helpful?

Get booking details

Request

Responses

Was this helpful?

Cancel booking

Request

Responses

Was this helpful?

Cancel booking by booking ID

Request

Responses

Was this helpful?

Update all promo codes for a booking

RequestExpand all

Responses

Was this helpful?

Update a single promo code by UUID

RequestExpand all

Responses

Was this helpful?

Destination

PromoCode

eSIM

WebView

Native eSIM Integration

Webhooks

Request

Request

Request