BookApp API

A Hermeseus-compatible hotel API. Search availability, get per-hotel room pricing, all normalized to USD. Authentication and the /Hotel/HotelAvailability contract mirror the Hermeseus shape so existing integrations map over with minimal changes.

Visual demo: /try Admin panel: /admin API Playground: /playground

Overview

Every call is POST with a JSON body (except the GET helpers). The flow is:

1. An admin creates an API user (UserName, Password, OfficeId) in /admin.
2. The client calls CreateSession and receives a SessionId.
3. The SessionId is sent in the body of every HotelAvailability call (15-minute sliding expiry — each successful call renews it).

Base URL & format

Business rules (applied to every result)

CreateSession

Establishes a session. Credentials are the API user created in the admin panel.

Request body

Response

{
  "Success": true,
  "SessionId": "7ce01b22-df26-465f-b143-a532ed985a03",
  "Error": null
}

EndSession

Request body

Response

{ "Success": true, "Error": null }

HotelAvailability

One endpoint, two modes, selected by which id you send:

• City search — send CityId (leave HotelId null) → a list of hotels.
• Hotel details — send HotelId (leave CityId null) → one hotel with full room pricing.

Request body

Mode A — City search

Returns PricedItineraries (hotels), cheapest first. Rooms is empty here; call by HotelId for the room breakdown.

// Request
{
  "SessionId": "7ce0…985a03",
  "CheckIn": "2026-09-10",
  "CheckOut": "2026-09-12",
  "CityId": -2140479,
  "CountryCode": "NL",
  "NationalityId": "NL",
  "Occupancies": [ { "AdultCount": 2, "ChildCount": 0, "ChildAges": [] } ],
  "Deep": false
}

// Response (truncated)
{
  "Success": true,
  "PricedItineraries": [
    {
      "FareSourceCode": "NjMzMTg2MnwyMDI2LTA5LTEwfDIwMjYtMDktMTI=",
      "HotelId": 5901512,
      "HotelName": "Dutchies Hostel",
      "NetRate": 182.06,
      "Currency": "USD",
      "NonRefundable": true,
      "Hotel": {
        "name": "Dutchies Hostel",
        "rating": 0,
        "reviewScore": 8.9,
        "location": { "latitude": 52.37, "longitude": 4.90 },
        "images": [ "https://bookapp.pro.plus/live_images/xdata/images/hotel/square60/58458024.jpg?k=…&o=" ]
      },
      "Rooms": [],
      "CancellationPolicies": []
    }
  ],
  "Meta": { "CityId": -2140479, "TotalOnBooking": 266, "Returned": 257, "Deep": false, "Plan": null },
  "Error": null
}

Mode B — Hotel details

Returns a single PricedItinerary with the full, prepaid Rooms list.

// Request
{
  "SessionId": "7ce0…985a03",
  "CheckIn": "2026-09-10",
  "CheckOut": "2026-09-12",
  "CityId": null,
  "HotelId": 6331862,
  "Occupancies": [ { "AdultCount": 2 } ]
}

// Response (truncated)
{
  "Success": true,
  "PricedItineraries": [
    {
      "FareSourceCode": "NjMzMTg2MnwyMDI2LTA5LTEwfDIwMjYtMDktMTI=",
      "HotelId": 6331862,
      "HotelName": "Holiday Inn Express Amsterdam - North Riverside",
      "NetRate": 775.62,
      "Currency": "USD",
      "NonRefundable": false,
      "Hotel": {
        "name": "…", "address": "…", "city": "Amsterdam",
        "rating": 3, "reviewScore": 8.2,
        "location": { "latitude": 52.38, "longitude": 4.91 },
        "images": [ "https://bookapp.pro.plus/images/xdata/images/hotel/max500/337421613.jpg" ]
      },
      "Rooms": [
        {
          "RoomId": "633186210_247251398_2_41_0",
          "RoomName": "Standard Twin Room …",
          "RoomType": "Buffet breakfast is included in the room rate.",
          "Price": 775.62,
          "Currency": "USD",
          "Occupancy": 2,
          "Amenities": [ "Free WiFi", "Air conditioning", "…" ],
          "Beds": [ "2 single beds" ],
          "Images": [ "https://bookapp.pro.plus/live_images/xdata/images/room/…jpg?k=…&o=" ],
          "RoomsLeft": 6,
          "NonRefundable": false,
          "Prepayment": "full_prepayment"
        }
      ],
      "CancellationPolicies": [ { "FromDate": "2026-09-08 …", "Penalty": 0 } ]
    }
  ],
  "Error": null
}

PricedItinerary fields

cities/search

Find cities by name. Public (no session). Returns an internal id (use it as HotelAvailability CityId) and the provider-side external_id.

Query parameters

{
  "data": [
    { "id": 12, "external_id": -755070, "name": "Istanbul",
      "destination": "Istanbul, Turkey", "country": { "code": "TR", "name": "Turkey" } }
  ],
  "meta": { "query": "istanbul", "count": 1, "limit": 50, "provider": "example-provider-1" }
}

cities/lookup

Bulk-resolve cities by their provider-side external_id (up to 500).

// Request
{ "external_ids": [-755070, -2140479], "provider": "example-provider-1" }

// Response
{ "data": [ { "id": 12, "external_id": -755070, "name": "Istanbul", … } ],
  "meta": { "count": 1, "requested": 2, "provider": "example-provider-1" } }

Not implemented (by design)

/Hotel/HotelBook, /Hotel/HotelOrder, /Hotel/HotelCancel and /Hotel/HotelBookingData are intentionally absent — this service covers search & availability only.

Languages

Send a 2-letter lang in the request body to translate hotel and room content (names, room types, meal plans, addresses, review words, …). Prices are always returned in USD, independent of language. If lang is omitted, null, or not in the list below, the response falls back to en (echoed back in Meta.Language).

Supported codes:

arbgcacs dadeelen esetfifr hehrhuid isitjako ltlvmsnl noplptro ruskslsr svthtruk vizh

// same search, German content — prices still USD
{ "SessionId":"", "CheckIn":"2026-09-10", "CheckOut":"2026-09-12",
  "HotelId":6331862, "lang":"de", "Occupancies":[{"AdultCount":2}] }
// → Rooms[0].RoomName: "Standard-Zweibettzimmer …", Currency: "USD"

Image URLs

All image URLs point to bookapp.pro.plus and are cached on our side:

Both return the raw image bytes with long-lived cache headers. Just use whichever URL the API returns.

Errors

On failure, Success is false and Error is populated:

{ "Success": false, "SessionId": null,
  "Error": { "Id": "Err0101003", "Message": "Invalid credentials or inactive account." } }

Quick start (curl)

# 1) Create a session
curl -s https://bookapp.pro.plus/Authenticate/CreateSession \
  -H 'Content-Type: application/json' \
  -d '{"OfficeId":"OFFICE001","UserName":"demo","Password":"demo12345"}'

# 2) City search (cheapest-first, prepaid, 7+)
curl -s https://bookapp.pro.plus/Hotel/HotelAvailability \
  -H 'Content-Type: application/json' \
  -d '{"SessionId":"","CheckIn":"2026-09-10","CheckOut":"2026-09-12",
       "CityId":-2140479,"Occupancies":[{"AdultCount":2}]}'

# 3) Hotel details (rooms + prices)
curl -s https://bookapp.pro.plus/Hotel/HotelAvailability \
  -H 'Content-Type: application/json' \
  -d '{"SessionId":"","CheckIn":"2026-09-10","CheckOut":"2026-09-12",
       "CityId":null,"HotelId":6331862,"Occupancies":[{"AdultCount":2}]}'