# 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.


```json
{
  "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](#totalprice-object) object | Total price information for the request. |
| `units` | Array of [Unit](#unit-object) object | Unit information for the request. |
| `occupancy` | [Occupancy](#occupancy-object) object | Occupancy information for the request. |
| `guestInfo` | [GuestInfo](#guestinfo-object) object | Guest information for the request. |


### TotalPrice object


```json
{
 "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


```json
{
 "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](#price-object) object | Price information. |


### Price object


```json
{
 "amount": 200.0,
 "currency": "EUR"
}
```

| Key | Value | Description |
|  --- | --- | --- |
| `amount` | Number | Total price of the unit. |
| `currency` | String | Price currency. |


### Occupancy object


```json
{
 "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`.


```json
{
  "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


```http
GET https://supply-xml.booking.com/rtb/properties/{property_id}/requests/{id}
```

### Sample request


```bash
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.


```json
{
  "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



```json
{
    "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



```json
{
  "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


```http
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


```bash
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


```json
{
  "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"
  }
}
```

#### Errors and warnings

Please refer to the previous [error](#error-or-bad-request) and [warning](#success-with-warning) examples.