Tripklik
API docs by Redocly

Hotels B2B API (2.0.0)

Download OpenAPI specification:

API Support: technology@infotek.ae

Our Hotels API gives you a complete B2B gateway for searching, pricing, booking, and managing hotel inventory with precision. It connects your system to real-time availability, rich hotel content, multi-rate handling, instant confirmations, and full booking lifecycle controls.

Built for speed, stability, and clean integration, it lets your platform deliver consistent results, automate operations, and scale without friction. Whether you are powering a B2B portal, a mobile app, or a distribution engine, this API provides the structure you need to move fast, stay reliable, and serve your customers with confidence.

What this API covers

Area What it does Endpoints
Autocomplete Find cities, hotels and nationalities while the user types Location Autocomplete, Nationality Autocomplete
Booking Flow Search hotels, pick rooms, book, hold, pay and confirm Search Hotels, Collect Results, Get Hotel Details, Get Available Rooms, Check Availability, Save Guest Details, Hold Booking, Pay and Confirm Booking, Retrieve Order Details
Hold Reserve free-cancellation rooms now and pay later Hold Booking, then Pay and Confirm Booking
Cancel Booking Cancel a free-cancellation booking before its deadline Retrieve Order Details, Cancel Booking
Balance Check your agency balance before paying Get Balance
Hotels Dump Download all our hotels once, then only what changed Hotels Dump

1. Autocomplete

Build the search form from two lookups (no token needed):

  • Location Autocomplete searches cities and hotels in one call.
  • Nationality Autocomplete searches countries for the guest nationality.
User types "cairo" ──▶ Location Autocomplete
                         ├── city hit:  code CAI, country.code EG ──▶ Search: city + country_code
                         └── hotel hit: id 2135352 ──────────────▶ Search: hotels_ids  (only this hotel)
                                                                      or requested_hotel_ids + city
User types "eg" ────▶ Nationality Autocomplete ──▶ code EG ──────▶ Search: nationality

2. Booking Flow

Search returns hotels with their cheapest price, either all at once or progressively with mode: poll and Collect Results. Get the rooms of the chosen hotel, then call Check Availability with the selected room combination: it confirms the rooms and price and creates the order. Save the guests on the order, then either hold it (when can_hold is true) or pay and confirm right away. Confirmation with the supplier runs in the background, so poll Retrieve Order Details until booking_status is final.

Search Hotels ──(mode: poll)──▶ Collect Results until status: completed
     │
     ▼
Get Hotel Details (optional)
     │
     ▼
Get Available Rooms ──────────▶ room_combinations[].can_hold / deadline
     │
     ▼
Check Availability ───────────▶ creates the order, returns can_hold / deadline
     │
     ▼
Save Guest Details
     │
     ├── can_hold = true ──▶ Hold Booking ──▶ (pay before deadline) ──┐
     │                                                                │
     ▼                                                                ▼
Pay and Confirm Booking ◀─────────────────────────────────────────────┘
     │
     ▼
Poll Retrieve Order Details (every 10 min, up to 3 hours)
     │
     ▼
booking_status: book_success or book_failed

3. Hold

can_hold tells you whether the booking can be held without payment, and deadline until when (pay before it, or the hold is released). They are returned by Get Available Rooms (per room combination), Check Availability and Retrieve Order Details; always use the latest one. A hold is offered only for fully free-cancellation rooms from suppliers that support it, and must be enabled for your account.

can_hold = true ──▶ Hold Booking ──▶ order status: hold
                                         │
                       before `deadline` ▼
                              Pay and Confirm Booking ──▶ booking confirmed
                                         │
                        after `deadline` ▼
                              hold released, book again

Hold can still be refused (403 with the reason) when your account's hold limits are reached, e.g. the number or total amount of active holds, or a check-in date that is too close.

4. Cancel Booking

Cancel a booking free of charge before its free-cancellation deadline. The amount is refunded to your agency balance.

Before cancelling

  1. Check the cancellation policy of the rooms (cancellation_policy in Get Available Rooms): free cancellation ends at last_cancellation_deadline, after which policies show the charges.
  2. Call Retrieve Order Details and look for an entry with action: cancel in order.available_actions. It is listed only while the booking can be cancelled through the API (free-cancellation booking, before its deadline data.deadline). If it isn't there, the booking can't be cancelled through the API; contact your account manager.
  3. Call Cancel Booking with its product_id.
Retrieve Order Details
      │
      ▼
order.available_actions has { action: "cancel", product_id }?
      │
      ├── no ──▶ can't be cancelled through the API (non-refundable, or past the deadline)
      │
      └── yes ─▶ Cancel Booking (product_id) ──▶ booking cancelled, refund to your balance

5. Balance

Bookings are paid from your agency balance (in your agency currency). Check it before Pay and Confirm Booking to avoid a payment failure.

Get Balance ──▶ balance ≥ booking price? ──yes──▶ Pay and Confirm Booking
                          │
                          no ──▶ top up your balance first

6. Hotels Dump

Keep your own copy of our hotels, to map them to your inventory or build your own search pages.

GET /api/agency/api-out/hotels/dump                     first time: all hotels
GET /api/agency/api-out/hotels/dump?since=<version>     every day: only what changed
  • First time: call it without since. You get type: full with a link to a file of all hotels (gzip-compressed JSON Lines, one hotel per line). Download it, import it, and keep its version.
  • Every day: call it with since set to your version. You get type: delta with the files of what changed, to apply in order, or type: up_to_date when nothing changed. Keep the new version. If you get type: full, replace all your hotels with it.

Links are valid for 1 hour; call the endpoint again for fresh links. A new version is published every day.

first time ──▶ Hotels Dump ─────────────▶ type: full ──▶ download, check sha256, import all, keep version
                                                                                                │
every day ───▶ Hotels Dump?since=<version> ◀─────────────────────────────────────────────────────┘
                 ├── type: up_to_date ──▶ nothing to do
                 ├── type: delta ───────▶ apply each file of `deltas` in order, keep its version
                 └── type: full ────────▶ replace all your hotels, keep version

Hotel IDs:

  • Use a hotel's id in hotels_ids or requested_hotel_ids of Search Hotels. These are the same IDs as Location Autocomplete and Sample Hotels.
  • Search results may show a hotel under one of its linked_hotel_ids. Map those to the hotel id.
  • A delete line with replaced_by means the hotel now has another ID. Move your mapping to replaced_by.

Authentication

All API endpoints require Bearer Token authentication. Each request must include a valid token in the header to ensure secure and authorized access.

Example:

Authorization: Bearer 9f12c3ab-47c8-4e91-bd84-2c7a1f83b6d1

Account Enablement

Get Balance, Hold Booking, Cancel Booking, Sample Hotels and Hotels Dump must be enabled for your account. If they return 403, contact your account manager.

Test Bookings

Send live_booking: false in Save Guest Details to make the order a test booking, or true for a live booking. When not sent, your account environment decides: live for accounts enabled for live bookings, test otherwise. Accounts not enabled for live bookings always make test bookings.

Test bookings go through the full flow (hold, pay, order details) but are never sent to the supplier. Their supplier reference and hcn start with TEST-.

Need known hotels to test with? Sample Hotels returns up to 100 4- and 5-star hotels for each test city (IST, CAI, DXB, PAR, JED); use their id in hotels_ids or requested_hotel_ids.

To test the pending flow, use a check-in date on the 17th of any month:

check-in on the 17th ──▶ Pay and Confirm ──▶ booking_status: book_pending (reference set, no HCN)
                                                   │  next confirmation run (within ~5 minutes)
                                                   ▼
                                             booking_status: book_success, hcn: TEST-HCN-...
any other check-in ────▶ Pay and Confirm ──▶ booking_status: book_success, hcn: TEST-HCN-...

Status Fields

The order has two status fields:

  • status: payment/order status (payment_pending, hold, payment_success)
  • booking_status: booking status with the supplier:
    • book_success: confirmed by the supplier.
    • book_pending: the supplier accepted the booking but hasn't confirmed it yet. Keep polling; it moves to book_success or book_failed.
    • book_failed: the supplier refused the booking.

Supplier Reference and HCN

  • reference: the supplier's booking reference, available as soon as the supplier accepts the booking.
  • hcn (hotel confirmation number): the hotel's own confirmation number, to give the guest at check-in. It depends on the supplier:
    • some return it immediately with book_success;
    • some reach book_pending first and set the HCN later, when the hotel confirms;
    • some never return it; the booking is still valid with the supplier reference.

Keep polling Retrieve Order Details while booking_status is book_pending, or until hcn is set if you need it.

Booking Status Polling

After Pay and Confirm Booking, you must poll the Order Details endpoint to retrieve the final booking status:

┌──────────────┐     ┌─────────────────┐     ┌──────────────────┐
│ PayAndConfirm│────▶│  Poll Order     │────▶│  Check Status    │
│ Booking      │     │  Details        │     │                  │
└──────────────┘     └─────────────────┘     └────────┬─────────┘
                                                      │
                     ┌────────────────────────────────┼────────────────────────────────┐
                     │                                │                                │
                     ▼                                ▼                                ▼
              ┌──────────────┐               ┌──────────────┐               ┌──────────────────┐
              │ book_success │               │ book_failed  │               │ No final status  │
              │ (Confirmed)  │               │  (Failed)    │               │ after 3 hours    │
              └──────────────┘               └──────────────┘               └────────┬─────────┘
                                                                                     │
                                                                                     ▼
                                                                            ┌──────────────────┐
                                                                            │ Mark unconfirmed │
                                                                            │ Contact Account  │
                                                                            │ Manager          │
                                                                            └──────────────────┘
  • Polling Frequency: Once every 10 minutes
  • Polling Duration: Continue for 3 hours
  • Final Statuses: book_success or book_failed. book_pending is not final: keep polling.
  • HCN: may arrive after book_success; see Supplier Reference and HCN
  • Unconfirmed Status: If no final status is received after 3 hours, mark the booking as "unconfirmed" (not failed) and contact your account manager

Autocomplete

Destination, hotel and nationality lookup for building the search form. No authentication needed.

Location Autocomplete

Searches cities and hotels in one call while the user types. No authentication is required.

Send one query per index in queries, usually both with the same q:

  • cities: use the hit's code as city and country.code as country_code in Search Hotels.
  • hotels: use the hit's id in hotels_ids (search only this hotel) or in requested_hotel_ids together with a city (show this hotel first among the city's hotels).

Results come back in results, one entry per query, in the same order.

Optional per query: limit, filter (e.g. country_code = "EG") and sort (e.g. ["combined_score:desc"] for cities, to rank popular destinations first).

Request Body schema: application/json
required
required
Array of objects

Responses

Request samples

Content type
application/json
{
  • "queries": [
    ]
}

Response samples

Content type
application/json
{
  • "results": [
    ]
}

Nationality Autocomplete

Searches countries by name or code while the user types, for the guest nationality. No authentication is required.

Use the hit's code as nationality in Search Hotels.

Request Body schema: application/json
required
q
required
string

Text typed by the user

limit
integer
Default: 20

Responses

Request samples

Content type
application/json
{
  • "q": "eg"
}

Response samples

Content type
application/json
{
  • "hits": [],
  • "query": "eg",
  • "limit": 20,
  • "offset": 0,
  • "estimatedTotalHits": 1,
  • "processingTimeMs": 0
}

Search

Hotel search operations give your system the ability to query real-time availability, pricing, and room options across all connected suppliers. You can filter by destination, dates, occupancy, and other parameters to retrieve accurate, structured results ready for display or further processing.

Search Hotels

Search for available hotels with comprehensive filtering options. Supports searching by city or by specific hotel IDs. Multiple rooms with different guest configurations can be searched.

Search modes

Set mode in the request:

  • search (default): the response arrives once every supplier has answered, with the full results.
  • poll: the response arrives immediately with the search_id, status: progress and up to 100 skeleton hotels (skeleton: true): hotel content (name, stars, photos, location) without price, so you can render the list right away. Call Collect Results with that search_id every 2-3 seconds. Each call returns everything found so far, with skeletons replaced by priced hotels as suppliers answer, so replace what you show each time. Stop when status is completed (at the latest about 60 seconds after the search).
Search (mode: poll) ──▶ search_id, status: progress, skeleton hotels (no price)
        │
        ▼
Collect Results ──▶ status: progress ──▶ priced hotels replace skeletons, call again in 2-3 s
        │
        └──────────▶ status: completed ──▶ final results, stop polling

Show skeleton hotels as "loading" and don't let users select them; only hotels with skeleton: false have rooms and prices.

Search by city, specific hotels, or both

Field Searches Limit
city + country_code All hotels of the city
hotels_ids Only the listed hotels up to 1000
city + country_code + requested_hotel_ids The city and the listed hotels; the listed hotels come first (is_requested_hotel: true) and are always returned, with is_available: false when no supplier has them up to 10

Use requested_hotel_ids when the user picked a specific hotel but should still see alternatives in the same city.

Filters

Optional: min_price, max_price (total for the stay), stars, boarding (meal plans) and free_cancellation. They narrow the city results; requested hotels are never filtered out.

How the response is organized

Search response
├── search_id ──────────────────────▶ use as `session` in every next call
├── search                            the destination and number of nights
├── fact_groups ◀────────────────┐  facilities and services, grouped by category
│   └── <group>.facts.<code>.id   │
└── hotels[]                      │  one entry per available hotel
    ├── index ────────────────────┼─▶ use as `hotel` in Hotel Details, Rooms and Check Availability
    ├── name, stars, address, location, zone, thumbnail, reviews
    ├── amenities[] ── fact ids ──┘
    ├── price                         cheapest price for all rooms and the whole stay
    ├── free_cancellation             at least one room option can be cancelled for free
    └── boarding_type[]               meal plans available (room only, breakfast, ...)
  • Show hotels[] as your results list. The price is a starting price ("from"); the exact options and prices come from Get Available Rooms.
  • index is the hotel identifier for the next calls.
  • amenities holds fact IDs: find each one in fact_groups (the facts are keyed by code; match on their id) to show the hotel's facilities and to build facility filters.
  • Sort and filter on your side using price.display_price, stars, reviews, free_cancellation, boarding_type and amenities.
Authorizations:
bearerAuth
Request Body schema: application/json
required
required
Array of objects (RoomSearch) non-empty

Array of room objects with guest configurations

nationality
required
string = 2 characters

Guest nationality code (ISO 3166-1 alpha-2)

country_code
string = 2 characters

Country code for a city search (required with city)

city
string

City code for a city search (required with country_code)

hotels_ids
Array of integers <= 1000 items

Search only these hotels (up to 1000). When provided, city and country_code are optional.

check_in
required
string <date>

Check-in date (YYYY-MM-DD)

check_out
required
string <date>

Check-out date (YYYY-MM-DD)

currency
required
string = 3 characters

Currency code (ISO 4217)

language
required
string = 2 characters

Language preference (ISO 639-1)

requested_hotel_ids
Array of integers <= 10 items

Hotels to highlight in a normal city search (up to 10). The search still returns the city's hotels, and these hotels are searched as well and listed first, flagged with is_requested_hotel. They are always returned, even when they don't match the filters or have no availability (is_available: false).

mode
string
Default: "search"
Enum: "search" "poll"

search waits for all suppliers and returns the full results. poll returns immediately with placeholder (skeleton) hotels, then you collect results with Collect Results until status is completed.

min_price
number or null

Minimum total price for the stay (price.display_price)

max_price
number or null

Maximum total price for the stay (price.display_price)

stars
Array of integers or null[ items [ 0 .. 5 ] ]

Only hotels with one of these star ratings

boarding
Array of strings or null

Only hotels offering at least one of these meal plans (values of boarding_type)

free_cancellation
boolean or null

true: only hotels with a free-cancellation option. false: only hotels without one.

Responses

Request samples

Content type
application/json
Example
{
  • "rooms": [
    ],
  • "nationality": "EG",
  • "country_code": "AE",
  • "city": "DXB",
  • "check_in": "2025-12-14",
  • "check_out": "2025-12-16",
  • "currency": "USD",
  • "language": "en"
}

Response samples

Content type
application/json
{
  • "search_id": "575f395a-e8c9-4cc4-a85b-a12551678eeb",
  • "search": {
    },
  • "hotels": [
    ],
  • "status": "progress",
  • "requested_hotel": true,
  • "is_available": true,
  • "fact_groups": {
    },
  • "fact_sheet": [
    ]
}

Collect Results

Returns the results of a search made with mode: poll. Call it every 2-3 seconds with the search_id of the search.

Each call returns all hotels found so far, in the same structure as the Search response; skeleton hotels are replaced by priced hotels as suppliers answer, so replace what you show each time. Keep calling while status is progress; stop when it is completed.

Authorizations:
bearerAuth
path Parameters
search_id
required
string

search_id returned by Search Hotels

Responses

Response samples

Content type
application/json
{
  • "search_id": "575f395a-e8c9-4cc4-a85b-a12551678eeb",
  • "search": {
    },
  • "hotels": [
    ],
  • "status": "progress",
  • "requested_hotel": true,
  • "is_available": true,
  • "fact_groups": {
    },
  • "fact_sheet": [
    ]
}

Hotel Details

Retrieve comprehensive hotel information including descriptions, amenities, images, and location data to enrich your user experience.

Get Hotel Details

Retrieves comprehensive details about a specific hotel including full description, amenities, gallery images, and location information.

Authorizations:
bearerAuth
Request Body schema: application/json
required
session
required
string <uuid>

Search session ID from search response

hotel
required
string

Hotel index from search results

currency
required
string

Currency code

language
required
string

Language preference

Responses

Request samples

Content type
application/json
{
  • "session": "575f395a-e8c9-4cc4-a85b-a12551678eeb",
  • "hotel": "0",
  • "currency": "USD",
  • "language": "en"
}

Response samples

Content type
application/json
{
  • "id": 989573,
  • "name": "Movenpick Grand Al Bustan Hotel",
  • "type": "HOTEL",
  • "description": "This hotel is located on Casablanca Road in the Al Garhoud district, just 5 minutes from Dubai International Airport...",
  • "gallery": [],
  • "stars": 5,
  • "address": "Casablanca Street, Po Box 30880 Dubai Airport",
  • "city": {
    },
  • "country": {
    },
  • "postal_code": "",
  • "phones": [
    ],
  • "provider": "hotel_beds",
  • "coordinates": {
    },
  • "emails": [
    ],
  • "website": "",
  • "thumbnail": "https://via.placeholder.com/800x600/CCCCCC/333333?text=Hotel+Image",
  • "featured": false,
  • "check_in_time": "None",
  • "check_out_time": "None",
  • "check_in_out_policy": "string",
  • "zone": {
    },
  • "amenities": [
    ],
  • "fact_details": { },
  • "facts_groups": {
    }
}

Rooms

Access detailed room availability, pricing options, meal plans, and cancellation policies for selected hotels to help customers make informed booking decisions.

Get Available Rooms

Retrieves all available room options for a selected hotel, including room types, pricing, meal plans, and cancellation policies.

How the response is organized

Each room combination is one complete, bookable option: one room for each room you searched for, with a single total price for all rooms and the whole stay. Similar options are grouped in accommodations.

Rooms response
├── lowest_price                     the cheapest room combination (same shape as below)
├── free_cancellation                at least one combination can be cancelled for free
└── accommodations[]                 groups of similar options
    └── room_combinations[]          one bookable option each
        ├── room_ids[] ─────────────▶ send as `rooms[]` to Check Availability
        ├── rooms[]                   one room per room searched for (name, meal, amenities, gallery)
        ├── total_price               price for all rooms and the whole stay
        ├── meal                      meal plan of the option
        ├── refundable                false when any room can't be cancelled
        ├── cancellation_policy       when cancellation becomes chargeable
        ├── can_hold                  the option can be held without payment
        └── deadline                  hold deadline, when known at this step
  • Show each room combination as one option, with total_price.display_price as its price.
  • To book an option, send its room_ids to Check Availability. When saving guests, room_index is the position of the room in rooms[] (0 for the first room).
  • Cancellation policy: when use_combination_policy is true, use the combination's cancellation_policy; when false, ignore it and use the cancellation_policy of each room in rooms.
  • can_hold / deadline here are a first indication: confirm them with Check Availability.
Authorizations:
bearerAuth
Request Body schema: application/json
required
session
required
string <uuid>

Search session ID from search response

hotel
required
string

Hotel index from search results

currency
required
string

Currency code

language
required
string

Language preference

Responses

Request samples

Content type
application/json
{
  • "session": "575f395a-e8c9-4cc4-a85b-a12551678eeb",
  • "hotel": "0",
  • "currency": "USD",
  • "language": "en"
}

Response samples

Content type
application/json
{
  • "accommodations": [
    ],
  • "lowest_price": {
    },
  • "free_cancellation": true
}

Booking

Confirm the rooms, save the guests, then hold or pay and confirm.

can_hold tells you whether the booking can be held without payment, and deadline until when (pay before it, or the hold is released). They are returned by Get Available Rooms (per room combination), Check Availability and Retrieve Order Details; always use the latest one. A hold is offered only for fully free-cancellation rooms from suppliers that support it, and must be enabled for your account.

Check Availability

Confirms that the selected room combination is still available at the same price, and creates the order for it.

Authorizations:
bearerAuth
query Parameters
product_type
required
string
Value: "hotel"
search_id
required
string

Session ID from the search

hotel
required
string

Hotel code

rooms[]
required
Array of strings

Room IDs of the selected room combination (room_ids from Get Available Rooms), one parameter per room

currency
required
string
Example: currency=USD
language
required
string
Example: language=en

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Product availability checked successfully",
  • "available": true,
  • "price_changed": false,
  • "price_change": 0,
  • "price": null,
  • "session_id": "575f395a-e8c9-4cc4-a85b-a12551678eeb",
  • "order_id": 9120,
  • "can_hold": true,
  • "deadline": "2026-11-20 23:59:00"
}

Save Guest Details

Saves the contact details and guests on the order created by Check Availability.

This does not book the hotel. Continue with Hold Booking (when can_hold is true) or Pay and Confirm Booking.

Authorizations:
bearerAuth
path Parameters
session
required
string <uuid>
Example: 575f395a-e8c9-4cc4-a85b-a12551678eeb

Session ID returned by Check Availability (session_id)

Request Body schema: application/json
required
required
object
required
Array of objects non-empty

One entry per guest. The first guest is the lead guest.

live_booking
boolean or null

false makes this a test booking (never sent to the supplier). true makes a live booking. When omitted, your account environment decides: live for accounts enabled for live bookings, test otherwise. Accounts not enabled for live bookings always make test bookings.

Responses

Request samples

Content type
application/json
{
  • "contact": {
    },
  • "passengers": [
    ],
  • "live_booking": false
}

Response samples

Content type
application/json
{
  • "message": "order stored successfully"
}

Hold Booking

Reserves the booking without payment. Available only when can_hold is true (see Hold in the overview). Pay with Pay and Confirm Booking before deadline, or the hold is released.

This must be enabled for your account. If it is refused, the response is 403 with the reason (for example, your account's hold limits were reached).

Authorizations:
bearerAuth
path Parameters
session
required
string <uuid>
Example: 575f395a-e8c9-4cc4-a85b-a12551678eeb

Session ID returned by Check Availability (session_id)

Responses

Response samples

Content type
application/json
{
  • "message": "Order held successfully",
  • "data": [ ],
  • "order": {
    }
}

Pay and Confirm Booking

Pays for the booking from your agency balance and confirms it with the supplier. Works for new and held bookings.

Important: After payment, you must poll the Order Details endpoint every 10 minutes for up to 3 hours to receive the final booking status (book_success or book_failed). If no final status is received, mark the booking as "unconfirmed" and contact your account manager.

Authorizations:
bearerAuth
path Parameters
session
required
string <uuid>
Example: 575f395a-e8c9-4cc4-a85b-a12551678eeb

Search session ID used in booking creation

Responses

Response samples

Content type
application/json
{
  • "message": "Order confirmed successfully",
  • "data": [
    ],
  • "order": {
    }
}

Orders

Retrieve order details and monitor booking status. After payment, poll order details every 10 minutes for up to 3 hours to receive final booking status (book_success or book_failed).

Retrieve Order Details

Retrieves comprehensive details of a specific hotel booking, including guest information, room details, pricing, and booking status.

Polling Instructions:

  • After Pay and Confirm Booking, poll this endpoint every 10 minutes
  • Continue polling for up to 3 hours
  • Monitor booking_status for the final status: book_success or book_failed (book_pending means keep polling)
  • order.hcn is set when the hotel confirms; it can arrive later than book_success, and some suppliers never return it
  • If no final status after 3 hours, mark as "unconfirmed" and contact your account manager

Hold: data.can_hold and data.deadline show whether the booking can be held and until when a held booking must be paid.

Cancel: order.available_actions lists cancel (with its product_id) while the booking can be cancelled through the API; see Cancel Booking.

Authorizations:
bearerAuth
path Parameters
session
required
string <uuid>
Example: 575f395a-e8c9-4cc4-a85b-a12551678eeb

Search session ID from booking

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "order": {
    }
}

Cancel Booking

Cancel a booking free of charge before its free-cancellation deadline. The amount is refunded to your agency balance.

Before cancelling

  1. Check the cancellation policy of the rooms (cancellation_policy in Get Available Rooms): free cancellation ends at last_cancellation_deadline, after which policies show the charges.
  2. Call Retrieve Order Details and look for an entry with action: cancel in order.available_actions. It is listed only while the booking can be cancelled through the API (free-cancellation booking, before its deadline data.deadline). If it isn't there, the booking can't be cancelled through the API; contact your account manager.
  3. Call Cancel Booking with its product_id.
Retrieve Order Details
      │
      ▼
order.available_actions has { action: "cancel", product_id }?
      │
      ├── no ──▶ can't be cancelled through the API (non-refundable, or past the deadline)
      │
      └── yes ─▶ Cancel Booking (product_id) ──▶ booking cancelled, refund to your balance

Cancel Booking

Cancels the booking with the supplier and refunds it to your agency balance.

Only call it for a product listed with action: cancel in order.available_actions of Retrieve Order Details; any other booking is rejected. Check the rooms' cancellation policy before cancelling.

This endpoint must be enabled for your account. If it returns 403, contact your account manager.

Authorizations:
bearerAuth
path Parameters
session
required
string <uuid>
Example: 575f395a-e8c9-4cc4-a85b-a12551678eeb

Session ID returned by Check Availability (session_id)

Request Body schema: application/json
required
product_id
required
integer

product_id of the cancel entry in order.available_actions

Responses

Request samples

Content type
application/json
{
  • "product_id": 12001
}

Response samples

Content type
application/json
{
  • "data": [ ],
  • "message": "Hotel Booking Cancelled Successfully",
  • "status": true
}

Account

Agency account information.

Get Balance

Returns the available balance of your agency as a plain number, in the agency currency.

This endpoint must be enabled for your account. If it returns 403, contact your account manager.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
85104.87

Static Content

All our hotels, to keep in your own system and keep up to date. See Hotels Dump for the download flow.

DumpHotel

One line of the full dump file, and the hotel of a delta upsert line.

id
integer

Hotel ID. Use in hotels_ids or requested_hotel_ids of Search Hotels.

linked_hotel_ids
Array of integers

Other IDs of the same hotel. Search results may show the hotel under one of them.

object (LocalizedName)

Text per language

stars
integer or null
type
string or null
object (LocalizedName)

Text per language

postal_code
string or null
phone
string or null
object
object or null
object
object (LocalizedName)

Text per language

thumbnail
string or null <uri>
images
Array of strings <uri> [ items <uri > ]
check_in_time
string or null
check_out_time
string or null
{
  • "id": 2135352,
  • "linked_hotel_ids": [
    ],
  • "name": {
    },
  • "stars": 5,
  • "type": "hotel",
  • "address": {
    },
  • "postal_code": "11511",
  • "phone": "+20227957171",
  • "geo": {
    },
  • "city": {
    },
  • "country": {
    },
  • "description": {
    },
  • "thumbnail": "https://images.example.com/img/AUo-hSG0n72Gwj7_yTdra1MV.jpg",
  • "images": [],
  • "check_in_time": "15:00:00",
  • "check_out_time": "12:00:00"
}

DumpDeltaLine

One line of a delta file.

One of
op
required
string
Value: "upsert"
required
object (DumpHotel)

One line of the full dump (and the hotel of a delta upsert). Empty translations are "".

Example
{
  • "op": "upsert",
  • "hotel": {
    }
}

Hotels Dump

Links to download all our hotels, or only what changed since the version you last applied.

GET /api/agency/api-out/hotels/dump                     first time: all hotels
GET /api/agency/api-out/hotels/dump?since=<version>     every day: only what changed
type When What to do
full First call (no since), or when your copy needs a full reload Download url, check sha256, replace all your hotels, keep version
delta Daily call with since Download each file of deltas in order, apply its lines, keep its version
up_to_date Nothing changed since your version Nothing to do

A new version is published every day. Links are valid until expires_at (1 hour); call this endpoint again for fresh links.

Full dump (hotels.jsonl.gz): gzip-compressed JSON Lines, one DumpHotel per line. Decompress and read it line by line; the file is large (tens of MB compressed).

Delta (delta.jsonl.gz): one DumpDeltaLine per line:

  • {"op": "upsert", "hotel": {…}}: add the hotel, or replace the hotel with the same id.
  • {"op": "delete", "id": 3011456, "replaced_by": 2135352}: remove the hotel. When replaced_by is set, the hotel now has that ID; move your mapping to it.

Use id in hotels_ids or requested_hotel_ids of Search Hotels; linked_hotel_ids are other IDs of the same hotel that search results may show.

The full dump response has an ETag (its version). Send it back in If-None-Match to get 304 Not Modified while it is still the latest.

This endpoint must be enabled for your account. If it returns 403, contact your account manager.

Authorizations:
bearerAuth
query Parameters
since
string^\d{8}T\d{6}Z$
Example: since=20261011T040000Z

The version you last applied. Omit it on your first call to get all hotels.

header Parameters
If-None-Match
string
Example: "20261012T040000Z"

The ETag of your last full dump. Returns 304 when it is still the latest.

Responses

Response samples

Content type
application/json
Example
{}

Test Data

Known hotels to try the API with.

Sample Hotels

Returns up to 100 hotels rated 4 or 5 stars for each test city: Istanbul (IST), Cairo (CAI), Dubai (DXB), Paris (PAR) and Jeddah (JED). Hotels are in the same format as the hotel hits of Location Autocomplete, with the same IDs as Hotels Dump.

Use a hotel's id in hotels_ids or requested_hotel_ids of Search Hotels, with city_code and country_code for a city search. The list is refreshed daily.

This endpoint must be enabled for your account. If it returns 403, contact your account manager.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "message": "Sample hotels retrieved successfully",
  • "status": true
}