BookingHold
Endpoint
Section titled “Endpoint”POST {base_url}/1.0/bookings/holdBlocks a specific room and rate for 5 minutes to give time to confirm.
Headers
Section titled “Headers”| Header | Value |
|---|---|
Authorization |
Bearer <access_token> |
Content-Type |
application/json |
Accept |
application/json |
Request body
Section titled “Request body”{ "rateKey": "<rateKey from /hotels/checkrates>"}| Field | Type | Description |
|---|---|---|
rateKey |
string | See the rateKey source warning above |
client |
object | Optional. Booking holder |
client.name |
string | First name |
client.surname |
string | Last name |
client.contactData[].email |
string | |
client.contactData[].phone.countryCode |
string | Country code |
client.contactData[].phone.number |
string | Phone number |
roomCriteria[] |
array | Optional. One entry per room |
roomCriteria[].roomId |
int | Room number within the quote, from 1 to N, in the order the rooms were requested in HotelRates — see Guest data in the hold |
roomCriteria[].paxes[] |
array | Guests in the room |
roomCriteria[].paxes[].age |
int | Guest age |
roomCriteria[].paxes[].name |
string | Guest name |
roomCriteria[].paxes[].surname |
string | Guest surname |
Guest data in the hold
Section titled “Guest data in the hold”BookingHold optionally accepts client and roomCriteria, sent together as in the example below. This flow coexists with the current one: client can still be sent in BookingNew, as documented in BookingNew.
- Send
roomIdfrom 1 to N in the order of the rooms in HotelRates, and send theroomCriteriaarray in that same order. - For each room, send the same guests (count and ages) that were quoted in HotelRates.
Example request with two rooms, one of them with a minor:
{ "rateKey": "<rateKey from /hotels/checkrates>", "client": { "name": "Jane", "surname": "Doe", "contactData": [ { "email": "jane.doe@example.com", "phone": { "countryCode": "+52", "number": "5512312322" } } ] }, "roomCriteria": [ { "roomId": 1, "paxes": [ { "age": 30, "name": "Jane", "surname": "Doe" }, { "age": 32, "name": "John", "surname": "Doe" } ] }, { "roomId": 2, "paxes": [ { "age": 41, "name": "Maria", "surname": "Lopez" }, { "age": 10, "name": "Ana", "surname": "Lopez" } ] } ]}BookingNew request in this flow:
{ "bookingKey": "<bookingKey from /bookings/hold>", "clientReference": "99999", "commentsForHotel": "Special requests..."}Observed in one sample:
- BookingNew was accepted with only
bookingKey,clientReferenceandcommentsForHotel. - In BookingGet, the
primaryGuestof each room was the first guest of that room.
Response (success)
Section titled “Response (success)”{ "bookingKey": "oDvxthDyTDD9xNd...XYZ=", "eventId": "441542bd-f08e-40ed-81e9-11fbd08b0915", "error": null}| Field | Type | Description |
|---|---|---|
bookingKey |
string | Token used in BookingNew. Valid 5 minutes. |
eventId |
string | Trace ID |
error |
object|null | Error details, or null on success |
Time window
Section titled “Time window”The bookingKey expires 5 minutes after issue. After expiry, the room is released and you must restart from CheckRates (or earlier).
Errors specific to this endpoint
Section titled “Errors specific to this endpoint”| Code | HTTP | Message | Cause | What to do |
|---|---|---|---|---|
| 1101 | 400 | The provided key has already been used previously | rateKey already used in a Hold | Get a new rateKey with CheckRates |
| 4001 | 400 | Invalid Hold Request, can not parse the rateKey | rateKey corrupted, encoded incorrectly, or empty | Send the rateKey from CheckRates complete and unmodified |
| 4002 | 400 | You cannot invoke 'Hold' without first performing a 'CheckRates' |
Hold called with the rateKey from Rates instead of CheckRates |
Use the rateKey returned by CheckRates, not by Rates |
| 4003 | 400 | RateKey from CheckRates older than 20 min | The rateKey from CheckRates is older than 20 min |
Repeat CheckRates |
| 4008 | 400 | The requested rate is no longer available. |
Not defined. The response does not state the reason. Observed in one response. The Hold request was sent less than 20 seconds after a successful CheckRates. 4008 and 4009 return the same message; the difference between them is not defined. | Request a new rateKey by repeating Rates and CheckRates. Do not use the code to tell the cause apart. |
| 4009 | 400 | The requested rate is no longer available. |
Not defined. The response does not state the reason. Observed in one response. The Hold request was sent less than 20 seconds after a successful CheckRates. 4008 and 4009 return the same message; the difference between them is not defined. | Request a new rateKey by repeating Rates and CheckRates. Do not use the code to tell the cause apart. |
Diagnostic patterns
Section titled “Diagnostic patterns”| Symptom | Likely cause |
|---|---|
| 4001 with valid-looking rateKey | The rateKey contains URL-unsafe characters (+, /, =) — verify it is being sent in JSON body, not as URL param |
| 4002 | Calling Hold with the rateKey from /rates instead of /checkrates |
| 1101 on retry | The previous Hold succeeded silently; check for a bookingKey in your logs |
Optional headers (informational)
Section titled “Optional headers (informational)”Some implementations send an additional header for tracking; it is not validated by the API but can be useful in logs:
| Header | Purpose |
|---|---|
CustomerIp |
Originating customer IP for analytics |
This header is optional. Its presence does not change behavior.

