HotelHero API Reference

This guide provides detailed information about the HotelHero API endpoints, including request formats, response structures, and examples to help you integrate your applications with our travel platform.

API Overview

The HotelHero API provides comprehensive access to our travel platform services. With our API, you can:

Access detailed information about hotels, cities, and destinations
Search for hotel availability based on various criteria
Create and manage hotel bookings
Integrate our travel data seamlessly into your applications

This reference provides all the information you need to successfully integrate with our API.

Refer to the Authentication section for more information on how to authenticate your requests.

Base URL

All endpoints use the following base URL:

API Base URL

https://api.hotelhero.net/v2

Endpoints Overview

The HotelHero API is organized into two main categories:

Content API: Access static content like hotel information, city data, and region details.
Booking API: Perform dynamic operations such as searching for availability, creating bookings, and managing reservations.

Each endpoint follows RESTful principles and returns responses in JSON format. The following sections provide detailed information about each endpoint, including request parameters, response formats, and example usage.

Additionally, we offer PDF generation capabilities for hotel vouchers and offers through dedicated endpoints. These are particularly useful for creating customer-facing documents. (Currently not available)

Hotels

Endpoint	Method	Description
`/hotels`	GET	Retrieve a list of all hotels
`/hotels/:id`	GET	Get detailed information about a specific hotel

Cities

Endpoint	Method	Description
`/cities`	GET	Retrieve a list of all cities

Regions

Endpoint	Method	Description
`/regions`	GET	Retrieve a list of all regions/destinations

Hotel Availability

Endpoint	Method	Description
`/availability/search`	POST	Search for hotel availability with specified criteria

Booking

Endpoint	Method	Description
`/booking/create`	POST	Create a checkout session for a selected hotel offer
`/booking/complete`	POST	Complete a booking with guest details
`/booking/cancel`	POST	Cancel an existing booking
`/booking/:id`	GET	Retrieve details of a specific booking

API Endpoints

The following endpoints provide access to detailed information about getting data about hotels, cities, and countries, bookings, and more.

Below you'll find detailed documentation for each endpoint, including request parameters, response formats, and example usage.

Content API

The Content API provides access to static data about hotels, cities, and countries.

Get Hotels

Retrieves a list of all hotels.

Request

GET /hotels

https://api.hotelhero.net/v2/hotels

Query Parameters

Parameter	Type	Description
`limit`	integer	Maximum number of hotels to return (default: 10)
`page`	integer	Page number for pagination

Headers

Content-Type: application/json
api_key: YOUR_API_KEY

Examples

curl https://api.hotelhero.net/v2/hotels?limit=10 \
-H "Content-Type: application/json" \
-H "api_key: YOUR_API_KEY"

Response

Example response

{
  "count": 32942,
  "next": "https://api.hotelhero.net/v2/hotels?limit=10&offset=10",
  "previous": null,
  "results": [
    {
      "id": "HH-1153116",
      "name": "Kordistos Beach",
      "address": "85301 Kefalos",
      "rating": 2,
      "guest_rating": {
        "count": 14,
        "comfort": "7.8",
        "overall": "9.0",
        "service": "8.2",
        "amenities": "8.8",
        "condition": "8.2",
        "cleanliness": "9.0"
      },
      "city": "Kefalos",
      "latitude": 36.751608,
      "longitude": 26.980724,
      "country": "Greece",
      "country_iso": "GR"
    }
    // More hotels...
  ]
}

Get Hotel Details

Retrieves detailed information about a specific hotel.

Request

GET /hotels/{id}

https://api.hotelhero.net/v2/hotels/{id}

Parameters

Parameter	Type	Description
`id`	string	HotelHero ID (e.g., HH-0000123)

Headers

Content-Type: application/json
api_key: YOUR_API_KEY

Example

curl https://api.hotelhero.net/v2/hotels/HH-0000123 \
-H "Content-Type: application/json" \
-H "api_key: YOUR_API_KEY"

Response

Example response

{
  "id": "HH-1153116",
  "name": "Kordistos Beach",
  "location": {
    "address_1": "Kefalos",
    "address_2": "Kos",
    "longitude": 26.980724,
    "latitude": 36.751608,
    "city": "Kefalos",
    "country": "Greece",
    "country_iso": "GR",
    "post_code": "85301"
  },
  "description": "When you stay at Kordistos Hotel in Kos...",
  "phone": "+3023443251",
  "email": "info@website.com",
  "url": "https://www.website.com",
  "facilities": [
    {
      "name": "facility_safe"
    },
    {
      "name": "facility_restaurants"
    }
    // More facilities
  ],
  "rating": 2,
  "guest_rating": {
    "count": 14,
    "comfort": "7.8",
    "overall": "9.0",
    "service": "8.2",
    "amenities": "8.8",
    "condition": "8.2",
    "cleanliness": "9.0"
  },
  "checkin_policy": "Check-in from 14:00, Early check-in subject to availability",
  "checkout_policy": "Check-out until 11:00, Late check-out subject to availability",
  "fees": "Tourist tax €4 per room per night payable at the hotel",
  "policies": "Pets not allowed. All children are welcome."
}

Get Cities

Retrieves a list of all cities.

Request

GET /cities

https://api.hotelhero.net/v2/cities

Query Parameters

Parameter	Type	Description
`limit`	integer	Maximum number of cities to return (default: 20)
`page`	integer	Page number for pagination

Headers

Content-Type: application/json
api_key: YOUR_API_KEY

Example

curl https://api.hotelhero.net/v2/cities?limit=10 \
-H "Content-Type: application/json" \
-H "api_key: YOUR_API_KEY"

Response

Example response

{
  "count": 350,
  "next": "https://api.hotelhero.net/v2/cities?limit=10&offset=10",
  "previous": null,
  "results": [
    {
      "id": "c1d2e3f4-5678-90gh-ijkl-mnopqrstuvwx",
      "name": "Athens",
      "country": "Greece",
      "country_iso": "GR"
    },
    {
      "id": "y9z8a7b6-5432-10cd-efgh-ijklmnopqrst",
      "name": "Thessaloniki",
      "country": "Greece",
      "country_iso": "GR"
    }
    // More cities...
  ]
}

Get Regions

Retrieves a list of all regions/destinations.

Request

GET /regions

https://api.hotelhero.net/v2/regions

Query Parameters

Parameter	Type	Description
`limit`	integer	Maximum number of regions to return (default: 20)
`page`	integer	Page number for pagination

Headers

Content-Type: application/json
api_key: YOUR_API_KEY

Example

curl https://api.hotelhero.net/v2/regions?limit=10 \
-H "Content-Type: application/json" \
-H "api_key: YOUR_API_KEY"

Response

Example response

{
  "count": 120,
  "next": "https://api.hotelhero.net/v2/regions?limit=10&offset=10",
  "previous": null,
  "results": [
    {
      "id": "d4e5f6g7-8901-23hi-jklm-nopqrstuvwxy",
      "name": "Halkidiki",
      "country": "Greece",
      "country_iso": "GR"
    },
    {
      "id": "z0a1b2c3-4567-89de-fghi-jklmnopqrstu",
      "name": "Cyclades",
      "country": "Greece",
      "country_iso": "GR"
    }
    // More regions...
  ]
}

Booking API

The Booking API allows you to search for hotel availability, create checkout sessions, and complete bookings.

Search Hotel Availability

Search for hotel availability based on specified criteria.

Request

POST /availability/search

https://api.hotelhero.net/v2/availability/search

Headers

Content-Type: application/json
api_key: YOUR_API_KEY

Request Body

{
  "check_in": "2025-12-20",
  "check_out": "2025-12-25",
  "rooms": [
    {
      "adults": 2,
      "children": [5, 8]
    }
  ],
  "hotel_id": "HH-0000123"
}

You must include ONE of the following location parameters:

hotel_id: Single HotelHero ID or array of IDs
city_id: UUID of a city
region_id: UUID of a region/destination
country: Country name

Example

curl -X POST https://api.hotelhero.net/v2/availability/search \
-H "Content-Type: application/json" \
-H "api_key: YOUR_API_KEY" \
-d '{
  "check_in": "2025-12-20",
  "check_out": "2025-12-25",
  "rooms": [
    {
      "adults": 2,
      "children": [5, 8]
    }
  ],
  "hotel_id": "HH-0000123"
}'

Response

Example response

{
  "search_id": "5f8e7d6c-9b3a-4f2e-8d7c-6b5a4f3e2d1c",
  "results_count": 3,
  "search_time_ms": 340,
  "check_in": "2025-09-20",
  "check_out": "2025-09-25",
  "results": [
    {
      "hotel_id": "HH-0000123",
      "hotel_name": "Anthemus Sea Beach Hotel & Spa",
      "rates": [
        {
          "rate_id": "ANT-DEL-20231220-5N-2A2C-BB",
          "room_type": "Deluxe Family Room Sea View",
          "boarding": "BB",
          "price": 850.0,
          "currency": "EUR",
          "cancellation_policy": {
            "cancellation_deadline": "2025-12-04T16:00:00",
            "from_dates": ["2025-12-04T16:00:00"],
            "penalty_fees": [100]
          },
          "non_refundable": false
        }
        // More rates...
      ]
    }
    // More hotel offers...
  ],
  "expires_at": "2025-09-15T22:30:00"
}

Create Checkout Session

Create a checkout session for a selected hotel offer from a previous search.

Request

POST /booking/create

https://api.hotelhero.net/v2/booking/create

Headers

Content-Type: application/json
api_key: YOUR_API_KEY

Request Body

{
  "search_id": "5f8e7d6c-9b3a-4f2e-8d7c-6b5a4f3e2d1c",
  "rate_id": "ANT-DEL-20231220-5N-2A2C-BB",
  "booking_period": {
    "check_in": "2025-09-20",
    "check_out": "2025-09-25"
  }
}

Example

curl -X POST https://api.hotelhero.net/v2/booking/create \
-H "Content-Type: application/json" \
-H "api_key: YOUR_API_KEY" \
-d '{
  "search_id": "5f8e7d6c-9b3a-4f2e-8d7c-6b5a4f3e2d1c",
  "rate_id": "ANT-DEL-20231220-5N-2A2C-BB",
  "booking_period": {
    "check_in": "2025-09-20",
    "check_out": "2025-09-25",
  }
}'

Response

Example response

{
  "checkout_id": "be88a0f5-681f-4ff7-b317-9bc2e357907b",
  "hotel": {
    "id": "HH-0000123",
    "name": "Anthemus Sea Beach Hotel & Spa",
    "address": "Elia Beach",
    "city": "Nikiti",
    "latitude": 40.2345,
    "longitude": 23.789,
    "country": "Greece",
    "country_iso": "GR",
    "rating": 5
  },
  "booking_period": {
    "check_in": "2025-09-20",
    "check_out": "2025-09-25",
    "nights": 5
  },
  "offer": {
    "rate_id": "ANT-DEL-20231220-5N-2A2C-BB",
    "room_type": "Deluxe Family Room Sea View",
    "boarding": "BB",
    "price": 850.0,
    "currency": "EUR",
    "cancellation_policy": {
      "cancellation_deadline": "2025-09-04T16:00:00",
      "from_dates": ["2025-09-04T16:00:00"],
      "penalty_fees": [100]
    },
    "non_refundable": false
  },
  "price": 850.0,
  "currency": "EUR",
  "created_at": "2025-09-15T17:30:45"
}

Complete Booking

Complete a booking by providing guest information.

Want to test your integration without creating real bookings? Try searching for hotel ID HH-TEST - see our Test Hotel documentation.

Request

POST /booking/complete

https://api.hotelhero.net/v2/booking/complete

Headers

Content-Type: application/json
api_key: YOUR_API_KEY

Request Body

{
  "checkout_id": "e3f4g5h6-i7j8-k9l0-m1n2-o3p4q5r6s7t8",
  "contact_person": {
    "first_name": "John",
    "last_name": "Smith",
    "email": "john.smith@example.com",
    "phone_number": "+306977777777"
  },
  "occupancy": [
    {
      "guests": [
        {
          "first_name": "John",
          "last_name": "Smith",
          "is_child": false
        },
        {
          "first_name": "Jane",
          "last_name": "Smith",
          "is_child": false
        },
        {
          "first_name": "David",
          "last_name": "Smith",
          "age": 5,
          "is_child": true
        },
        {
          "first_name": "Emma",
          "last_name": "Smith",
          "age": 8,
          "is_child": true
        }
      ]
    }
  ],
  "remarks": "Late arrival (after 10pm). Ground floor room preferred."
}

Example

curl -X POST https://api.hotelhero.net/v2/booking/complete \
-H "Content-Type: application/json" \
-H "api_key: YOUR_API_KEY" \
-d '{
  "checkout_id": "e3f4g5h6-i7j8-k9l0-m1n2-o3p4q5r6s7t8",
  "contact_person": {
    "first_name": "John",
    "last_name": "Smith",
    "email": "john.smith@example.com",
    "phone_number": "+306977777777"
  },
  "occupancy": [
    {
      "guests": [
        {
          "first_name": "John",
          "last_name": "Smith",
          "is_child": false
        },
        {
          "first_name": "Jane",
          "last_name": "Smith",
          "is_child": false
        },
        {
          "first_name": "David",
          "last_name": "Smith",
          "age": 5,
          "is_child": true
        },
        {
          "first_name": "Emma",
          "last_name": "Smith",
          "age": 8,
          "is_child": true
        }
      ]
    }
  ],
  "remarks": "Late arrival (after 10pm). Ground floor room preferred."
}'

Response

Example response

{
  "booking_id": "HHB-123456",
  "hotel": {
    "id": "HH-0000123",
    "name": "Anthemus Sea Beach Hotel & Spa",
    "address": "Elia Beach",
    "city": "Nikiti",
    "latitude": 40.2345,
    "longitude": 23.789,
    "country": "Greece",
    "country_iso": "GR",
    "rating": 5
  },
  "booking_period": {
    "check_in": "2025-09-20",
    "check_out": "2025-09-25",
    "nights": 5
  },
  "contact_person": {
    "first_name": "John",
    "last_name": "Smith",
    "email": "john.smith@example.com",
    "phone_number": "+306977777777"
  },
  "offer": {
    "rate_id": "ANT-DEL-20231220-5N-2A2C-BB",
    "room_type": "Deluxe Family Room Sea View",
    "boarding": "BB",
    "price": 850.0,
    "currency": "EUR",
    "cancellation_policy": {
      "cancellation_deadline": "2025-09-04T16:00:00",
      "from_dates": ["2025-09-04T16:00:00"],
      "penalty_fees": [100]
    },
    "non_refundable": false
  },
  "total_price": 850.0,
  "currency": "EUR",
  "status": "confirmed",
  "created_at": "2025-11-15T17:35:12+02:00",
  "occupancy": [
    {
      "title": "Family room",
      "adults": 2,
      "children": [5, 8],
      "boarding": "BB",
      "occupancy": [
        {
          "firstName": "John",
          "lastName": "Smith",
          "is_child": false
        },
        {
          "firstName": "Jane",
          "lastName": "Smith",
          "is_child": false
        },
        {
          "firstName": "David",
          "lastName": "Smith",
          "is_child": true,
          "age": 5
        },
        {
          "firstName": "Emma",
          "lastName": "Smith",
          "is_child": true,
          "age": 8
        }
      ]
    }
  ],
  "remarks": "Late arrival (after 10pm). Ground floor room preferred."
}

Cancel Booking

Cancel an existing booking.

Request

POST /booking/cancel

https://api.hotelhero.net/v2/booking/cancel

Headers

Content-Type: application/json
api_key: YOUR_API_KEY

Request Body

{
  "booking_id": "HHB-123456"
}

Example

curl -X POST https://api.hotelhero.net/v2/booking/cancel \
-H "Content-Type: application/json" \
-H "api_key: YOUR_API_KEY" \
-d '{
  "booking_id": "HHB-123456"
}'

Response

Example response

{
  "message": "Booking successfully cancelled.",
  "booking_id": "HHB-123456",
  "status": "cancelled",
  "cancellation_date": "2025-09-16T14:25:37",
  "refunded_amount": 850.0,
  "currency": "EUR"
}

Get Booking Details

Retrieve details of a specific booking.

Request

GET /booking/{booking_id}/

https://api.hotelhero.net/v2/booking/HHB-123456/

Parameters

Parameter	Type	Description
`booking_id`	string	The booking ID (e.g., HHB-123456)

Headers

Content-Type: application/json
api_key: YOUR_API_KEY

Example

curl https://api.hotelhero.net/v2/booking/HHB-123456/ \
-H "Content-Type: application/json" \
-H "api_key: YOUR_API_KEY"

Response

Example response

{
  "booking_id": "HHB-123456",
  "hotel": {
    "id": "f8b9c123-4567-89ab-cdef-0123456789ab",
    "name": "Anthemus Sea Beach Hotel & Spa",
    "address": "Elia Beach",
    "city": "Nikiti",
    "latitude": 40.2345,
    "longitude": 23.789,
    "country": "Greece",
    "country_iso": "GR",
    "rating": 5
  },
  "booking_period": {
    "check_in": "2025-09-20",
    "check_out": "2025-09-25",
    "nights": 5
  },
  "contact_person": {
    "first_name": "John",
    "last_name": "Smith",
    "email": "john.smith@example.com",
    "phone_number": "+306977777777"
  },
  "offer": {
    "rate_id": "ANT-DEL-20231220-5N-2A2C-BB",
    "room_type": "Deluxe Family Room Sea View",
    "boarding": "BB",
    "price": 850.0,
    "currency": "EUR",
    "cancellation_policy": {
      "cancellation_deadline": "2025-09-04T16:00:00",
      "from_dates": ["2025-09-04T16:00:00"],
      "penalty_fees": [100]
    },
    "non_refundable": false
  },
  "total_price": 850.0,
  "currency": "EUR",
  "status": "confirmed",
  "created_at": "2025-09-15T17:35:12",
  "occupancy": [
    {
      "title": "Family room",
      "adults": 2,
      "children": [5, 8],
      "boarding": "BB",
      "occupancy": [
        {
          "firstName": "John",
          "lastName": "Smith",
          "is_child": false
        },
        {
          "firstName": "Jane",
          "lastName": "Smith",
          "is_child": false
        }
      ],
      "children": [
        {
          "firstName": "David",
          "lastName": "Smith",
          "is_child": true,
          "age": 5
        },
        {
          "first_name": "Emma",
          "last_name": "Smith",
          "age": 8
        }
      ]
    }
  ],
  "remarks": "Late arrival (after 10pm). Ground floor room preferred."
}

Object Definitions

The following objects are used to define the data returned by the API.

Hotel Object

Field	Type	Description
`id`	string	Unique identifier for the hotel
`name`	string	Hotel name
`address`	string	Physical address
`description`	string	Detailed hotel description
`rating`	number	Hotel star rating
`guest_rating`	object	Customer rating information (score and count)
`city`	string	City name
`country`	string	Country name
`country_iso`	string	Country ISO code
`latitude`	number	Geographic latitude
`longitude`	number	Geographic longitude

Location Object

Field	Type	Description
`id`	string	Unique identifier for the location
`address_1`	string	Address line 1
`address_2`	string	Address line 2 (optional)
`longitude`	number	Geographic longitude
`latitude`	number	Geographic latitude
`city`	string	City name
`country`	string	Country name
`country_iso`	string	Country ISO code
`post_code`	string	Postal/ZIP code

City Object

Field	Type	Description
`id`	string	Unique identifier for the city
`name`	string	City name
`country`	string	Country name
`country_iso`	string	Country ISO code

Region Object

Field	Type	Description
`id`	string	Unique identifier for the region
`name`	string	Region name
`country`	string	Country name
`country_iso`	string	Country ISO code

Rate Object

Field	Type	Description
`rate_id`	string	Unique identifier for the rate
`room_type`	string	Description of the room type
`boarding`	string	Meal plan (e.g., "BB", "AI")
`price`	number	Total selling price
`currency`	string	Currency code (e.g., "EUR")
`cancellation_policy`	object	Details of cancellation terms
`non_refundable`	boolean	Whether the rate is non-refundable

Cancellation Policy Object

Field	Type	Description
`cancellation_deadline`	string	Last date/time for penalty-free cancellation (ISO 8601)
`from_dates`	array	List of start dates for different cancellation fee periods
`penalty_fees`	array	List of penalty percentages corresponding to from_dates

Booking Period Object

Field	Type	Description
`check_in`	string	Check-in date (YYYY-MM-DD)
`check_out`	string	Check-out date (YYYY-MM-DD)

Contact Person Object

Field	Type	Description
`first_name`	string	First name of the contact person
`last_name`	string	Last name of the contact person
`email`	string	Email address
`phone_number`	string	Phone number with country code

Guests Array

Field	Type	Description
`first_name`	string	Guest's first name
`last_name`	string	Guest's last name
`is_child`	boolean	Whether the guest is a child (true) or adult (false)
`age`	integer	Age of the guest (required only if is_child is true)

Test Hotel for Development

The Test Hotel feature allows developers to test the complete booking flow without creating real bookings or charging partner credits.

Want to test your integration without real bookings or charges? Simply search for hotel ID HH-TEST.

How it works

When you search for and book the special Test Hotel (ID: HH-TEST):

No real booking will be created in the database
No partner credit will be charged
You'll receive a standard booking response with a test booking ID (format: TEST-XXXXX)

Integration flow

The Test Hotel follows the standard booking flow - no special handling needed beyond using the test hotel ID:

Search for Test Hotel: Make a search request to /v2/availability/search/ using hotel ID HH-TEST.
Create checkout session: Select any rate from the results and create a checkout session with /v2/booking/create/.
Complete the booking: Use the standard /v2/booking/complete/ endpoint with your guest details.
Process the response: You'll receive a test booking response with an ID in the format TEST-XXXXX.

Example

Search for Test Hotel

// Step 1: Search for Test Hotel
const searchPayload = {
  hotel_id: "HH-TEST",  // Use the Test Hotel ID
  check_in: "2025-06-01",
  check_out: "2025-06-05",
  rooms: [
    {
      adults: 2,
      children: []
    }
  ]
};

// Make the search request
fetch('https://api.hotelhero.net/v2/availability/search', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'api_key': 'YOUR_API_KEY'
  },
  body: JSON.stringify(searchPayload)
})
.then(response => response.json())
.then(data => {
  // The rest of your booking flow follows the standard process
  // No special handling needed for checkout creation or booking completion
  console.log('Search ID:', data.search_id);
  console.log('Available rates:', data.results[0].rates);
});

Limitations

Test bookings are not stored in the database, so they cannot be retrieved later with GET /booking/{booking_id}/
Cancellation requests for test bookings will not work as they don't exist in the system
The booking IDs will always have the format TEST-XXXXX to make them easily identifiable as test bookings