ETG API V3
Affiliate API
Hotel search
Prebook by SERP

Prebook by SERP

🆕
This call is in development and will be available for implementation in Q1 2025. 
https://api.worldota.net/api/b2b/v3/serp/prebook
ℹ️
  • This call is required if you don’t use the Prebook call.
  • Request this call right after the SERP calls withing 6 hours.
  • Skip requesting the Hotelpage call.

The call checks if the requested rate is still available before it can be booked and improves the booking success rate:

  • If the original rate is unavailable, the call will try to find the same or similar rate with the new book_hash and match_hash field values.

  • If:

    • The same rate isn’t found.
    • The request specifies a permissible price increase in the price_increase_percent field.

    The call will try to find the same room but with an increased price. The value in the payment_options field may change.

ℹ️

The limitations:

  • The recommended call timeout is 60 seconds.
  • The minimum call timeout is 30 seconds.

Request example 

curl --user <KEY_ID>:<API_KEY> 'https://api.worldota.net/api/b2b/v3/serp/prebook' \
--header 'Content-Type: application/json' \
--data '{
  "hash": "sr-b9164354-5bef-5e30-850d-09ed638272f4",
  "price_increase_percent": 20
}'

Request body

hash String required

The unique rate ID.

ℹ️
  • Get this value from the search_hash field of the SERP calls.
  • Use this value within 6 hours after you have got the rate.
  • The minimum length is 1 character.
  • The maximum length is 256 characters.
price_increase_percent Int optional

The percentage by which the new price can be higher than the original price.

For example, if you send price_increase_percent=20 and the starting price is 1,000, the maximum allowed price for this pre-book call is 1,200.

If the value isn’t provided, the API will try to rebook with the same price or lower.

ℹ️
  • The minimum value is 0.
  • The maximum value is 100.

Response

total_hotels Int
The total number of unique hotels.
changes Object

The rate price change information.

price_changed Boolean
Whether the rate price is changed or not.
hotels [Object]

The list of hotels and their rates.

id String

The unique hotel ID.

ℹ️
  • Either this field or the hid field is required.
hid Int

The most preferred hotel ID.

ℹ️
  • Either this field or the id field is required.
  • The maximum length is 7 characters.
rates [Object]

The list of available hotel rates.

allotment Int
The number of rooms available for the rate.
amenities_data [String]

The room amenities list.

To get all available room amenities and their definitions, use the room_amenities field from the Hotel Static Data call.

any_residency Boolean

Whether the rate is allowed to be booked by the guest with any kind of residency or not.

Use it if you don’t collect the guests’ residency.

book_hash String

The unique rate ID.

ℹ️
  • The minimum length is 3 character.
  • The maximum length is 256 characters.
daily_prices [Float]
The list of daily rate prices breakdown in the request currency.
deposit Object

The deposit information of the order. Has a value if the rate payment_types.type field has the hotel value.

amount Float
The deposit amount.
currency_code String
The deposit amount currency code. Is the same as the charged (hotel) currency code.
is_refundable Boolean
Whether the deposit is refundable or not.
match_hash String

The match_hash field of the rate from the call made by the SERP mechanism.

Use this field if you are:

  • Showing rates to the users from the call made by the SERP mechanism.
  • Making a booking from these rates.
  • Using this call response as actual data on the rate.
  • Using this call response to actualize the exact rate from the calls made by the SERP mechanism.

Usage of this field can help the ETG collect analytics for SERP-HP matching.

meal String

The meal type in the rate.

To get all available meal types and their definitions, use the meals field from the Hotel Static Data call.

Has the nomeal value if no meal type is provided.

meal_data Object

The rate meals information.

value String

The meal type in the rate.

To get all available meal types and their definitions, use the meals field from the Hotel Static Data call.

Has the nomeal value if no meal type is provided.

has_breakfast Boolean
Whether breakfast is included to the rate or not.
no_child_meal Boolean
Whether the children meal is absent in the rate or not.
no_show Object

The no-show penalty information.

amount Float
The no-show penalty amount.
currency_code String
The no-show penalty amount currency code. Is the same as the charged (hotel) currency code.
from_time String
The time in the hotel timezone from which amount would be charged for the no-show penalty in the HH:MM:SS format.
payment_options Object

The accepted payment options with the specified amount to be charged.

For a booking, this amount in the requested currency should be paid.

payment_types String

The list with accepted payment options.

amount Float
The amount to be charged for the booking in the contract currency code.
currency_code String
The amount currency code. Is the same as the charged (contract) currency code.
by String
Whether the booking can be paid by a card or not.
cancellation_penalties String

The cancellation rules and commission information.

free_cancellation_before String

The date and time when the free cancellation policy expires.

Has the null value, if there is no free cancellation.

The timezone is in UTC±0.

policies String

The cancellation policies breakdown by periods.

amount_charge Float
The cancellation penalty amount in the contract currency.
amount_show Float
The cancellation penalty amount in the request currency.
end_at String

The date and time when this cancellation policy expires.

Has the null value, if it is in the time from the start_at field value till check-in.

If the start_at and end_at fields have the null value, this particular cancellation policy:

  • Has no time restrictions.
  • Is in effect all the time.

The timezone is in UTC±0.

start_at String

The date and time when this cancellation policy takes effect.

Has the null value, if it is in effect till the end_at field value.

The timezone is in UTC±0.

currency_code String
Amount’s currency. Is the same as the charged (contract’s) currency.
is_need_credit_card_data Boolean
Whether the credit card information is needed or not.
is_need_cvc Boolean
Whether the CVC is needed or not.
show_amount Float
The rate price.
show_currency_code String
The currency code in the request body.
tax_data Object

The tax information.

taxes Object

The taxes list.

amount Float
The tax amount.
currency_code String

The tax amount currency code in the ISO 4217 format.

ℹ️
  • The length is 3 characters.
  • The possible values:
    • AED.
    • AFN.
    • ALL.
    • AMD.
    • ANG.
    • AOA.
    • ARS.
    • AUD.
    • AWG.
    • AZN.
    • BAM.
    • BBD.
    • BDT.
    • BGN.
    • BHD.
    • BIF.
    • BMD.
    • BND.
    • BOB.
    • BOV.
    • BRL.
    • BSD.
    • BTN.
    • BWP.
    • BYR.
    • BYN.
    • BZD.
    • CAD.
    • CDF.
    • CHE.
    • CHF.
    • CHW.
    • CLF.
    • CLP.
    • CNY.
    • COP.
    • COU.
    • CRC.
    • CUC.
    • CUP.
    • CVE.
    • CZK.
    • DJF.
    • DKK.
    • DOP.
    • DZD.
    • EGP.
    • ERN.
    • ETB.
    • EUR.
    • FJD.
    • FKP.
    • GBP.
    • GEL.
    • GHS.
    • GIP.
    • GMD.
    • GNF.
    • GTQ.
    • GYD.
    • HKD.
    • HNL.
    • HRK.
    • HTG.
    • HUF.
    • IDR.
    • ILS.
    • INR.
    • IQD.
    • IRR.
    • ISK.
    • JMD.
    • JOD.
    • JPY.
    • KES.
    • KGS.
    • KHR.
    • KMF.
    • KPW.
    • KRW.
    • KWD.
    • KYD.
    • KZT.
    • LAK.
    • LBP.
    • LKR.
    • LRD.
    • LSL.
    • LTL.
    • LVL.
    • LYD.
    • MAD.
    • MDL.
    • MGA.
    • MKD.
    • MMK.
    • MNT.
    • MOP.
    • MRO.
    • MUR.
    • MVR.
    • MWK.
    • MXN.
    • MXV.
    • MYR.
    • MZN.
    • NAD.
    • NGN.
    • NIO.
    • NOK.
    • NPR.
    • NZD.
    • OMR.
    • PAB.
    • PEN.
    • PGK.
    • PHP.
    • PKR.
    • PLN.
    • PYG.
    • QAR.
    • RON.
    • RSD.
    • RUB.
    • RWF.
    • SAR.
    • SBD.
    • SCR.
    • SDG.
    • SEK.
    • SGD.
    • SHP.
    • SLL.
    • SOS.
    • SRD.
    • SSP.
    • STD.
    • SVC.
    • SYP.
    • SZL.
    • THB.
    • TJS.
    • TMT.
    • TND.
    • TOP.
    • TRY.
    • TTD.
    • TWD.
    • TZS.
    • UAH.
    • UGX.
    • USD.
    • USN.
    • USS.
    • UYI.
    • UYU.
    • UZS.
    • VEF.
    • VND.
    • VUV.
    • WST.
    • XAF.
    • XAG.
    • XAU.
    • XBA.
    • XBB.
    • XBC.
    • XBD.
    • XCD.
    • XDR.
    • XFU.
    • XOF.
    • XPD.
    • XPF.
    • XPT.
    • XSU.
    • XTS.
    • XUA.
    • YER.
    • ZAR.
    • ZMW.
    • ZWL.
included_by_supplier Boolean

Whether the tax is included by the supplier or not.

When it has:

  • The false value, the tax is supposed to be paid at the hotel in this object currency.
  • The true value, the tax is included in the price.
name String

The ETG tax ID.

To get all available tax IDs and their definitions, use the taxes filed from the Hotel Static Data call.

type String
The payment type.
vat_data Object

The rate VAT information.

amount Float
The VAT amount.
applied Boolean
Whether the VAT is applied or not.
currency_code String

The amount currency code in the ISO 4217 format.

ℹ️
  • The length is 3 characters.
  • The possible values:
    • AED.
    • AFN.
    • ALL.
    • AMD.
    • ANG.
    • AOA.
    • ARS.
    • AUD.
    • AWG.
    • AZN.
    • BAM.
    • BBD.
    • BDT.
    • BGN.
    • BHD.
    • BIF.
    • BMD.
    • BND.
    • BOB.
    • BOV.
    • BRL.
    • BSD.
    • BTN.
    • BWP.
    • BYR.
    • BYN.
    • BZD.
    • CAD.
    • CDF.
    • CHE.
    • CHF.
    • CHW.
    • CLF.
    • CLP.
    • CNY.
    • COP.
    • COU.
    • CRC.
    • CUC.
    • CUP.
    • CVE.
    • CZK.
    • DJF.
    • DKK.
    • DOP.
    • DZD.
    • EGP.
    • ERN.
    • ETB.
    • EUR.
    • FJD.
    • FKP.
    • GBP.
    • GEL.
    • GHS.
    • GIP.
    • GMD.
    • GNF.
    • GTQ.
    • GYD.
    • HKD.
    • HNL.
    • HRK.
    • HTG.
    • HUF.
    • IDR.
    • ILS.
    • INR.
    • IQD.
    • IRR.
    • ISK.
    • JMD.
    • JOD.
    • JPY.
    • KES.
    • KGS.
    • KHR.
    • KMF.
    • KPW.
    • KRW.
    • KWD.
    • KYD.
    • KZT.
    • LAK.
    • LBP.
    • LKR.
    • LRD.
    • LSL.
    • LTL.
    • LVL.
    • LYD.
    • MAD.
    • MDL.
    • MGA.
    • MKD.
    • MMK.
    • MNT.
    • MOP.
    • MRO.
    • MUR.
    • MVR.
    • MWK.
    • MXN.
    • MXV.
    • MYR.
    • MZN.
    • NAD.
    • NGN.
    • NIO.
    • NOK.
    • NPR.
    • NZD.
    • OMR.
    • PAB.
    • PEN.
    • PGK.
    • PHP.
    • PKR.
    • PLN.
    • PYG.
    • QAR.
    • RON.
    • RSD.
    • RUB.
    • RWF.
    • SAR.
    • SBD.
    • SCR.
    • SDG.
    • SEK.
    • SGD.
    • SHP.
    • SLL.
    • SOS.
    • SRD.
    • SSP.
    • STD.
    • SVC.
    • SYP.
    • SZL.
    • THB.
    • TJS.
    • TMT.
    • TND.
    • TOP.
    • TRY.
    • TTD.
    • TWD.
    • TZS.
    • UAH.
    • UGX.
    • USD.
    • USN.
    • USS.
    • UYI.
    • UYU.
    • UZS.
    • VEF.
    • VND.
    • VUV.
    • WST.
    • XAF.
    • XAG.
    • XAU.
    • XBA.
    • XBB.
    • XBC.
    • XBD.
    • XCD.
    • XDR.
    • XFU.
    • XOF.
    • XPD.
    • XPF.
    • XPT.
    • XSU.
    • XTS.
    • XUA.
    • YER.
    • ZAR.
    • ZMW.
    • ZWL.
included Boolean
Whether the VAT is included or not.
value Float
⚠️
DEPRECATED

The VAT amount in the currency of this object currency_code field value.

rg_ext Object

The hotel room type.

Use this field to get extra data on the room from the hotel static data. For example, room images, descriptions.

balcony Int

Whether there is a balcony or not.

ℹ️

The possible values:

  • 0—no balcony.
  • 1—a balcony.
bathroom Int

The room bathroom information.

ℹ️

The possible values:

  • 0—undefined.
  • 1—a shared bathroom.
  • 2—a private bathroom.
  • 3—an external private bathroom.
bedding Int

The room bedding information.

ℹ️

The possible values:

  • 0—undefined.
  • 1—a bunk bed.
  • 2—a single bed.
  • 3—a double bed.
  • 4—a twin bed.
  • 7—multiple beds.
bedrooms Int

The bedroom number.

ℹ️

The possible values:

  • 0—undefined.
  • 1—1 bedroom.
  • 2—2 bedrooms.
  • 3—3 bedrooms.
  • 4—4 bedrooms.
  • 5—5 bedrooms.
  • 6—6 bedrooms.
capacity Int

The maximum number of main bed places without additional charges and excluding extra beds, cots, etc.

ℹ️

The possible values:

  • 0—undefined.
  • 1—single.
  • 2—double.
  • 3—triple.
  • 4—quadruple.
  • 5—quintuple.
  • 6—sextuplet.
class Int

The room class information.

ℹ️

The possible values:

  • 0—run of house.
  • 1—dorm.
  • 2—capsule.
  • 3—room.
  • 4—junior suite.
  • 5—suite.
  • 6—apartment.
  • 7—studio.
  • 8—villa.
  • 9—cottage.
  • 17—bungalow.
  • 18—chalet.
  • 19—camping.
  • 20—tent.
club Int

Whether it is a club room or not.

ℹ️

The possible values:

  • 0—not a club room.
  • 1—a club room.
family Int

Whether it is a family room or not.

ℹ️

The possible values:

  • 0—not a family room.
  • 1—a family room.
floor Int

The room floor Information.

ℹ️

The possible values:

  • 0—undefined.
  • 1—a penthouse floor.
  • 2—a duplex floor.
  • 3—a basement floor.
  • 4—an attic floor.
quality Int

The room quality information.

ℹ️

The possible values:

  • 0—undefined.
  • 1—economy.
  • 2—standard.
  • 3—comfort.
  • 4—business.
  • 5—superior.
  • 6—deluxe.
  • 7—premier.
  • 8—executive.
  • 9—presidential.
  • 17—premium.
  • 18—classic.
  • 19—ambassador.
  • 20—grand.
  • 21—luxury.
  • 22—platinum.
  • 23—prestige.
  • 24—privilege.
  • 25—royal.
sex Int

The room gender restrictions.

ℹ️

The possible values:

  • 0—undefined.
  • 1—male.
  • 2—female.
  • 3—mixed.
view Int

The room view information.

ℹ️

The possible values:

  • 0—undefined.
  • 1—bay view.
  • 2—bosphorus view.
  • 3—burj-khalifa view.
  • 4—canal view.
  • 5—city view.
  • 6—courtyard view.
  • 7—dubai-marina view.
  • 8—garden view.
  • 9—golf view.
  • 17—harbour view.
  • 18—inland view.
  • 19—kremlin view.
  • 20—lake view.
  • 21—land view.
  • 22—mountain view.
  • 23—ocean view.
  • 24—panoramic view.
  • 25—park view.
  • 26—partial-ocean view.
  • 27—partial-sea view.
  • 28—partial view.
  • 29—pool view.
  • 30—river view.
  • 31—sea view.
  • 32—sheikh-zayed view.
  • 33—street view.
  • 34—sunrise view.
  • 35—sunset view.
  • 36—water view.
  • 37—with view.
  • 38—beachfront.
  • 39—ocean front.
  • 40—sea front.
room_data_trans Object

The room information in the request language.

bathroom String

The room bathroom information.

Has the null value, if it is a private bathroom.

bedding_type String
The room bedding information.
main_name String
The room name.
main_room_type String
The room type.
misc_room_type String
The room additional information.
legal_info Object

The hotel and service provider legal information.

Has the value different from null for only countries where it is mandatory to have this information.

Has the null value for the calls made by the SERP mechanism.

hotel Object

The hotel legal information.

name String
The hotel legal name.
address String
The hotel legal address.
taxpayer_number String

The Taxpayer Personal Identification Number (INN) of the hotel.

ℹ️
  • The length is 10 characters.
state_registration_number String

The State Registration Number for Companies (OGRN) of the hotel.

ℹ️
  • The length is 13 characters.
work_time String
The hotel legal address working hours.
provider Object

The service provider legal information.

name String
The service provider legal name.
address String
The service provider legal address.
taxpayer_number String

The Taxpayer Personal Identification Number (INN) of the service provider.

ℹ️
  • The length is 10 characters.
state_registration_number String

The State Registration Number for Companies (OGRN) of the service provider.

ℹ️
  • The length is 13 characters.
room_name String
The room name in the request language.
room_name_info Object
The optional object that may help to resolve certain matching problems. To get access to the object, contact your account manager.
serp_filters [String]
⚠️
DEPRECATED

The list of amenities at the hotel.

Response example 

{
  "data": {
    "hotels": [
      {
        "id": "ambassador_hotel_2",
        "hid": 7597119,
        "rates": [
          {
            "book_hash": "p-4ee7f78d-af14-453f-b3fd-e8b1a80102ae",
            "match_hash": "m-b743e28f-060e-54a8-8e61-70931704806d",
            "daily_prices": [
              "12.60"
            ],
            "meal": "breakfast",
            "meal_data": {
              "value": "breakfast",
              "has_breakfast": true,
              "no_child_meal": false
            },
            "payment_options": {
              "payment_types": [
                {
                  "amount": "12.50",
                  "show_amount": "12.60",
                  "currency_code": "EUR",
                  "show_currency_code": "EUR",
                  "by": null,
                  "is_need_credit_card_data": false,
                  "is_need_cvc": false,
                  "type": "deposit",
                  "vat_data": {
                    "included": false,
                    "applied": false,
                    "amount": "0.00",
                    "currency_code": "EUR",
                    "value": "0.00"
                  },
                  "tax_data": {
                    "taxes": [
                      {
                        "name": "city_tax",
                        "included_by_supplier": false,
                        "amount": "2.00",
                        "currency_code": "EUR"
                      }
                    ]
                  },
                  "perks": {},
                  "commission_info": {
                    "show": {
                      "amount_gross": "14.00",
                      "amount_net": "12.60",
                      "amount_commission": "1.40"
                    },
                    "charge": {
                      "amount_gross": "14.00",
                      "amount_net": "12.50",
                      "amount_commission": "1.50"
                    }
                  },
                  "cancellation_penalties": {
                    "policies": [
                      {
                        "start_at": null,
                        "end_at": null,
                        "amount_charge": "12.50",
                        "amount_show": "12.60",
                        "commission_info": {
                          "show": {
                            "amount_gross": "14.00",
                            "amount_net": "12.60",
                            "amount_commission": "1.40"
                          },
                          "charge": {
                            "amount_gross": "14.00",
                            "amount_net": "12.50",
                            "amount_commission": "1.50"
                          }
                        }
                      }
                    ],
                    "free_cancellation_before": null
                  },
                  "recommended_price": {
                    "amount": "12.50",
                    "currency_code": "EUR",
                    "show_amount": "12.60",
                    "show_currency_code": "EUR"
                  }
                }
              ]
            },
            "bar_rate_price_data": {
              "amount": "84.92",
              "currency_code": "EUR"
            },
            "rg_ext": {
              "class": 4,
              "quality": 0,
              "sex": 0,
              "bathroom": 2,
              "bedding": 3,
              "family": 0,
              "capacity": 2,
              "club": 0,
              "bedrooms": 0,
              "balcony": 0,
              "view": 0,
              "floor": 0
            },
            "legal_info": {
              "hotel": {
                "name": "",
                "address": "",
                "taxpayer_number": "0000000000",
                "state_registration_number": "0000000000000",
                "work_time": "from 9-18 local time"
              },
              "provider": {
                "name": "",
                "address": "",
                "taxpayer_number": "0000000000",
                "state_registration_number": "0000000000000"
              }
            },
            "room_name": "Standard Double room (full double bed)",
            "room_name_info": {
              "original_rate_name": "Basic Room, 1 Double Bed, Non Smoking"
            },
            "serp_filters": [
              "has_bathroom",
              "has_breakfast",
              "has_internet"
            ],
            "sell_price_limits": null,
            "allotment": 10,
            "amenities_data": [
              "non-smoking"
            ],
            "any_residency": true,
            "deposit": null,
            "no_show": {
              "amount": "25.00",
              "currency_code": "EUR",
              "from_time": "12:00:00"
            },
            "room_data_trans": {
              "main_room_type": "Standard Double room",
              "main_name": "Standard Double room",
              "bathroom": null,
              "bedding_type": "full double bed",
              "misc_room_type": null
            }
          }
        ],
        "bar_price_data": null
      }
    ],
    "changes": {
      "price_changed": false
    }
  },
  "debug": {
    "request": {
      "hash": "sr-b9164354-5bef-5e30-850d-09ed638272f4",
      "price_increase_percent": 10
    },
    "key_id": 1234,
    "validation_error": null
  },
  "status": "ok",
  "error": null
}

Errors

The error field has the value specified in the headers below.

no_available_rates

The rate with the price_increase_percent field value isn’t found. Try to change the value.

rate_not_found

The rate with the hash field value isn’t found. Too much time has probably passed since the search request. Send another search request.

invalid_params

  • The hash field is required.
  • The hash field value is incorrect.
  • The price_increase_percent field value is less than 0.

unknown

The internal ETG services’ timeout.

prebook_from_serp_disabled

There is no permission to use this call for this contract. Contact the API support team.

contract_mismatch

The pre-book contract differs from the rate contract. They should be the same.

PrebookLook up rate