API Documentation

Complete API reference for integrating HotelBinder into your platform

Quick Start

Base URL

https://api.hotelbinder.com/v1

Authentication

Include your API key and secret in all requests:

Headers:
  X-API-Key: your-api-key
  X-API-Secret: your-api-secret
  X-Environment: sandbox | production

API Endpoints

Search Hotels

GET /api/v1/search/hotels

Query Parameters:

  • city (required) - City name
  • checkIn (required) - Check-in date (ISO format: YYYY-MM-DD)
  • checkOut (required) - Check-out date (ISO format: YYYY-MM-DD)
  • guests (required) - Number of guests
  • rooms (optional) - Number of rooms
  • minPrice (optional) - Minimum price filter
  • maxPrice (optional) - Maximum price filter
  • starRating (optional) - Minimum star rating

Response:

{
  "hotels": [
    {
      "id": "hotel-123",
      "name": "Grand Hotel",
      "city": "Paris",
      "country": "France",
      "starRating": 4,
      "images": ["https://..."],
      "basePrice": 150.00,
      "currency": "EUR",
      "source": "OWN",
      "isExternal": false
    }
  ],
  "totalResults": 1,
  "sources": {
    "own": 1,
    "hotelBeds": 0,
    "rateHawk": 0
  }
}

Create Booking

POST /api/v1/booking/create

Request Body:

{
  "hotelId": "hotel-123",  // Required: Hotel ID from search results
  "checkIn": "2026-03-15",  // Required: ISO date format
  "checkOut": "2026-03-17",  // Required: ISO date format
  "guests": 2,  // Required: Number of guests
  "rooms": 1,  // Optional: Number of rooms
  "guestName": "John Doe",  // Required: Guest name
  "guestEmail": "john@example.com",  // Required: Guest email
  "guestPhone": "+1234567890",  // Optional: Guest phone
  "totalAmount": 200.00,  // Required: Total booking amount
  "currency": "EUR",  // Required: Currency code
  "source": "OWN",  // Required: OWN, HOTELBEDS, or RATEHAWK
  "externalHotelId": "ext-456",  // Optional: For external hotels
  "rateKey": "rate-key-123",  // Optional: Rate key for external bookings
  "partnerReference": "PARTNER-REF-123",  // Optional: Your booking reference
  "specialRequests": "Late check-in requested"  // Optional: Special requests
}

Get Booking

GET /api/v1/booking/{id}

Response:

{
  "id": "booking-123",
  "hotelId": "hotel-123",
  "hotelName": "Grand Hotel",
  "checkIn": "2026-03-15T00:00:00.000Z",
  "checkOut": "2026-03-17T00:00:00.000Z",
  "guests": 2,
  "rooms": 1,
  "guestName": "John Doe",
  "guestEmail": "john@example.com",
  "status": "CONFIRMED",
  "totalAmount": 200.00,
  "currency": "EUR",
  "confirmationNumber": "HB-ABC123",
  "createdAt": "2026-02-15T10:00:00.000Z",
  "source": "OWN",
  "partnerReference": "PARTNER-REF-123",
  "revenue": {
    "commission": 20.00,
    "margin": 20.00,
    "netRevenue": 40.00
  }
}

Cancel Booking

POST /api/v1/booking/{id}/cancel

Cancels a booking by ID. Returns the updated booking with status "CANCELLED".

Code Examples

JavaScript/TypeScript

const response = await fetch(
  'https://api.hotelbinder.com/v1/search/hotels?city=Paris&checkIn=2026-03-15&checkOut=2026-03-17&guests=2',
  {
    headers: {
      'X-API-Key': 'your-api-key',
      'X-API-Secret': 'your-api-secret',
      'X-Environment': 'sandbox'
    }
  }
);
const data = await response.json();

cURL

curl -X GET \
  "https://api.hotelbinder.com/v1/search/hotels?city=Paris&checkIn=2026-03-15&checkOut=2026-03-17&guests=2" \
  -H "X-API-Key: your-api-key" \
  -H "X-API-Secret: your-api-secret" \
  -H "X-Environment: sandbox"

Need Help?

For API support, integration help, or questions, contact us at info@visit-online.nl