Retrieving booking requests
This article covers all endpoints that provides means to retrieve booking requests.
BookingRequest object
RtB API revolves around the BookingRequest object, therefore it's imperative to understand the json object schema of the Booking Request object before we dive into the various endpoints to fetch this information.
All objects that are nested under BookingRequest is explained in their own section and can be navigated using the page hierarchy navigation on the top right of this article.
{ "id": 123456, "propertyId": 654321, "requestStatus": "BOOKED", "reservationId": 98765123479123, "checkin": "2024-02-15", "checkout": "2024-02-16", "totalPrice": { "amount": 200.0, "currency": "EUR" }, "units": [ { "id": 987654321, "rateId": 123456789, "name": "Double Room", "price": { "amount": 200.0, "currency": "EUR" } } ], "occupancy": { "adults": 2, "children": 0, "total": 2 }, "guestInfo": { "guestMessage": "Hi, We would like to stay at your property for 1 day, we have plans to do some activities nearby.", "emailVerified": true, "phoneVerified": true, "registeredSince": 2022, "domestic": false, "hasNoShow": false, "hasPastMisconduct": false, "hasStayWithPartnerBefore": true, "completedStays": "5+" }, "statusUpdateTime": "2024-02-09T16:30:00Z", "createdAt": "2024-02-08T16:27:01Z", "updatedAt": "2024-02-09T16:30:00Z" }
| Key | Value | Description |
|---|---|---|
id | Number | Booking Request Object id - this is not the Booking reservationId. |
propertyId | Number | Id of the property the request is for. |
requestStatus | String | Represents the state of of the request. This can contain the following values: - CREATED: Request is created. - APPROVED: Request is approved by partner. - REJECTED: RtB is declined by partner. - BOOKED: Request was booked by guest after being APPROVED by partner. - EXPIRED_PENDING_APPROVAL: Request expired because partner did not take any action. - EXPIRED_AFTER_APPROVAL: Request expired due to guest's inaction after partner's approval. |
reservationId | BigInt | Booking reservationId. The reservationId is present only for requests with BOOKED status. It links a request to a reservation. If the status is not BOOKED, reservationId will be null. Use the Reservations API to fetch reservation details. |
checkin | String | Requested check-in date. |
checkout | String | Requested check-out date. |
totalPrice | TotalPrice object | Total price information for the request. |
units | Array of Unit object | Unit information for the request. |
occupancy | Occupancy object | Occupancy information for the request. |
guestInfo | GuestInfo object | Guest information for the request. |
TotalPrice object
{ "amount": 200.0, "currency": "EUR" }
| Key | Value | Description |
|---|---|---|
amount | Number | Total price shown to the guest at the time of the request. Note that this price can still change if this is not a finalised Booking. |
currency | Boolean | Curreny of the total price. |
Unit object
{ "id": 987654321, "rateId": 123456789, "name": "Double Room", "price": { "amount": 200.0, "currency": "EUR" } }
| Key | Value | Description |
|---|---|---|
id | Number | Unit id. |
rateId | Number | Rate id related to this unit. You can use this id to fetch rate details. |
name | String | Name of the requested unit. |
price | Price object | Price information. |
Price object
{ "amount": 200.0, "currency": "EUR" }
| Key | Value | Description |
|---|---|---|
amount | Number | Total price of the unit. |
currency | String | Price currency. |
Occupancy object
{ "adults": 2, "children": 0, "total": 2 }
| Key | Value | Description |
|---|---|---|
adults | Number | Total number of adults. |
children | Number | Total number of children. |
total | Number | Total number of guests. (adults + children) |
GuestInfo object
Guest information is provided in the guestInfo property of the booking request object. Information unknown for a specific guest is represented as null.
{ "guestMessage": "Hi, We would like to stay at your property for 1 day, we have plans to do some activities nearby.", "emailVerified": true, "phoneVerified": true, "registeredSince": 2022, "domestic": false, "hasNoShow": false, "hasPastMisconduct": false, "hasStayWithPartnerBefore": true, "completedStays": "5+" }
| Key | Value | Description |
|---|---|---|
guestMessage | String | Message written by the guest when making the request to book. |
emailVerified | Boolean | If the email was verified by Booking.com. |
phoneVerified | Boolean | If the phone number was verified by Booking.com. |
registeredSince | String | Year of registry on Booking.com. |
domestic | Boolean | If the guest is traveling within the same country. |
hasNoShow | Boolean | If the guest has a previous no-show. |
hasPastMisconduct | Boolean | If the guest was marked with misconduct before. |
hasStayWithPartnerBefore | Boolean | Whether this guest has stayed in this property before. |
completedStays | String | "5+" is present when the guest has at least 5 completed stays on Booking.com. |
Get booking request by ID
Use the /rtb/properties/{property_id}/requests/{id} endpoint to retrieve a booking request by its ID.
Method and URL
GET https://supply-xml.booking.com/rtb/properties/{property_id}/requests/{id}
Sample request
curl --location 'https://supply-xml.booking.com/rtb/properties/{property_id}/requests/{id}' \ --header 'Authorization: Basic {your_base64_encoded_credentials}' --header 'X-Booking-Api-Version: {version_number}'
Sample responses
You can receive the following responses when using this endpoint.
Success
In case of a successful request, you'll receive the booking request with status code 200.
{ "data": [{ "id": 8744916, "propertyId": 9575899, "reservationId": 4257108177, "requestStatus": "BOOKED", "checkin": "2024-01-31", "checkout": "2024-02-01", "totalPrice": { "amount": 150.0, "currency": "EUR" }, "units": [ { "id": 957589902, "rateId": 33417965, "name": "Double Room", "price": { "amount": 150.0, "currency": "EUR" } } ], "occupancy": { "adults": 2, "children": 0, "total": 2 }, "guestInfo": { "guestMessage": "Hi, we would like to stay at your property for a night to explore the area.", "emailVerified": false, "phoneVerified": false, "registeredSince": 2017, "domestic": false, "hasNoShow": false, "hasPastMisconduct": false, "hasStayWithPartnerBefore": true, "completedStays": null }, "statusUpdateTime": "2024-01-29T11:30:02Z", "createdAt": "2024-01-29T11:28:41Z", "updatedAt": "2024-01-29T11:30:02Z", "expiresAt": null }], "warnings": [], "errors": [], "meta": { "ruid": "7b4e2580-33a7-46cb-a007-10d1e940ee0f" } }
Success with warning
It is possible that you'll receive a successful response (HTTP 200), with a metadata that contains a warning. This usually means you're using a deprecated parameter, or you're passing a parameter outside of the accepted boundaries. In this case you will receive:
- The booking request with status code 200
- An warning code
- A message explaining the warning,
- An RUID in the metadata
{ "data": [{ "id": 8744916, "propertyId": 9575899, "reservationId": 4257108177, "requestStatus": "BOOKED", "checkin": "2024-01-31", "checkout": "2024-02-01", "totalPrice": { "amount": 150.0, "currency": "EUR" }, "units": [ { "id": 957589902, "rateId": 33417965, "name": "Double Room", "price": { "amount": 150.0, "currency": "EUR" } } ], "occupancy": { "adults": 2, "children": 0, "total": 2 }, "guestInfo": { "guestMessage": "Hi, we would like to stay at your property for a night to explore the area.", "emailVerified": false, "phoneVerified": false, "registeredSince": 2017, "domestic": false, "hasNoShow": false, "hasPastMisconduct": false, "hasStayWithPartnerBefore": true, "completedStays": null }, "statusUpdateTime": "2024-01-29T11:30:02Z", "createdAt": "2024-01-29T11:28:41Z", "updatedAt": "2024-01-29T11:30:02Z", "expiresAt": null } ], "warnings": [ { "message": "updateSince is more then 72 hours in the past. Using 2024-01-28T20:07:02Z instead" } ], "errors": [], "meta": { "hasNextPage": false } }
Error or bad request
In case of an error or a bad request, you'll receive the following:
- Relevant HTTP status code
- An error code
- A message explaining the error, and
- An RUID in the metadata
{ "data": null, "warnings": [], "errors": [ { "message": "Data not found", "code": 635, "details": null, "description": "Booking request not found for property." } ], "meta": { "ruid": "04875dc9-6e57-406f-b613-cb89e94c3184" } }
List booking requests
Use the /rtb/requests endpoint to retrieve booking requests for all of your properties.
Method and URL
GET https://supply-xml.booking.com/rtb/requests
Query parameters
| Parameter | Description | Type | Required | Min | Max | Default |
|---|---|---|---|---|---|---|
propertyId | Specify a property ID to return booking requests specific to the property. | Number | False | 1 | - | - |
status | Specify the booking request status. Can contain the following values: - CREATED: Request is created. - APPROVED: Request is approved by partner. - REJECTED: Request is declined by partner. - BOOKED: Request was booked by guest after being APPROVED by partner. - EXPIRED_PENDING_APPROVAL: Request expired because partner did not take any action. - EXPIRED_AFTER_APPROVAL: Request expired due to guest's inaction after partner's approval. | String | False | - | - | - |
page | Specifies the page number you want to access. | Number | False | 1 | - | 1 |
pageSize | Specifies the number of booking requests per page. | Number | False | 1 | 100 | 20 |
updatedSince | Only returns requests modified after the provided date (ISO 8601 date in UTC. e.g. 2024-03-23T13:16:18Z) | String | False | UTC Now | UTC Now - 72 hours | UTC Now - 72 hours |
Sample request
curl --location 'https://supply-xml.booking.com/rtb/requests?status=CREATED&updatedSince=2024-03-23T13:16:18Z' \ --header 'Authorization: Basic {your_base64_encoded_credentials}' --header 'X-Booking-Api-Version: {version_number}'
Sample responses
In case of a successful request, you'll receive status code 200 with an array of booking requests from all of your properties sorted by created date in descending order and information about the next page in the metadata.
In case of an error, you'll receive the following:
- an error code
- a message explaining the error, and
- an RUID in the metadata
Success
{ "data": [{ "id": 737767, "propertyId": 10125435, "requestStatus": "EXPIRED_PENDING_APPROVAL", "checkin": "2023-06-23", "checkout": "2023-06-24", "totalPrice": { "amount": 365.0, "currency": "EUR" }, "units": [{ "id": 738539, "rateId": 35579440, "name": "One-Bedroom Apartment", "price": { "amount": 365.0, "currency": "EUR" } }], "occupancy": { "adults": 1, "children": 0, "total": 1 }, "guestInfo": { "guestMessage": "ftbvznw ifs adyk xnwffhch" }, "statusUpdateTime": "2023-05-26T13:28:54Z", "createdAt": "2023-05-25T13:27:47Z", "updatedAt": "2023-05-26T13:28:54Z" }, { "id": 686410, "propertyId": 10122635, "requestStatus": "EXPIRED_PENDING_APPROVAL", "checkin": "2023-06-24", "checkout": "2023-06-25", "totalPrice": { "amount": 392.49999999999994, "currency": "EUR" }, "units": [{ "id": 683222, "rateId": 35939440, "name": "One-Bedroom Apartment", "price": { "amount": 392.49999999999994, "currency": "EUR" } }], "occupancy": { "adults": 2, "children": 0, "total": 2 }, "guestInfo": { "guestMessage": "ktsxq oobh. vki yea mjo wkyh: oesw lswv bgvrc wal pmujo dhpc" }, "statusUpdateTime": "2023-05-26T13:28:54Z", "createdAt": "2023-05-25T13:27:47Z", "updatedAt": "2023-05-26T13:28:54Z" } ], "warnings": [], "errors": [], "meta": { "ruid": "0000000000000000000000000000000000000000000000000000000000000000000000000000", "hasNextPage": true, "nextPageUrl": "https://supply-xml.booking.com/rtb/requests?propertyId=10125435&status=EXPIRED_PENDING_APPROVAL&page=2&pageSize=2" } }