Promo Code Claiming
Overview
Instead of sending promo codes directly, you can share claim links that allow users to receive promo codes via email after providing their email address. This is useful for events, marketing campaigns, or any scenario where you want to capture user emails at the point of claim.
How It Works
- Create a booking without an email address
- Get a claim URL in the response
- Share the claim URL with your users
- Users visit the link, enter their email, and receive the promo code instantly
Creating a Claim Link
Create a booking without providing an email address:
curl -X POST https://api.hubbyesim.com/api/bookings \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-H "x-timestamp: TIMESTAMP" \
-H "x-signature: SIGNATURE" \
-d '{
"departure_date": "2026-01-03",
"booking_id": "EVENT-001",
"package_specifications": [
{
"destination": "TUR",
"package_type": "data-limited",
"size": "1GB"
}
]
}'Response
{
"success": true,
"data": [{
"id": "booking_id",
"promo_codes": [
{
"promo_code": "ABC123XYZ",
"uuid": "550e8400-e29b-41d4-a716-446655440000",
"claim_url": "https://platform.hubbyesim.com/free-esim/company-name?uuid=550e8400-e29b-41d4-a716-446655440000",
"deep_link_url": "https://hubby-esim.web.app/starter/?promoCode=ABC123XYZ",
"package_id": "...",
"package_size": "1GB",
"destination": "Turkey",
"iso3": "TUR",
"package_type": "data-limited",
"package_duration": 365
}
]
}]
}Claiming a Promo Code
Users can claim the promo code by visiting the claim_url or by calling the API directly:
curl -X POST https://api.hubbyesim.com/api/promo-codes/claim/550e8400-e29b-41d4-a716-446655440000 \
-H "Content-Type: application/json" \
-d '{
"email": "user@example.com"
}'Response
{
"success": true,
"message": "Promo code claimed and email sent successfully",
"data": {}
}The user immediately receives an email with the promo code.
Use Cases
Event Registration
Share claim links with event attendees to capture their email addresses and provide them with eSIM promo codes.
Marketing Campaigns
Distribute claim links through various channels (email, SMS, QR codes) to track engagement and capture leads.
Partner Integrations
Embed claim functionality in partner websites or apps without requiring direct promo code distribution.
Retrieving Promo Code Details
Partners can retrieve promo code details using the authenticated endpoint:
curl -X GET https://api.hubbyesim.com/api/promo-codes/ABC123XYZ \
-H "x-api-key: YOUR_API_KEY" \
-H "x-timestamp: TIMESTAMP" \
-H "x-signature: SIGNATURE"Response
{
"success": true,
"message": "Promo code fetched successfully!",
"data": {
"promo_code": "ABC123XYZ",
"uuid": "550e8400-e29b-41d4-a716-446655440000",
"claim_url": "https://platform.hubbyesim.com/free-esim/company-name?uuid=...",
"deep_link_url": "https://hubby-esim.web.app/starter/?promoCode=ABC123XYZ",
"package_id": "...",
"package_size": "1GB",
"destination": "Turkey",
"iso3": "TUR",
"package_type": "data-limited",
"package_duration": 365,
"traffic_policy": null
}
}Note: Partners can only access promo codes belonging to their organization.
Important Notes
- Email Template Required: Your partner account must have a valid Brevo template configured for promo code delivery emails
- One-Time Claim: Each UUID can only be claimed once
- Expiration: Promo codes follow standard expiration rules
- No Authentication: The claim endpoint is public and doesn't require API authentication
- Backward Compatible: Existing promo codes without UUIDs continue to work normally
Error Handling
Common error responses:
Already Claimed (400)
{
"success": false,
"error": {
"code": 400,
"message": "Promo code has already been claimed"
}
}Expired (400)
{
"success": false,
"error": {
"code": 400,
"message": "Promo code is no longer valid"
}
}Not Found (404)
{
"success": false,
"error": {
"code": 404,
"message": "UUID not found"
}
}