tobook LLM API Documentation

Notes on endpoints, schemas, supported fields and model considerations are provided below, don't hesitate to message our backend team for questions or bugs, if you need help with the swift resolution of any implementation issues, or have any further questions.

Unicode values are supported in all string values, and all API requests and responses are UTF-8 encoded.

1. Get Countries

Endpoint

Endpoint: GET /countries

Purpose: Retrieve a list of all available countries. Ideal starting point for agents.

Parameters

Parameter	Type	Required	Default	Description
langId	int	No	1	Language ID for country names

Example Request

GET /countries?langId=1

Sample Messages

Example Response

{
          "status": "success",
          "langId": 1,
          "count": 245,
          "countries": [
            {
              "countryId": 190,
              "iSOCode": "CH",
              "internetCode": "CH",
              "country": "Switzerland"
            },
            {
              "countryId": 200,
              "iSOCode": "DE",
              "internetCode": "DE",
              "country": "Germany"
            }
          ]
        }

Usage Note for Agents: Use the returned countryId for subsequent calls to /findLocation or /hotels.

---

Endpoint

2. Get Locations by Country

Endpoint: GET /locations

Purpose: Get all available locations (cities, regions, etc.) within a specific country.

Parameters

Parameter	Type	Required	Default	Description
countryId	int	Yes	-	Country ID (from /countries endpoint)
langId	int	No	1	Language ID

Sample Messages

Example Request

GET /locations?countryId=200&langId=1

Example Response

{
          "status": "success",
          "langId": 1,
          "count": 42,
          "locations": [
            {
              "searchLocationID": 12345,
              "locationName": "Amsterdam",
              "locationNameEnglish": "Amsterdam",
              "lat": 52.3676,
              "lng": 4.9041
            },
            {
              "searchLocationID": 67890,
              "locationName": "Rotterdam",
              "locationNameEnglish": "Rotterdam",
              "lat": 51.9225,
              "lng": 4.47917
            }
          ]
        }

Note: The searchLocationId can be used in subsequent calls to search for hotels in that location.

---

Endpoint

Find Location by Name Fragment

Endpoint: GET /findLocation

Purpose: Search for locations (cities, regions, etc.) using a partial name. Very useful for agents to find matching places quickly.

Parameters

Parameter	Type	Required	Default	Description
fragment	string	Yes	-	Partial name of the location (e.g. "amster", "paris", "saas")
langId	int	No	1	Language ID

Example Request

GET /findLocation?fragment=amster&langId=1

Example Response

{
          "status": "success",
          "fragment": "saa",
          "langId": 1,
          "count": 1,
          "locations": [
            {
              "searchLocationId": null,
              "name": "Saas Fee - Switzerland",
              "location": "Saas Fee",
              "country": "Switzerland",
              "countryId": 190
            }
          ]
        }

Usage Tip for Agents: Use the returned searchLocationId in the next step to search for hotels in that specific location.

---

Endpoint

Get Hotels by Search Location

Endpoint: GET /hotels

Purpose: Search for hotels in a specific location with availability and pricing for given dates.

Parameters

Parameter	Type	Required	Default	Description
searchLocationId	int	Yes	-	ID from /findLocation endpoint
arr	string	Yes	-	Arrival date (YYYY/MM/DD)
dep	string	Yes	-	Departure date (YYYY/MM/DD)
numAdults	int	Yes	-	Number of adults
numChildren	int	No	0	Number of children
SearchAllStars	int	Yes	0	Set to 1 to ignore star rating filter, 0 to apply star filters below
Show0Stars	int	No	0	Include 0-star properties (1 = yes, 0 = no)
Show1Stars	int	No	0	Include 1-star properties
Show2Stars	string	No	0	Include 2-star properties
Show3Stars	string	No	0	Include 3-star properties
Show4Stars	int	No	0	Include 4-star properties
Show5Stars	int	No	0	Include 5-star properties
langId	int	No	1	Language ID

Important Note for Agents

When SearchAllStars = 0, at least one of the ShowXStars parameters must be set to 1. Otherwise the system may return no results.

Example Request

GET hotels?searchLocationId=1505&arr=2026/7/19&dep=2026/7/22&numAdults=2&numChildren=0&SearchAllStars=1&Show0Stars=0&Show1Stars=0&Show2Stars=0&Show3Stars=0&Show4Stars=0&Show5Stars=0&langId=1

Example Response

{
          "status": "success",
          "count": 12,
          "hotel_structure": [
            {
              "hotelId": 9533,
              "hotelName": "Hotel Example",
              "address": "Main Street 123",
              "locationName": "Amsterdam",
              "telephone": "+31201234567",
              "classification": 4,
              "distanceToCenter_km": "1.25 km",
              "roomTypeName": "Standard Double",
              "priceInclusive": 245.50,
              "priceInclusiveEuros": 245.50
            }
          ],
          "meta": {
            "totalOffers": 12,
            "timestamp": "2026-07-12T10:00:00Z",
            "langId": 1,
            "searchLocationId": 1505,
            "currencyID": 1
          }
        }

Note for Agents: Use the hotelId from the results to call the /offers endpoint for detailed rates and availability.

---

Endpoint

Get Detailed Hotel Information

Endpoint: GET /hotel

Purpose: Get rich details for a specific hotel including offers, facilities, policies, photos, and reviews.

Parameters

Parameter	Type	Required	Default	Description
hotelId	int	Yes	-	Hotel ID
arr	string	Yes	-	Arrival date (YYYY/MM/DD)
dep	string	Yes	-	Departure date (YYYY/MM/DD)
numAdults	int	Yes	-	Number of adults
numChildren	int	No	0	Number of children
langId	int	No	1	Language ID

Example Request

GET /hotel?hotelId=100093&arr=2026/07/19&dep=2026/07/22&numAdults=2&numChildren=0&langId=1

Example Response

    {
    "status": "success",
    "count": 1,
    "hotel_structure": [
    {
    "hotelId": 100093,
    "hotelName": "Example Hotel",
    "address": "Example Street 123",
    "locationName": "Amsterdam",
    "country": "Netherlands",
    "public_URL": ""https://www.tobook.com/Ital/Hotels/Example-Hotell?CityPName=Poro&arr=2026/7/19&dep=2026/7/2",
    "telephone": "+39201234567",
    "classification": 4,
    "distanceToCenter_km": "1.85 km",
    "description": "Beautiful hotel in the city center...",
    "offers": [ /* array of offers */ ],
    "facilities": [ /* grouped facilities */ ],
    "hotelPolicies": [ /* grouped policies */ ],
    "hotelRoomTypes": [ /* room types */ ],
    "hotelCancelationPolicies": [ /* cancellation rules */ ],
    "Photos": [ /* photo list */ ],
    "Reviews": [ /* guest reviews */ ]
    }
    ],
    "meta": {
    "totalHotel": 1,
    "timestamp": "2026-07-12T11:00:00Z",
    "langId": 1,
    "currencyID": 1
    }
    }

Note for Agents: This endpoint returns rich structured data suitable for final decision making before booking.

---

Offers Endpoint

Get Hotel Offers / Availability

Endpoint: GET /offers

Purpose: Get real-time room rates, availability, and pricing for a specific hotel and dates.

Parameters

Parameter	Type	Required	Default	Description
hotelId	int	Yes	-	Hotel ID
arr	string	Yes	-	Arrival date (YYYY/MM/DD or MM/DD/YYYY)
dep	string	Yes	-	Departure date (YYYY/MM/DD or MM/DD/YYYY)
numAdults	int	Yes	-	Number of adults
numChildren	int	No	0	Number of children
langId	int	No	1	Language ID

Sample Messages

Example Request

GET /offers?hotelId=100&arr=07/07/2026&dep=07/08/2026&numAdults=2&numChildren=0&langId=1

Example Response

{
          "status": "success",
          "hotelId": 200,
          "checkIn": "07/07/2026",
          "checkOut": "07/08/2026",
          "currency": {
            "id": 1,
            "code": "USD",
            "symbol": "$",
            "name": "US Dollar"
          },
          "numAdults": 2,
          "numChildren": 0,
          "hotel": {
            "name": "Example Hotel",
            "Classification": 4,
            "city": "Amsterdam",
            "country": "Netherlands"
          },
          "cancellationPolicies": [ /* array of policies */ ],
          "offers": [
            {
              "offerTypeId": 123,
              "roomType": {
                "id": 456,
                "name": "Standard Double Room",
                "maxPersons": 2,
                "personsNormal": 2
              },
              "ratePlan": {
                "name": "Bed & Breakfast",
                "paymentScheme": "BB"
              },
              "price": {
                "total": 245.50,
                "totalExclusive": 200.00,
                "currency": "USD",
                "breakdown": {
                  "base": 200.00,
                  "inclusive": 245.50
                }
              },
              "availability": {
                "available": true,
                "roomsLeft": 5
              }
            }
          ],
          "meta": {
            "totalOffers": 8,
            "timestamp": "2026-07-12T11:30:00Z",
            "langId": 1
          }
        }

Note for Agents: Use one of the offerTypeId values when calling the /bookings endpoint.

---

Endpoint

Create Booking

Endpoint: POST /bookings

Purpose: Create a hotel booking using a selected offer. No Credit card details are provided.

Important Information about Bookings

This endpoint creates a booking inquiry, not a confirmed reservation.

The inquiry is non-binding and will automatically expire if the necessary credit-card details are not provided within 12 hours after the creation of the inquiry.

An email will be sent to the provided guest email address containing the inquiry details and a secure link. The guest can use this link to provide the necessary credit card details and convert the inquiry into a confirmed reservation. Provided that the rooms are still available.

If the rooms are still available and a valid credit card is provided, the inquiry becomes a confirmed reservation.

Parameters (JSON Body)

Parameter	Type	Required	Default	Description
hotelId	string	Yes	-	Hotel ID
firstName	string	Yes	-	Guest first name
lastName	string	Yes	-	Guest last name
email	string	Yes	-	Guest email address
startDate	datetime	Yes	-	Arrival date (ISO format)
endDate	datetime	Yes	-	Departure date (ISO format)
roomTypeID	string	Yes	-	Room type ID from offers
offerTypeID	string	Yes	-	Offer type ID from offers

Example Request (cURL)

curl -X POST https://llm.tobook.com/bookings \
            -H "Content-Type: application/json" \
            -d '{
            "hotelId": "200",
            "firstName": "alfa",
            "lastName": "bbbb",
            "email": "xx@cc.yyy",
            "mobile": "+11233",
            "startDate": "2026-08-01T00:00:00",
            "endDate": "2026-08-02T00:00:00",
            "roomTypeID": "1",
            "offerTypeID": "1"
            }'

Example Success Response

        {
        "status": "success",
        "bookingId": "27-200",
        "message": "Booking created successfully",
        "returnValue": 27,
        "rawResponse": { {"ExplicitCodeSet":false,"ErrorCode":0,"ErrorMessage":"","ReturnValue":27}}
        }
        

Note for Agents: This is the final step in the booking flow. The system returns a bookingId on success.

Endpoint

Feedback / Suggestions

Endpoint: POST /feedback

Purpose: Allow agents and developers to report bugs, suggest improvements, or give feedback directly..

Parameters (JSON Body)

Parameter	Type	Required	Max Length	Description
feedback_type	string	Yes	20	bug, suggestion, or improvement
endpoint	string	No	100	Affected endpoint (e.g. /offers)
description	string	Yes	250	Description of the issue or suggestion
suggested_fix	string	No	250	Optional suggested solution
agent_id	string	No	100	Identifier of the agent (optional)
session_id	string	No	100	Session identifier (optional)

Example Request

            {
            "feedback_type": "bug",
            "endpoint": "/offers",
            "description": "Price field is missing when offer is sold out",
            "suggested_fix": "Always return price with availability status",
            "agent_id": "agent-claude-3"
            }'
        

Example Success Response

            {
            "status": "success",
            "message": "Feedback received. Thank you!",
            "timestamp": "2026-07-16T12:00:00Z"
            }