Hermeseus API

Create a new API session. No authentication required.

Request

copy{
  "OfficeId": "OFFICE_NAME_OR_ID",
  "UserName": "your_username",
  "Password": "A1B2C3...HASHED_SHA512_UPPERCASE"
}

Response — 200 OK

copy{
  "Success": true,
  "SessionId": "7f3c81d2-0e8d-4f9a-9c12-4d5e2b9a8f01",
  "Error": null
}

Response — Error

copy{
  "Success": false,
  "SessionId": null,
  "Error": {
    "Id": "Err0101003",
    "Message": "Invalid credentials. Username or password is incorrect."
  }
}

Terminate the current session immediately. After this call the SessionId is invalid.

Request

copy{ "SessionId": "7f3c81d2-0e8d-4f9a-9c12-4d5e2b9a8f01" }

Response

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

Search for the cheapest itinerary per unique flight group across the selected provider. The response is capped at 500 itineraries with category diversity (cheapest, fastest, direct, baggage tiers, morning departures, evening arrivals).

Request

copy{
  "SessionId": "7f3c81d2-...",
  "Provider": "example-provider-1",   // optional; gateway picks the right source by default
  "AdultCount": 1,
  "ChildCount": 0,
  "InfantCount": 0,
  "PricingSourceType": "All",
  "RequestOption": "All",
  "NumberOfResults": 100,  // optional; omit / 0 / 100 = default 100. Any other value scales the same mix (50→50, 1000→1000). Max 5000.
  "TravelPreference": {
    "CabinType": 1,          // integer enum: 1=Economy, 2=Premium Economy, 3=Business, 4=Premium Business, 5=First, 6=Premium First
    "MaxStopsQuantity": "All",
    "AirTripType": "OneWay",
    "DirectFlight": false
  },
  "OriginDestinationInformations": [
    {
      "OriginLocationCode": "IST",
      "DestinationLocationCode": "DXB",
      "DepartureDateTime": "2026-06-12T00:00:00"
    }
  ]
}

Response — 200 OK (truncated)

copy{
  "Success": true,
  "SearchId": 428713,
  "PricedItineraries": [
    {
      "FareSourceCode": "dHA6ODc0NTE6ZmwxMjM0OjMyNw==",
      "ValidatingAirlineCode": "TK",
      "DirectionInd": 1,
      "IsPassportMandatory": true,
      "AirItineraryPricingInfo": {
        "FareType": 1,
        "ItinTotalFare": {
          "BaseFare": 182.40,
          "TotalTax": 37.20,
          "TotalFare": 219.60,
          "Currency": "USD"
        },
        "PtcFareBreakdown": [ /* per-pax breakdown */ ]
      },
      "OriginDestinationOptions": [
        {
          "JourneyDurationPerMinute": 270,
          "FlightSegments": [
            {
              "DepartureAirportLocationCode": "IST",
              "ArrivalAirportLocationCode": "DXB",
              "DepartureDateTime": "2026-06-12T08:25:00",
              "ArrivalDateTime": "2026-06-12T14:55:00",
              "MarketingAirlineCode": "TK",
              "FlightNumber": "764",
              "ResBookDesigCode": "Y",
              "Baggage": "1PC",
              "CabinClassCode": 1,
              "SeatsRemaining": 9
            }
          ]
        }
      ]
    }
  ],
  "Error": null
}

Streaming twin of AirLowFareSearch. Same request body, but the response is a Server-Sent Events stream (Content-Type: text/event-stream): itineraries are pushed in batches as the provider's incremental search returns them, instead of waiting for the whole search to finish. Use it for a fast first paint and progressively-filling results.

Each streamed itinerary is identical in shape to an AirLowFareSearch entry and is cached for later AirRevalidate/AirBook exactly the same way. De-duplication is by FareSourceCode across the stream. Unlike the blocking endpoint, results are not collapsed to cheapest-per-flight-group and the 500-item diversity cap is not applied (those are whole-result-set operations) — every proposal is emitted as it arrives.

Request

Identical to AirLowFareSearch.

Response — text/event-stream

copyevent: itineraries
data: {"PricedItineraries":[ { /* same shape as AirLowFareSearch[*] */ }, ... ]}

event: itineraries
data: {"PricedItineraries":[ ... more as they arrive ... ]}

event: done
data: {"Success":true,"SearchId":428713,"Total":137}

Event types:

copycurl -N -X POST https://demo.hermeseus.com/api/Air/AirLowFareSearchIncremental \
  -H "Content-Type: application/json" \
  -d '{"SessionId":"...","OriginDestinationInformations":[{"OriginLocationCode":"IST","DestinationLocationCode":"DXB","DepartureDateTime":"2026-06-12T00:00:00"}],"AdultCount":1,"TravelPreference":{"CabinType":1},"RequestOption":"Fifty"}'

The cheapest fare for each day on a route — a price calendar. Give an origin, a destination and the trip type (OneWay / RoundTrip); you get one entry per available date. This endpoint is provider-agnostic: there is no Provider field and the data always comes from the same aggregated fare source. All prices are in USD by default.

Request

copy{
  "SessionId": "...",
  "Origin": "DXB",
  "Destination": "IST",
  "TripType": "RoundTrip",
  "DepartDate": "2026-11",
  "ReturnDate": "2026-12",
  "CalendarType": "departure_date",
  "Currency": "USD"
}

Response

copy{
  "Success": true,
  "Origin": "DXB", "Destination": "IST", "TripType": "RoundTrip",
  "CalendarType": "departure_date", "Currency": "USD",
  "DaysCount": 50, "MinPrice": 370, "MaxPrice": 608,
  "Cheapest": { "Date": "2026-11-27", "Price": 370, ... },
  "Days": [
    {
      "Date": "2026-11-01", "Price": 412, "Currency": "USD",
      "Transfers": 1, "Airline": "PS", "FlightNumber": 576,
      "DepartureAt": "2026-11-01T06:35:00+03:00", "ReturnAt": "2026-12-01T13:30:00+02:00",
      "ExpiresAt": "2026-08-10T12:34:14Z", "Origin": "DXB", "Destination": "IST"
    }, ...
  ],
  "Error": null
}

Re-check price and availability for a specific itinerary before calling AirBook. Required: the booking flow rejects book attempts that have not been revalidated within the current session.

Request

copy{
  "SessionId": "7f3c81d2-...",
  "FareSourceCode": "dHA6ODc0NTE6ZmwxMjM0OjMyNw=="
}

Response

copy{
  "Success": true,
  "PricedItinerary": { /* same shape as in AirLowFareSearch[*] */ },
  "PriceChange": false,
  "Error": null
}

Fare rules (penalties, changes, refundability) for an itinerary. Accepts either FareSourceCode (pre-booking) or UniqueId (post-booking).

Request

copy{ "SessionId": "...", "FareSourceCode": "..." }

Reserves the previously revalidated itinerary. Funds equal to TotalFare are held on your office wallet. The reservation auto-cancels after 10 minutes if the ticket is not issued via AirOrderTicket.

Request

copy{
  "SessionId": "7f3c81d2-...",
  "FareSourceCode": "dHA6ODc0NTE6ZmwxMjM0OjMyNw==",
  "ClientUniqueId": "order_29013",
  "TravelerInfo": {
    "PhoneNumber": "+971501234567",
    "Email": "customer@example.com",
    "AirTravelers": [
      {
        "PassengerType": "Adt",
        "Gender": 0,            // 0=Male 1=Female
        "DateOfBirth": "1992-04-18",
        "Nationality": "AE",
        "PassengerName": {
          "PassengerTitle": "Mr",
          "PassengerFirstName": "John",
          "PassengerLastName": "Smith"
        },
        "Passport": {
          "PassportNumber": "A12345678",
          "ExpiryDate": "2030-12-01",
          "IssueDate": "2020-12-01",
          "Country": "AE"
        }
      }
    ]
  }
}

Response — Reserved

copy{
  "Success": true,
  "UniqueId": "4d2e91c8-3b71-4a55-8e9c-5f1a2d3b6c80",
  "TktTimeLimit": "2026-05-20T10:23:01+00:00",
  "TktTimeLimitTimeZone": "UTC",
  "Category": 10,
  "Status": 10,
  "PriceChange": false,
  "WarningMessage": null,
  "Error": null
}

Response — Insufficient balance

copy{ "Success": true, "Category": 40, "Status": 41, "WarningMessage": "Insufficient balance.", "Error": null }

Transitions the booking from 10/10 to 20/20 (TicketInProcess), queuing it for ticket issuance.

Request

copy{ "SessionId": "...", "UniqueId": "4d2e91c8-..." }

Response

copy{ "Success": true, "Category": 20, "Status": 20, "Error": null }

Cancel a booking that has not been ticketed yet. Released funds are returned to the office's available balance immediately. Ticketed bookings (status 21) require AirRefund instead.

Request

copy{ "SessionId": "...", "UniqueId": "4d2e91c8-..." }

Returns the list of e-tickets eligible for refund and any per-ticket penalty.

Issues a refund. Booking moves to 21/25 (TicketCancelled). The refunded amount is credited back to the office wallet via a charge transaction.

Request

copy{
  "SessionId": "...",
  "UniqueId": "4d2e91c8-...",
  "RefundType": 1,
  "EticketNumbers": ["235-2148764520"]
}

Full reservation record: travelers, e-tickets, segments, fare breakdown, booking notes, and audit timestamps. Lookup by either internal UniqueId or your ClientUniqueId.

Each segment in TravelItinerary.ItineraryInfo.ReservationItems additionally carries three fields: DepartureAirportTerminal and ArrivalAirportTerminal (plain strings) and AirlineRules (an HTML string of the fare/airline conditions). They are empty until populated for the booking and may be blank for segments left unfilled.

Request

copy{ "SessionId": "...", "UniqueId": "4d2e91c8-..." }

Array of countries. code is the 2-letter ISO country code used by city/airport records; currency is the country's ISO-4217 currency; name_translations holds localized names.

copy[
  {
    "code": "GM",
    "name": "Gambia",
    "currency": "GMD",
    "name_translations": { "en": "Gambia" },
    "cases": { "su": "Gambia" }
  }
]

Array of cities. code is the 3-letter IATA city code (matches OriginLocationCode/DestinationLocationCode in search), country_code links to countries, coordinates gives lat/lon, and has_flightable_airport indicates the city is reachable by air.

copy[
  {
    "code": "FSZ",
    "name": "Shizuoka",
    "country_code": "JP",
    "time_zone": "Asia/Tokyo",
    "coordinates": { "lat": 34.796112, "lon": 138.18944 },
    "has_flightable_airport": true,
    "name_translations": { "en": "Shizuoka" },
    "cases": { "su": "Shizuoka" }
  }
]

Array of airports. code is the 3-letter IATA airport code (matches segment DepartureAirportLocationCode/ArrivalAirportLocationCode), city_code links to cities, iata_type is the entity type (e.g. airport), and flightable indicates bookable flights operate there.

copy[
  {
    "code": "BLK",
    "name": "Blackpool Airport",
    "city_code": "BLK",
    "country_code": "GB",
    "iata_type": "airport",
    "time_zone": "Europe/London",
    "coordinates": { "lat": 53.778385, "lon": -3.041985 },
    "flightable": true,
    "name_translations": { "en": "Blackpool Airport" }
  }
]

Array of airlines. code is the 2-character IATA airline code (matches ValidatingAirlineCode and segment MarketingAirlineCode/OperatingAirline.Code), name is the carrier name, and is_lowcost flags low-cost carriers.

copy[
  {
    "code": "ZM",
    "name": "Air Manas",
    "is_lowcost": true,
    "name_translations": { "en": "Air Manas" }
  }
]

Airline logo image proxy. {code} is a 1–4 character airline code (alphanumeric). Returns a square PNG (200×200, transparent background) served from this domain, cached for 24h. Use it directly as an <img> src. Returns 404 if no logo exists for that code.

copy<img src="https://api.hermeseus.com/logos/airline-logos/UN" alt="airline logo" width="80" height="80">

# or
curl -L 'https://api.hermeseus.com/logos/airline-logos/TK' -o tk.png

Alternate logo source — same contract as above but served from a different image provider with a square fill crop (200×200 PNG). Use whichever renders best for a given carrier; 404 if no logo exists.

copy<img src="https://api.hermeseus.com/logos/airline-logos-v2/UN" alt="airline logo" width="80" height="80">

Fuzzy search across city name, destination name, and country. Matches starting with the query string are boosted first.

Response

copy{
  "data": [
    {
      "id": 1248,
      "external_id": 35487,
      "name": "Istanbul",
      "destination": "Istanbul, Turkey",
      "country": { "code": "TR", "name": "Turkey" }
    }
  ],
  "meta": { "query": "istanbul", "count": 1, "limit": 50 }
}

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

Request

copy{ "external_ids": [35487, 35488], "provider": "example-provider-1" }

Search available hotel offers. Provider=example-provider-1 (default) returns the rich payload with full hotel metadata (images, facilities, geo); Provider=example-provider-2 uses an alternate inventory source. All prices are normalised to USD.

Request

copy{
  "SessionId": "7f3c81d2-...",
  "Provider": "example-provider-1",
  "CheckIn": "2026-07-10",
  "CheckOut": "2026-07-14",
  "CityId": 35487,
  "CountryCode": "TR",
  "NationalityId": "AE",
  "Occupancies": [
    { "AdultCount": 2, "ChildCount": 1, "ChildAges": [7] }
  ]
}

Response (truncated)

copy{
  "Success": true,
  "PricedItineraries": [
    {
      "FareSourceCode": "cGFydG86SE9URUw0Mjg3MQ==",
      "HotelId": 42871,
      "HotelName": "Grand Hyatt Istanbul",
      "NetRate": 487.20,
      "Currency": "USD",
      "NonRefundable": false,
      "Hotel": {
        "name": "Grand Hyatt Istanbul",
        "rating": 5,
        "location": { "latitude": 41.0427, "longitude": 28.9882 },
        "images": ["https://cdn.../1.jpg", ...]
      },
      "Rooms": [ ... ],
      "CancellationPolicies": [ ... ]
    }
  ],
  "Error": null
}

Verify a hotel rate before booking. The returned itinerary is cached and is what HotelBook reads from — calling Book without CheckRate fails with Err0102004.

Reserve the previously rate-checked offer. Funds are held; the reservation auto-cancels after 10 minutes if not confirmed via HotelOrder.

Request

copy{
  "SessionId": "...",
  "FareSourceCode": "cGFydG86SE9URUw0Mjg3MQ==",
  "PhoneNumber": "+971501234567",
  "Email": "customer@example.com",
  "NationalityId": "AE",
  "ClientUniqueId": "hotel_order_88112",
  "Rooms": [
    {
      "RoomId": "R-1",
      "Passengers": [
        { "PassengerType": 1, "Title": "Mr", "FirstName": "John", "LastName": "Smith", "Nationality": "AE" }
      ]
    }
  ]
}

Confirm the reservation. Status moves 10→20 and the voucher is then issued.

Cancel a hotel booking and release held funds.

Full hotel reservation record: hotel metadata, booked rooms, voucher numbers, cancellation policies, audit timestamps.

Typed place search. Optional type restricts results to one of city, region, country, hotel, landmark, airport, district. Public — no session required.

Response

copy{
  "data": [
    {
      "id": 13,
      "external_id": 11111111456928,
      "type": "city",
      "name": "Paris",
      "label": "Paris, Ile de France, France",
      "country": { "code": "FR", "name": "France" },
      "nr_hotels": 25708
    }
  ],
  "meta": { "query": "paris", "count": 5, "limit": 20 }
}

Bulk resolve up to 500 places by public external_id. Public.

Request

copy{ "external_ids": [11111111456928, 2281] }

City search. Send CityId (from cities/search) with optional Filters, Page, Sort and Map. Provide exactly one of CityId or HotelId.

Request

copy{
  "SessionId": "7f3c81d2-...",
  "CheckIn": "2026-10-15",
  "CheckOut": "2026-10-16",
  "CityId": 11111111456928,
  "Occupancies": [ { "AdultCount": 2 } ],
  "Page": 1,
  "Sort": "price",
  "Filters": { "class": [4,5], "mealplan": ["breakfast_included"], "free_cancellation": [1] },
  "Map": { "Center": { "lat": 48.86, "lng": 2.35 }, "RadiusKm": 2 }
}

Response (truncated)

copy{
  "Success": true,
  "CheckIn": "2026-10-15", "CheckOut": "2026-10-16", "Nights": 1,
  "PricedItineraries": [
    {
      "FareSourceCode": "",
      "HotelId": 7825691,
      "HotelName": "Example Paris Hotel",
      "NetRate": 98.53, "Currency": "USD",
      "NonRefundable": true, "FreeCancellation": false, "MealPlan": "Room Only",
      "Hotel": { "external_id": 7825691, "review_score": 7.4, "location": { ... }, "images": [ ... ] }
    }
  ],
  "Meta": {
    "Pagination": { "Page": 1, "PageSize": 140, "TotalPages": 8, "HasNextPage": true },
    "PriceRange": { "min": 98.53, "max": 204.22, "currency": "USD" },
    "Sort": "price", "AvailableSorts": [ ... ], "AvailableFilters": { ... }, "Map": { ... }
  }
}

Filters

Send selections under Filters as { "key": [ ids… ] }; conditions combine with AND. For each search, every filter key, its human title, and the selectable option ids (with a live result count) are returned under Meta.AvailableFilters — each entry is { "title": …, "categories": [ { "id", "name", "count" } ] } — and the filters you sent are echoed back in Meta.AppliedFilters. The complete set of filter keys:

Deep hotel page. Send HotelId (and CityId: null) to get full property content plus one offer per room-rate.

Response (abridged)

copy{
  "Success": true, "Nights": 1,
  "Hotel": { "external_id": 6331862, "name": "...", "rating": 3, "description": "...", "facility_groups": [ ... ], "images": [ ... ] },
  "Policies": {
    "CheckIn": { "from": "15:00", "until": "23:30" }, "CheckOut": { "from": "08:00", "until": "11:00" },
    "AgeRestriction": { "min_age": 18, "phrase": "..." }, "Curfew": null,
    "Children": { "allowed": false }, "Pets": { "allowed": "NO", "charge": "NOT_APPLICABLE" },
    "Groups": null, "Meals": [ { "type": "BREAKFAST", "offer": "BOTH" } ],
    "AcceptedPaymentCards": [ "Visa", "Mastercard", ... ],
    "DamageDeposit": null, "ImportantInfo": null, "License": { "numbers": [ "1462850" ], "phrases": [ ... ] }
  },
  "Reviews": { "Score": 8.2, "Count": 12408, "SubScores": [ ... ], "Featured": [ ... ] },
  "PricedItineraries": [
    { "FareSourceCode": "NjMz...", "NetRate": 358.13, "MealPlan": "Breakfast",
      "Room": {
        "id": "...", "name": "Standard Twin Room", "adults": 2, "children": 0, "max_occupancy": 2, "beds": [ ... ],
        "size_m2": 32, "size_feet2": 344.4, "description": "The spacious twin room features…",
        "highlights": [ { "name": "Free WiFi", "icon": "wifi" }, { "name": "Air conditioning", "icon": "air-conditioning" } ],
        "amenities": [ "TV", "Minibar", "Private bathroom", ... ],
        "amenity_groups": [ { "group": "Bathroom", "items": [ "Toilet", "Shower", "Hairdryer" ] }, ... ],
        "images_count": 7, "images": [ { "url": "https://images.example.com/hotel/large/....jpg", "thumbnail_url": "https://images.example.com/hotel/thumb/....jpg" } ] } }
  ],
  "Meta": { "HotelId": 6331862, "Currency": "USD", "Offers": 5 }
}

Re-prices a FareSourceCode live and keeps it valid for at least 15 minutes. The confirmed itinerary is cached at the gateway and is what /v2/Hotel/HotelBook reads from.

Request

copy{ "SessionId": "...", "FareSourceCode": "NjMz..." }

Paginated list of products, served from the gateway's local catalogue cache (kept fresh by the daily sync + provider webhooks) rather than a live upstream call — so it's fast and resilient. Each item is augmented with image_url (main image) and images (full gallery), and the response keeps the same { data, meta.pagination } envelope. For the WHOLE catalogue in one call, use GET /v2/products/all.

Query Parameters

Responses

200 OK — paginated array of product summaries:

copy{
  "data": [
    {
      "uuid": "52d1b30f-9314-432a-9ec8-406b525a4f5c",
      "updatedAt": "2026-06-06 08:00:14",
      "title": "Hong Kong Disneyland Park Ticket",
      "titleTranslated": "Hong Kong Disneyland Park Ticket",
      "validFrom": null,
      "validThrough": null,
      "basePrice": 16.91,
      "typeName": "Attraction",
      "typeUuid": "d3c54653-dd05-598f-b193-f6683d1064ab",
      "cityName": "Hong Kong",
      "links": [
        { "method": "GET", "rel": "self",         "href": "https://api.hermeseus.com/api/Activity/v2/products/52d1b30f-..." },
        { "method": "GET", "rel": "productTypes",  "href": "https://api.hermeseus.com/api/Activity/v2/products/52d1b30f-.../product-types" }
      ],
      "image_url": "https://cdn.example.com/images/content/original/b4d63993-....jpg",
      "images": [ "https://cdn.example.com/images/content/original/b4d63993-....jpg", "..." ]
    }
  ],
  "meta": { "pagination": { "page": 1, "pageCount": 3, "perPage": 50, "total": 142 } },
  "timestamp": "2026-06-07T14:10:58.976+08:00"
}

Returns the entire product catalogue in a single response, served from the gateway's local cache — there is no 100-per-page limit. Use this when you need to pull every product at once (e.g. to build your own index) instead of walking the paginated GET /v2/products list. The cache is refreshed by the gateway on a daily schedule, so results reflect the most recent sync. By default each row is a lightweight summary (UUID, name, main image, and the product's top-level scalar fields); pass full=1 to receive every product's complete object. Every row is augmented with image_url (and, in full mode, images) from the local image cache.

Query Parameters

All filters are optional and AND together. The response adds total (products matching the filters) next to count (rows in this response). UUIDs for country/city come from GET /v2/products/by-location; type/category UUIDs from GET /v2/config.

Responses

200 OK — summary rows (default; example for ?type=Attraction):

copy{
  "success": true,
  "count": 142,
  "total": 142,
  "data": [
    {
      "uuid": "52d1b30f-9314-432a-9ec8-406b525a4f5c",
      "name": "Hong Kong Disneyland Park Ticket",
      "image_url": "https://cdn.example.com/images/content/original/b4d63993-....jpg",
      "title": "Hong Kong Disneyland Park Ticket",
      "basePrice": 16.91,
      "currency": "USD",
      "typeName": "Attraction"
    }
  ]
}

With ?full=1 each item in data is the complete Product object (same shape as GET /v2/products/{uuid}), plus image_url and images.

Public endpoint — no SessionId or credentials required. A breakdown of how many products are available in each country and, within it, each city — computed from the local catalogue cache (no upstream calls). Each country object lists its cities with a per-city product count and a country total. A product that spans several cities is counted once per distinct city, and once toward each distinct country's total (so total is the number of products available in that country, not the sum of its cities). Countries are sorted by total descending, cities by count descending.

Responses

200 OK:

copy{
  "success": true,
  "countries": 37,
  "products": 2249,
  "data": [
    {
      "country": "United Arab Emirates",
      "countryUuid": "1f2e3d4c-...",
      "cities": [
        { "city": "Dubai",     "cityUuid": "aaaa-...", "count": 128 },
        { "city": "Abu Dhabi", "cityUuid": "bbbb-...", "count": 31 }
      ],
      "total": 159
    },
    {
      "country": "Singapore",
      "countryUuid": "9a8b7c6d-...",
      "cities": [
        { "city": "Singapore", "cityUuid": "cccc-...", "count": 142 }
      ],
      "total": 142
    }
  ]
}

Full product metadata. Returns a single data object with descriptive fields (description, highlights, additionalInfo, priceIncludes/priceExcludes, itinerary, warnings, safety), commercial fields (basePrice, currency, isFlatPaxPrice, minPax/maxPax, reviewCount, reviewAverageScore, typeName/typeUuid), logistics (latitude, longitude, address, hotelPickup, airportPickup, businessHoursFrom/To, language lists), media (photos, image_url, images), categories, locations, and links. *Translated twins carry the localized text.

Path Parameters

Responses

200 OK — the Product object (excerpt):

copy{
  "data": {
    "uuid": "4dd77d8e-043b-4edb-b32a-0776043143ad",
    "updatedAt": "2026-05-16 08:03:13",
    "title": "MINT Museum of Toys Ticket",
    "titleTranslated": "MINT Museum of Toys Ticket",
    "description": "The MINT Museum of Toys houses Asia's largest collection of vintage toys ...",
    "highlights": "Delve into nostalgia with Asia's largest collection of vintage toys ...",
    "priceIncludes": "Admission ticket",
    "priceExcludes": "Hotel pickup and drop-off",
    "basePrice": 11.66,
    "currency": { "code": "USD", "symbol": "$" },
    "isFlatPaxPrice": false,
    "minPax": 1,
    "maxPax": 99,
    "reviewCount": 0,
    "reviewAverageScore": 0,
    "typeName": "Attraction",
    "typeUuid": "d3c54653-dd05-598f-b193-f6683d1064ab",
    "latitude": "1.2931", "longitude": "103.8520",
    "address": "26 Seah Street, Singapore 188382",
    "hotelPickup": false, "airportPickup": false,
    "categories": [ { "name": "Museums", "uuid": "..." } ],
    "locations": [ { "city": "Singapore", "country": "Singapore", "cityUuid": "...", "countryUuid": "..." } ],
    "photos": [ { "uuid": "...", "paths": { "original": "...", "1280x720": "..." } } ],
    "image_url": "https://cdn.example.com/images/content/original/....jpg",
    "images": [ "https://cdn.example.com/...jpg", "..." ],
    "links": [
      { "method": "GET", "rel": "self",         "href": "https://api.hermeseus.com/api/Activity/v2/products/4dd77d8e-..." },
      { "method": "GET", "rel": "productTypes",  "href": "https://api.hermeseus.com/api/Activity/v2/products/4dd77d8e-.../product-types" }
    ]
  },
  "timestamp": "2026-06-07T14:10:58.976+08:00"
}

Nationality / country-of-origin booking restrictions for a product. allow is a whitelist and exclude a blacklist of country codes; both empty means no restriction.

Response

copy{
  "data": { "exclude": [], "allow": [] },
  "timestamp": "2026-06-07T14:10:59.732+08:00"
}

Bookable variants of a product (e.g. “Admission”, “Admission with Guided Tour”, adult/child bundles). Each item carries the productTypeUuid you pass to POST /v2/bookings, plus links to its price-lists.

Response

copy{
  "data": [
    {
      "uuid": "80590844-e665-4fdc-843c-ffc6fe893403",
      "title": "Admission with Complimentary Guided Tour",
      "links": [
        { "method": "GET", "rel": "self",       "href": "https://api.hermeseus.com/api/Activity/v2/product-types/80590844-..." },
        { "method": "GET", "rel": "priceLists",  "href": "https://api.hermeseus.com/api/Activity/v2/product-types/80590844-.../price-lists" },
        { "method": "GET", "rel": "product",     "href": "https://api.hermeseus.com/api/Activity/v2/products/4dd77d8e-..." }
      ]
    }
  ],
  "timestamp": "2026-06-07T14:10:58.976+08:00"
}

Details of a single bookable variant: capacity (minPax/maxPax), per-category ticketTypes (adult/child/senior/infant/youth) with their gateRatePrice (USD), refundability (isNonRefundable, cancellationPolicies), durationDays/durationHours, voucher instructions, time slots, timezone, and options.

Path Parameters

Responses

200 OK — the ProductType object (excerpt):

copy{
  "data": {
    "uuid": "68ec3814-b54e-4e9a-ba84-7a92cfadbfb2",
    "title": "Adult Pass",
    "durationDays": 30, "durationHours": 0,
    "firstAvailabilityDate": "2026-05-31",
    "isNonRefundable": true,
    "minPax": 1, "maxPax": 10,
    "instantConfirmation": true,
    "adultGateRatePrice": 25.54,
    "ticketTypes": [
      { "type": "adult",  "label": "Person", "allowed": true,  "min": 1, "max": 10, "gateRatePrice": 20 },
      { "type": "child",  "label": "Child",  "allowed": false },
      { "type": "senior", "label": "Senior", "allowed": false }
    ],
    "cancellationPolicies": [],
    "timeslots": [],
    "timezone": "Asia/Singapore",
    "options": { "perBooking": [], "perPax": [] },
    "links": [
      { "method": "GET", "rel": "self",       "href": "https://api.hermeseus.com/api/Activity/v2/product-types/68ec3814-..." },
      { "method": "GET", "rel": "priceLists",  "href": "https://api.hermeseus.com/api/Activity/v2/product-types/68ec3814-.../price-lists" },
      { "method": "GET", "rel": "product",     "href": "https://api.hermeseus.com/api/Activity/v2/products/701cc19d-..." }
    ]
  },
  "timestamp": "2026-05-31T04:09:10.378+08:00"
}

Price & availability calendar for a product-type, one entry per date in the requested range (date_start / date_end, capped at 6 months from today). Each date lists availability per category, the bookable prices[] (each with a prices[].id = the priceId), voucherValidity, timezone and any cancellationPolicy.

Parameters

Inside prices[].rates[] each rate has a type (retailPrice = sell price, nettPrice = your cost), a category (adult/child/senior), the USD amount, and a format string showing the original price (e.g. "S$30.00").

Response (excerpt)

copy{
  "data": [
    {
      "date": "2026-07-01",
      "weekday": "Wednesday",
      "availability": [
        { "category": "adult",  "type": "shared", "quantity": 999 },
        { "category": "child",  "type": "shared", "quantity": 999 },
        { "category": "senior", "type": "shared", "quantity": 999 }
      ],
      "cancellationPolicy": [],
      "currency": "USD",
      "timezone": "Asia/Singapore",
      "voucherValidity": { "adult": { "date": "2026-10-01" }, "child": { "date": "2026-10-01" }, "senior": { "date": "2026-10-01" } },
      "prices": [
        {
          "id": "ffa35637-4073-4432-9093-e79c5aa33b81",
          "rates": [
            { "type": "retailPrice", "category": "adult", "currency": "USD", "amount": 23.32, "format": "S$30.00" },
            { "type": "nettPrice",   "category": "adult", "currency": "USD", "amount": 18.66, "format": "S$24.00" }
            /* ... child, senior ... */
          ]
        }
      ]
    }
    /* ... one object per date in the range ... */
  ],
  "timestamp": "2026-06-07T14:11:00.000+08:00"
}

Checks real-time availability and price for a single {date} (YYYY-MM-DD): data is one price-list object with the same availability / prices[].rates[] shape.

Path Parameters

Create an activity booking. Returns the booking in reserved status; the gateway mirrors it locally and finalises it asynchronously. Use data.uuid as the reference for all follow-up calls — it keeps working for the whole lifecycle. The office balance is held for the booking total.

Request Body application/json

Request — example

copy{
  "productTypeUuid": "5f3ff236-40b1-4f0a-a780-1db8649d1f5b",
  "arrivalDate": "2026-06-15",
  "partnerReference": "your-ref-123",
  "adults": 2,
  "children": 0,
  "seniors": 0,
  "customer": {
    "salutation": "Mr.",
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "jane@example.com",
    "phone": "+971501234567"
  },
  "options": { "perBooking": [], "perPax": [] }
}

Responses

200 OK — the created booking (envelope { "data": Booking, "timestamp": ... }), status reserved.

copy{
  "data": {
    "uuid": "1d59a17e-9726-4283-a5b7-bab7886e4709",
    "code": "Z2KB84Z",
    "partnerReference": "your-ref-123",
    "status": "reserved",
    "productTypeTitle": "Diamond Head State Monument Self-guided Hike",
    "productTypeUuid": "5f3ff236-40b1-4f0a-a780-1db8649d1f5b",
    "currencyCode": "USD",
    "totalAmount": 18.50,
    "amountBreakdown": [ { "name": "adult", "quantity": 2, "price": "9.25" } ],
    "arrivalDate": "2026-06-15",
    "adults": 2, "children": 0, "seniors": 0,
    "ticketTypes": [ { "type": "adult", "quantity": 2 } ],
    "links": [ "... self / confirm / cancel / productType / product ..." ]
  },
  "timestamp": "2026-06-15T16:24:49.648+08:00"
}

Filterable, paginated list of your bookings.

Query Parameters

Responses

200 OK — data is an array of Booking objects with meta.pagination.

A single booking by its reference UUID.

Path Parameters

Responses

200 OK — the Booking object:

copy{
  "data": {
    "uuid": "ae80dd16-42c7-485c-8d7e-703d948366eb",
    "code": "VKH3YHE",
    "partnerReference": "TTA_1780405735695943",
    "status": "reserved",
    "productTypeTitle": "Professional Photo Shoot in Bali - 1 Hour",
    "productTypeUuid": "97475b54-3378-4eb2-8f19-85c8b76255d8",
    "currencyCode": "USD",
    "totalAmount": 156.45,
    "amountBreakdown": [ { "name": "adult", "quantity": 1, "price": "156.45" } ],
    "arrivalDate": "2026-06-25",
    "timeSlot": null,
    "createdAt": "2026-06-02 21:08:59",
    "updatedAt": "2026-06-02 21:08:59",
    "salutation": "Mr.", "firstName": "Jane", "lastName": "Doe",
    "email": "jane@example.com", "phone": "+9120175399",
    "adults": 1, "children": 0, "seniors": 0,
    "ticketTypes": [ { "type": "adult", "quantity": 1 }, { "type": "child", "quantity": 0 }, { "type": "senior", "quantity": 0 } ],
    "options": [],
    "completedAt": null,
    "cancellationRequestAt": null,
    "cancellationRequestStatus": "none",
    "cancellationStatus": null,
    "refundDate": null, "refundAmount": null, "refundTransaction": null,
    "links": [
      { "method": "GET", "rel": "self",    "href": "https://api.hermeseus.com/api/Activity/v2/bookings/ae80dd16-..." },
      { "method": "PUT", "rel": "confirm", "href": "https://api.hermeseus.com/api/Activity/v2/bookings/ae80dd16-.../confirm" },
      { "method": "PUT", "rel": "cancel",  "href": "https://api.hermeseus.com/api/Activity/v2/bookings/ae80dd16-.../cancel" }
    ]
  },
  "timestamp": "2026-06-02T21:09:00.000+08:00"
}

Booking status values: reserved (created, awaiting confirmation), approved/confirmed (issued), cancelled, expired, rejected.

Drive a lifecycle transition with {status} = confirm or cancel:

• A new booking starts in the reserved status.
• confirm moves it to waiting and locks the inventory; on our side, funds equal to totalAmount are held on your office balance.
• Bookings left in waiting expire if not actioned within 5 days.
• cancel raises a cancellation request (subject to approval) and releases any active hold.

See the full Booking statuses table below.

Path Parameters

Request Body application/json

Only SessionId is required; the rest of the body may be empty ({ "SessionId": "..." }).

Responses

200 OK — the updated booking status:

copy{
  "data": {
    "uuid": "ae80dd16-42c7-485c-8d7e-703d948366eb",
    "status": "reserved",
    "updatedAt": "2026-06-02 21:09:31"
  },
  "timestamp": "2026-06-02T21:09:31.053+08:00"
}

Retrieves the issued vouchers / tickets for a confirmed booking. Each voucher carries a uuid, generatedAt, an optional visualId, and links (a download link and a booking link). All links[].href point at this gateway — including the download link, which targets the voucher-download endpoint below.

Path Parameters

Responses

200 OK — list of vouchers:

copy{
  "data": [
    {
      "uuid": "81995901-b405-4cf6-8cf8-df284f104117",
      "generatedAt": "2026-05-28 16:25:15",
      "links": [
        { "rel": "download", "href": "https://api.hermeseus.com/api/Activity/v2/bookings/{uuid}/download-voucher/81995901-..." },
        { "rel": "booking",  "href": "https://api.hermeseus.com/api/Activity/v2/bookings/{uuid}" }
      ],
      "visualId": null
    }
  ],
  "meta": { "pagination": { /* ... */ } },
  "timestamp": "2026-06-02T06:40:59.864+08:00"
}

Downloads the actual voucher file (usually a PDF). The gateway fetches it from the supplier and streams the bytes back through this domain — the supplier URL is never exposed. The response is the raw file with Content-Disposition: attachment, not JSON. {uuid} accepts either the booking reference you received at create time or the upstream UUID. As with every endpoint, include your SessionId (query param) when requesting the file.

copycurl -L -X GET \
  'https://api.hermeseus.com/api/Activity/v2/bookings/{uuid}/download-voucher/{voucher}?SessionId=...' \
  -o voucher.pdf

Fetches essential configuration: supported languages, currencies, locations (countries, cities), product types and categories, timezones, the base URLs, and your own user profile. The UUIDs returned here are the ones you pass to the type / category / country / city / language filters elsewhere.

Responses

200 OK — configuration object (excerpt):

copy{
  "data": {
    "now": "2026-06-07T00:05:01.740500Z",
    "version": 2,
    "serverUrl": "https://api.hermeseus.com/api/Activity",
    "photosUrl": "https://api.hermeseus.com",
    "activitiesSorting": [ "date", "-date", "price", "-price", "distance", "-distance" ],
    "user": {
      "name": "<your office name>",
      "email": "<your email>",
      "uuid": "<your user uuid>",
      "defaultPagination": 50,
      "defaultSortBy": "date",
      "defaultCurrencyCode": "USD",
      "defaultLanguageCode": "EN",
      "walletBalance": 1000.00,
      "walletBlockedBalance": -250.50,
      "walletAvailableBalance": 749.50,
      "walletAlertValue": 0
    },
    "languages":  { "data": [ { "name": "english", "code": "EN", "uuid": "..." } ] },
    "countries":  { "data": [ { "name": "Singapore", "code": "SG", "uuid": "..." } ] },
    "currencies": { "data": [ { "code": "USD", "symbol": "$", "uuid": "cd15153e-..." } ] },
    "types":      { "data": [ { "name": "Attraction", "uuid": "..." } ] },
    "categories": { "data": [ { "name": "Museums", "uuid": "..." } ] }
  },
  "timestamp": "2026-06-07T08:05:01.740+08:00"
}

Latest payload received for that (event, UUID). Add ?history=1&limit=20 to get up to 50 most recent payloads instead.

Response — found

copy{
  "event": "booking_status_updated",
  "primaryUuid": "b8e2f01c-...",
  "found": true,
  "receivedAt": "2026-05-21T03:11:48+00:00",
  "eventTimestamp": "2026-05-21 11:11:42 SGT",
  "signature": "a1b2c3...",
  "payload": { "bookingUuid": "...", "currentStatus": "APPROVED", ... }
}

Response — none yet

copy{ "event": "...", "primaryUuid": "...", "found": false, "message": "No webhook of this type has been received yet for this UUID." }

Returns the current office balance, held funds and available balance in USD.

Response

copy{
  "Success": true,
  "Balance": 12450.00,
  "HeldBalance": 340.20,
  "AvailableBalance": 12109.80,
  "Currency": "USD",
  "Error": null
}

Human-readable explanation for any Err... code.