POST/v1/hotels/book

Book hotel

Creates a hotel booking for selected rooms using holder, guest, rate and stay data.

Endpoint

Method	Path	Auth
`POST`	`/v1/hotels/book`	Required API key

Required headers:

Header	Description
`Authorization`	`Bearer <secret_key>`. The secret is shown only once when the credential is created.
`X-Travelandz-Id`	`<public_key>:<profile_code>`. The `profile_code` is the `dp_`-prefixed Developer Profile code shown in your dashboard. This binds the request to a profile and credential.
`Content-Type`	Use `application/json` for requests with a body.

Request Body Schema

Property	Type	Details	Required	Notes
`gdsprovider`	`number`		Yes	-
`hotelCode`	`string`		Yes	-
`holder`	`object`		Yes	-
`name`	`string`		Yes	-
`lastName`	`string`		Yes	-
`email`	`string`		Yes	-
`language`	`string`		No	-
`phone`	`string`		No	-
`rooms`	`array`		Yes	-
`rateKey`	`string`		Yes	-
`roomName`	`string`		Yes	-
`roomBoard`	`string`		Yes	-
`cancellationPolicies`	`array`		Yes	-
`amount`	`number`		Yes	-
`fromDate`	`string`	`Format: ISO 8601`	Yes	-

`ratePrice`	`number`		Yes	-
`priceRangeCurrency`	`enum`	`EUR`, `USD`, `CNY`	No	-
`priceRangeMinimum`	`number`		No	Minimum of the 25% of the original price of the booking
`priceRangeMaximum`	`number`		No	Maximum of the 100% of the original price of the booking.
`passengers`	`array`		Yes	-
`roomId`	`number`		Yes	-
`title`	`enum`	`mr`, `ms`, `mrs`, `miss`	Yes	-
`type`	`enum`	`adult`, `child`	Yes	-
`name`	`string`		Yes	-
`lastName`	`string`		Yes	-
`nationality`	`string`	`Format: 2 digits`	Yes	-
`age`	`number`		No	-
`gender`	`enum`	`f`, `m`	No	-

`checkIn`	`string`	`Format: YYYY-MM-DD`	Yes	-
`checkOut`	`string`	`Format: YYYY-MM-DD`	Yes	-

`searchBody`	`object`		Yes	-
`language`	`enum`	`en`, `es`, `zh`	No	Default en
`gdsprovider`	`number`		Yes	-
`hotelCode`	`string`		Yes	-
`checkIn`	`string`	`Format: YYYY-MM-DD`	Yes	-
`checkOut`	`string`	`Format: YYYY-MM-DD`	Yes	-
`countryCode`	`string`	`Format: 2 digits`	Yes	-
`guestNationality`	`string`	`Format: 2 digits`	Yes	-
`minRatePrice`	`number`		No	-
`maxRatePrice`	`number`		No	-
`rooms`	`array`		Yes	-
`adults`	`number`		Yes	Minimum value: 1, Maximum value: 4
`children`	`number`		No	Minimum value: 0, Maximum value: 4
`childrenAges`	`array`		Yes	-
`childrenAges[]`	`number[]`		Yes	-

`currency`	`enum`	`EUR`, `USD`, `CNY`	No	Default EUR
`checkIn`	`string`	`Format: YYYY-MM-DD`	Yes	-
`checkOut`	`string`	`Format: YYYY-MM-DD`	Yes	-

Success Response

Returns booking reference, status, provider response and confirmation details when available.

Response Body Schema

Property	Type	Details	Required	Notes
`bookingReference`	`string`		Yes	-
`clientReference`	`string`		Yes	-

Errors

Status	Code	Case
`400`	`unable_to_execute_booking`	Provider could not execute the booking.
`400`	-	Invalid payload or provider error.
`401/403`	auth codes	Invalid credentials.
`500`	-	Internal error.