hotelhuddle API Documentation

Base URL: https://api.hotelhuddle.com/api/v1

Authentication: Bearer token in the Authorization header. Generate keys in your Portal > API Keys. API access requires accepting the API Access Terms.

Required LLM Headers: Every request must identify the calling LLM and the end-user's network context:

• X-LLM-Identifier — Your product name or model identifier (e.g. openai-gpt-4o, claude-code).
• X-LLM-Client-IP — The public IP address of the end-user whose behalf you are acting.
• X-LLM-Client-Location (optional) — Free-form location hint for the end-user, e.g. US-TX or Austin, TX.

Supported Platforms

One API key works across the hotelhuddle family of brands. The platform you target is chosen with the brand parameter:

• grouprooms — Group room blocks
• hotelhaggle — Name Your Price
• hotelslots — Day-use rooms
• bookmyteam — Team / multi-destination travel
• bookmymeeting — Meeting rooms

Endpoints Overview

Method	Path	Description
GET	/api/v1/cities?q={city}	Search cities; returns canonical city ID and metadata.
POST	/api/v1/rfp/submit	Submit a group hotel RFP for any platform.
GET	/api/v1/rfps	List RFPs submitted with this API key.
GET	/api/v1/rfp/{id}	Check RFP status, matched hotels, and responses.
POST	/api/v1/rfp/{id}/choose	Select a winning hotel offer.

1. Search Cities

Resolve free-form city text into a canonical city record before submitting an RFP.

GET /api/v1/cities?q=Chattanooga
Authorization: Bearer {api_key}
X-LLM-Identifier: openai-gpt-4o
X-LLM-Client-IP: 203.0.113.45
X-LLM-Client-Location: US-TN

Response:

{
  "success": true,
  "data": [
    {
      "id": "Chattanooga-tn-us",
      "city": "Chattanooga",
      "state": "TN",
      "country": "US",
      "lat": "35.0456300",
      "lng": "-85.3096800"
    }
  ]
}

2. Submit an RFP

Submit a request on behalf of the API key owner. Customer contact details are taken from the account; do not send them in the request body.

POST /api/v1/rfp/submit
Authorization: Bearer {api_key}
X-LLM-Identifier: openai-gpt-4o
X-LLM-Client-IP: 203.0.113.45
Content-Type: application/json

{
  "brand": "grouprooms",
  "city_id": "Chattanooga-tn-us",
  "check_in": "2026-09-15",
  "check_out": "2026-09-17",
  "king_rooms": 10,
  "double_rooms": 5,
  "group_name": "Q3 Sales Kickoff",
  "terms_agree": true
}

Response:

{
  "success": true,
  "data": {
    "itinerary_number": null,
    "brand": "grouprooms",
    "rfps": [
      {
        "id": 2917521,
        "city": "Chattanooga",
        "status": "submitted"
      }
    ]
  }
}

3. Check Status

GET /api/v1/rfp/2917521
Authorization: Bearer {api_key}
X-LLM-Identifier: openai-gpt-4o
X-LLM-Client-IP: 203.0.113.45

Response:

{
  "success": true,
  "data": {
    "id": 2917521,
    "status": "submitted",
    "brand": "group",
    "city": "Chattanooga",
    "check_in": "2026-09-15",
    "check_out": "2026-09-17",
    "matched_hotels": 0,
    "responses": [],
    "itinerary_number": null,
    "stops": []
  }
}

4. Choose a Winner

POST /api/v1/rfp/2917521/choose
Authorization: Bearer {api_key}
X-LLM-Identifier: openai-gpt-4o
X-LLM-Client-IP: 203.0.113.45
Content-Type: application/json

{
  "hotel_id": "h_12345",
  "note": "Confirmed with traveler."
}

Response:

{
  "success": true,
  "data": {
    "rfp_id": 2917521,
    "hotel_id": "h_12345",
    "status": "accepted"
  }
}

5. Multi-Destination (bookmyteam)

For team travel with multiple stops, include a destinations array. The primary stop is defined by the top-level fields; each additional stop in destinations requires its own city_id, dates, and room counts.

{
  "brand": "bookmyteam",
  "city_id": "Chattanooga-tn-us",
  "check_in": "2026-09-15",
  "check_out": "2026-09-17",
  "king_rooms": 10,
  "double_rooms": 5,
  "terms_agree": true,
  "destinations": [
    {
      "city_id": "Atlanta-ga-us",
      "check_in": "2026-09-18",
      "check_out": "2026-09-20",
      "king_rooms": 8,
      "double_rooms": 4
    },
    {
      "city_id": "Nashville-tn-us",
      "check_in": "2026-09-21",
      "check_out": "2026-09-23",
      "king_rooms": 6,
      "double_rooms": 3
    }
  ]
}

6. Platform-Specific Fields

• hotelhaggle: include target_rate_per_night (USD, e.g. 199.99).
• hotelslots: include time_window (one of: morning, afternoon, evening, full_day, midday, extended_day, afternoon_evening, overnight_adjacent).
• bookmymeeting: include room_preference if desired.

Errors

All errors follow this shape:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR | UNAUTHORIZED | FORBIDDEN | RATE_LIMIT | INTERNAL_ERROR",
    "message": "Human-readable description."
  }
}

HTTP 429 is returned when you exceed the per-key rate limit (30 city searches/minute, 60 other requests/minute by default).

AI-Submitted Identifier

Every RFP created through this API is tagged with ai_submitted=1, source_domain=api.hotelhuddle.com, and the originating api_key_id. You can identify them in your dashboard and in the list endpoint via the ai flag.