FAQ
Short answers to the questions agencies ask most about search, rooms and guests, booking, hotel content and commercial terms, plus the passenger validation errors the API returns and how to prevent them.
The answers below come from the official FAQ. Every number is also in Limits.
Search and rates
Yes. Send the guest's market in sourceMarket, for example AE or ES.
No. You pull availability and prices with Quote.
JSON only. There is no XML.
Yes. Send Accept-Encoding: gzip on every call, because requests without it may be rejected.
Up to 3,000 hotel codes per Quote, all within about 200 km of each other.
Set bestCombinations: false in the Quote filter, and call Quote single for hotels marked quoteSingleNeeded: true.
It depends on the supplier, because the platform is a hub that connects many suppliers.
One hour. The combinationKey has its own clock: it expires 40 minutes after a Quote and 60 minutes after Confirm or Prebook.
No. Prices always come in your microsite's currency, so convert for display yourself.
30 nights, counted as checkOut minus checkIn. A longer stay gets 400, You cannot select more than 30 nights. Suppliers may add their own restrictions.
From GET /destination/{micrositeId}, described in Destinations. In your test account, use your test microsite id.
Rooms and guests
15, with at most 6 in each room and at most 4 rooms.
Ages 0-17. A booking can have at most 14 children and a room at most 5, and every room needs at least 1 adult.
Up to 15 per booking and 6 per room.
Yes. Up to 4 rooms, and each room can have a different occupancy.
No. Bedding type cannot be sent to the hotel.
The API receives them, but only mandatory data is forwarded to suppliers.
requestedAge, the age at the end of the stay. Send it even when requiredField doesn't list it.
The standard ones. The API validates phone numbers with Google libphonenumber (com.google.i18n.phonenumbers), so validate client-side with the same library.
Booking
No. One flow books one hotel. To search many hotels at once, send a list of codes to Quote.
Not as structured requests. You can send free text to the hotel in commentToAccommodation at Prebook.
Yes, from Quote to Book. Static content calls can use any valid token.
The tolerance is set per microsite, as a percentage or a fixed amount, and defaults to 0.5%. Beyond it the booking closes PRICE_ERROR.
Content
No. Use the first image in images[].
Booking.com, TripAdvisor and Expedia only.
Yes, but hotel profiles show descriptions, and the data changes over time. See Facilities.
Hotel or apartment: HOTEL or APARTMENT in accommodationType.
ISO 3166-1 alpha-2, for example ES.
S1 to S6 are stars, L1 to L5 keys, H1 to H5 suns, and IN means none.
Commercial
Either, depending on the microsite and credential, and responses don't show which. Ask your Nava account manager which one you have.
Yes, a valid GIATA licence is required. giataId can be null; where present, it maps the same hotel from several suppliers onto one record.
Expect a few days. See Certification for what the review needs.
Validation errors the API returns
When passenger data fails at Prebook, the API returns one of these errors. Check each one client-side so the guest can fix their input before you call Prebook.
| Error | Cause | Prevent it client-side |
|---|---|---|
| Missing the following required field of the contact person: Birthdate | A field that Confirm's requiredField lists for that person was not sent. The API returns one message per person and field, for example also ... of the roomHolder person: Birthdate. | Build the guest form from requiredField and require every listed field. |
| Phone incorrect | The number is not valid for its country code, or a field breaks the format rules. | Validate with libphonenumber. Send phoneCountryCode as + and digits, and phone as digits only, at most 15. |
| Invalid email format | email is not a valid address. | Validate the email format. |
| Duplicate passenger names | Two passengers in the booking have the same name. | Check that names are unique across the booking. Add a suffix such as JR where needed. |
| Birthdate does not match requested age | birthDate doesn't give the requestedAge at the end of the stay. | Compute the age at checkout from the birth date. |
| Child age different from availability / order changed | A child's requestedAge differs from the quoted age, or the rooms were reordered. | Quote with ages at checkout, and build Prebook from the stored quote distributions. |
| Duplicate document | Two passengers have the same document number. | Check that document numbers are unique. |
| Passport expires before end of trip | passportExpirationDate is before the end of the stay. | Compare the expiry date with checkOut. |
| Document type informed without document number | documentType was sent without documentNumber. | Require a number whenever a document type is set. |
| Different number of persons in distribution / order changed | A room has a different number of people than in the quote, or the rooms were reordered. | Build Prebook from the stored quote distributions, in the same order. |
The spec also validates field patterns the FAQ doesn't list, such as Latin-only names and digits-only phone numbers. They are in Limits.
Related
Scenario playbooks
Step-by-step handling for the situations every hotel integration meets, from a standard booking to on-request bookings, Book timeouts, cancellations, back-office sync and a sudden wave of 401 errors.
Certification
What the review before go-live covers, the three test-account bookings it asks for, what to prepare, how to make the bookings an automated test, and a go-live checklist.