# v3.1 Accommodation quick guide

**Follow this quick guide to start playing with our v3.1 Accommodation API collection in your client application**.

div
strong
⏱️ Estimated time to complete:
 15 - 30 minutes 
br
This quick guide shows the minimum steps needed to integrate the [Demand API accommodation endpoints](/demand/docs/open-api/demand-api/accommodations).

## Steps

Follow these steps to test a basic example:

> *A traveller searches for a 2-night stay in Amsterdam for 2 adults in 1 room.*


### 1. Search for accommodation

To find properties that match the use case search criteria:

→ Use the [accommodations/search](/demand/docs/open-api/demand-api/accommodations/accommodations/search) endpoint.

**Example request:**


```json
{
  "country": "es",
  "booker": {
    "country": "es",
    "platform": "mobile"
  },
  "checkin": "2026-11-06",
  "checkout": "2026-11-08",
  "guests": {
    "number_of_rooms": 1,
    "number_of_adults": 2
  }
}
```

details
summary
More details

You can use different search parameters:
* `city` is a Booking.com location ID (get these from [/locations/cities endpoint](/demand/docs/open-api/demand-api/commonlocations/common/locations/cities)).
* Always use ISO 3166-1 alpha-2 lowercase for `country` (get these from [/locations/countries endpoint](/demand/docs/open-api/demand-api/commonlocations/common/locations/countries)).
* `platform` can be "desktop", "mobile", or "tablet".
* You can also use `accommodations` IDs for specific property search. 

* See the [accommodation search guide](/demand/docs/accommodations/search-for-available-properties/) for examples and tips on creating search requests.
* See the [Data conventions guide](/demand/docs/development-guide/code-conventions) for date/times formats.


**Example response:**

The response contains a list of accommodations that match the specified search criteria, including the price and url to Booking.com property page.


```json
{
  "request_id": "01khtsn77md9gvwbw157960692",
  "data": [
    {
      "id": 13766008,
      "commission": {
        "amount": 0,
        "percentage": 0
      },
      "currency": "EUR",
      "deep_link_url": "booking://hotel/13766008?affiliate_id=956509&checkin=2026-11-06&checkout=2026-11-08&mcid=10",
      "price": {
        "book": 644.8,
        "total": 644.8
      },
      "products": [
        {
          "id": "1376600801_409788848_0_0_0_843543",
          "bundle": 843543,
          "children": [],
          "deal": {
            "discount_percentage": 14,
            "public_price": 748,
            "tags": [
              "seasonal_deal"
            ]
          },
          "number_available_at_this_price": 1,
          "number_of_adults": 2,
          "policies": {
            "cancellation": {
              "free_cancellation_until": null,
              "type": "special_conditions"
            },
            "meal_plan": {
              "meals": [],
              "plan": "no_plan"
            },
            "payment": {
              "prepayment_required": true,
              "timings": [
                "pay_online_now"
              ]
            }
          },
          "price": {
            "book": 644.8,
            "total": 644.8
          },
          "room": 1376600801
        }
      ],
      "url": "https://www.booking.com/hotel/es/beach-apartment-denia.html?aid=956509&checkin=2026-11-06&checkout=2026-11-08&no_rooms=1&group_adults=2&mcid=10"
    }
  ]
}
```

Keep the accommodation `id` (13766008) for the next step.

→ [Try it yourself](/demand/docs/open-api/demand-api/accommodations/accommodations/search)

### 2. Get accommodation details

→ Call [/accommodations/details](/demand/docs/open-api/demand-api/accommodations/accommodations/details) using the accommodation `id` from the search response (13766008).

**Example request:**


```json
{
  "accommodations": [
      13766008
  ],
  "extras": [
    "description"
  ],
  "languages": [
    "en-gb"
  ]
}
```

details
summary
More details
Multiple languages can be requested; if data isn't available in your preferred language, English is returned by default.

> ![genius-bulb](/assets/genius-bulb.3e13976eeeabd0526f1d76bfb7de5967932211a5ef4afe526a3b0a71a7b02fb0.5e2a7131.png) Use the `extras` field to retrieve more details about the accommodation. For example:
* If you want to use a photograph in your search results, add the field `"extras": ["photos"]` to your request.
* If you wish to see the property supported [payment methods](/demand/docs/payments/payments-methods), add the field `"extras": ["payment"]` to your request.



Example:


```json
  "extras": [
    "description",
    "photos",
    "facilities",
    "payment"
  ],
```

→ [Try it yourself](/demand/docs/open-api/demand-api/accommodations/accommodations/details)

**Example response:**

The response contains all the information about the selected accommodation including contact information, number of rooms, score/reviews, etc.


```json
{
  "request_id": "01k2kv6g4de00n4cw4cvr4v5bm",
  "data": [
    {
      "id": 10507360,
      "name": {
        "en-gb": "Demand API Sandbox Hotel Orion"
      },
      "accommodation_type": 204,
      "booker_address_required": false,
      "checkin_checkout_times": {
        "checkin_from": "12:00:00",
        "checkin_to": "20:00:00",
        "checkout_from": "08:00:00",
        "checkout_to": "12:00:00"
      },
      "contacts": {
        "general": {
          "email": "demand.api.dev@booking.com",
          "telephone": "+31207125609"
        },
        "reservations": null
      },
      "currency": "EUR",
      "is_genius": true,
      "is_work_friendly": false,
      "location": {
        "address": {
          "en-gb": "Oosterdoksstraat 154"
        },
        "city": -2140479,
        "coordinates": {
          "latitude": 52.376388,
          "longitude": 4.90919
        },
        "country": "nl",
        "districts": [
          145,
          9173
        ],
        "postal_code": "1011 DL",
        "regions": [
          1010
        ]
      },
      "meal_prices": {
        "breakfast": 12,
        "lunch": 10,
        "dinner": 15
      },
      "number_of_rooms": 300,
      "ranking": 4703915,
      "rating": {
        "number_of_reviews": 0,
        "preferred": true,
        "review_score": null,
        "stars": 5,
        "stars_type": "official"
      },
      "spoken_languages": [
        "en-gb"
      ],
      "url": "https://www.booking.com/hotel/nl/demand-api-sandbox-orion.html?aid=956509"
    }
  ]
}
```

### 3. Get availability and prices

→  Use accommodations/availability endpoint with the same traveller criteria.

* Include the accommodation id (13766008) from search.


**Example request:**


```json
{
  "accommodation": 13766008,
  "booker": {
    "country": "nl",
    "platform": "desktop"
  },

  "checkin": "2026-02-02",
  "checkout": "2026-02-10",
  "extras": [
    "include_bundle_variants"
  ],
  "guests": {
    "number_of_adults": 2,
    "number_of_rooms": 1
  }
}
```

**Example response:**

The response includes the available products and prices, together with a `recommendation`.


```json
{
  "request_id": "01k2m3js8k6rkgb09vehxcfbjy",
  "data": {
    "id": 10507360,
    "currency": "EUR",
    "products": [
      {
        "id": "1050736003_405384551_0_42_0_1122794",
        "commission": {...},
        "deal": {
          "discount_percentage": 3,
          "public_price": 98.2,
          "tags": [
            "mobile_rate"
          ]
        },
        "maximum_occupancy": {
          "adults": 4,
          "children": null,
          "total": 4
        },
        "number_available_at_this_price": 6,
        "policies": {...},
        "price": {
          "book": 95.38,
          "total": 95.38
        },
        "room": 1050736003
      },
      {
        "id": "1050736003_377312697_0_41_0_1122794",
        "commission": {
          "amount": 0,
          "percentage": 0
        },
        "deal": {
          "discount_percentage": 5,
          "public_price": 140,
          "tags": [
            "mobile_rate"
          ]
        },
        "maximum_occupancy": {
          "adults": 4,
          "children": null,
          "total": 4
        },
        "number_available_at_this_price": 6,
        "policies": {
          "cancellation": {
            "free_cancellation_until": "2025-10-29T22:59:59+00:00",
            "schedule": [
              {
                "from": "now",
                "price": 0
              },
              {
                "from": "2025-10-29T23:00:00+00:00",
                "price": 31.5
              }
            ],
            "type": "free_cancellation"
          },
          "meal_plan": {
            "meals": [
              "breakfast"
            ],
            "plan": "breakfast_included"
          },
          "payment": {
            "prepayment_required": false,
            "timings": [
              "pay_at_the_property",
              "pay_online_later",
              "pay_online_now"
            ]
          }
        },
        "price": {
          "book": 133,
          "total": 133
        },
        "room": 1050736003
      },
    ],
    "recommendation": {
      "price": {
        "book": 95.38,
        "total": 95.38
      },
      "products": [
        {
          "id": "1050736003_405384551_0_42_0_1122794",
          "children": [],
          "number_of_adults": 2,
          "price": {
            "book": 95.38,
            "total": 95.38
          }
        }
      ]
    },
    "url": "https://www.booking.com/hotel/nl/demand-api-sandbox-orion.html?aid=956509&checkin=2025-11-06&checkout=2025-11-08&no_rooms=1&group_adults=2"
  }
}
```

> ![genius-bulb](/assets/genius-bulb.3e13976eeeabd0526f1d76bfb7de5967932211a5ef4afe526a3b0a71a7b02fb0.5e2a7131.png) Highlight the `recommendation` field to show the best-priced option.


Prices may change between search and availability. Always confirm before booking.

→ ([Try it yourself](/demand/docs/open-api/demand-api/accommodations/accommodations/availability))

### 4. Handle the booking

Choose your integration type:

* **Search, look and redirect** → Redirect travelleres to the Booking.com `url` provided in the availability response.
* **Search, look and book** → Book within your application using [/orders/preview](/demand/docs/open-api/demand-api/orders/orders/preview) and [/orders/create](/demand/docs/open-api/demand-api/orders/orders/create)


For Search, look and book, you must have:

* An approved business case.
* A signed partner agreement.


Orders guides
* See the [Orders creation guide](/demand/docs/orders-api/order-preview-create) to learn how to proceed the booking.


## Best practices

✓ Always include your API key token and `X-Affiliate-Id` in every request.

✓ Use the correct [data conventions](/demand/docs/development-guide/code-conventions) in your requests to avoid errors.

✓ Store static location data (cities, countries, etc) to reduce API calls.

## Next steps

Congratulations, by now you know the basics of how to use the key accommodation endpoints!

* See the [Search, look and book tutorial](/demand/docs/accommodations/accommodation-tutorial) for full step by step guide.
* Refer to the [Orders](/demand/docs/open-api/demand-api/orders) and [payments](/demand/docs/payments/how-to) guides to make your first order.