Home

Beta version

This API endpoint is currently in beta. Make sure to direct any questions during the beta phase to your Booking.com contact person via the appropriate channels.

Migrating Content API to modernised APIs

Booking.com provides self-contained, modernised APIs each with a set of well-defined features to create and manage a property. The modernisation effort is an ongoing task and this topic will be updated based on the availability of the modernised APIs.

This topic provides details of the APIs that currently replace the functionality of the OTA_HotelDescriptiveContentNotif (HDCN) and the OTA_HotelDescriptiveInfo endpoints. In the future, we are also planning to replace the functionality of the OTA_HotelInvNotif endpoint with several modernised APIs.

Revisiting the old Content API usage

The existing Content API provides many functionalities supported by multiple endpoints. For example, you must use the OTA_HotelDescriptiveContentNotif endpoint to create and manage the following:

  • Property name, location, and property type and number of rooms.
  • Property facilities information.
  • Service details such as restaurants, parking and others.
  • Cancellation and pets policy details.
  • Parking and other fee details.

In addition, you must use the OTA_HotelInvNotif endpoint to create and manage room types and room amenities details and the OTA_HotelDescriptiveInfo endpoint to retrieve property details.

Risks using the Overlay mode

If you have to update a specific property detail, say adding a facility, you must send all the existing information in the Overlay mode along with the updated information. Using the OTA_HotelDescriptiveContentNotif endpoint in the Overlay mode introduces the risk of overwriting existing values if you fail to include all the existing information in the request.

What are the modernised APIs?

With the new APIs, Booking.com bundles a well-defined, and limited set of features within each modernised API allowing you greater flexibility. You can use each API to create, update and retrieve specific property information that you would otherwise manage using one OTA_HotelDescriptiveContentNotif endpoint.

This section contains a list of the new and simplified APIs, their benefits and additional information.

API Name Purpose Status
Property API Create and manage property details such as name, property category, physical location, check in/out time among others. Available.
Contacts API Create and manage property contact details. Available.
Facilities API Create and manage a property's facilities and room amenities. Available.
Property settings endpoint Set and manage feature opt-in, property flags and standard phrases/fine print. Available.
Room Details API Create and manage room types and room configurations including bedding. Soon to come.
Taxes & Fees API Set and manage VAT, taxes and fee details for both property and rooms. Soon to come.

Property API

Create and manage a property by providing only the basic required details.

The following table summarises the tasks, the HTTP method and the endpoints that the API supports.

Endpoint Task HTTP Method
property-api Create a property. POST
property-api Update/Overwrite existing property details. PATCH
property-api Retrieve property details. GET

Benefits of using the Property API

The following are the benefits of using the property-api:

  • Create or update a property's details such as name, property category, check in/out time and physical location without impacting other information.
  • Specify an external property ID while creating a property. This is useful while debugging technical issues if you cannot get property details through Booking.com generated property ID.
  • Create a property ID quickly by providing minimum information. Add the rest of the details later using other endpoints.
  • See an improved request and response body structure in Json.
  • Get familiar with the validation checks early.

For more details on the Property API, see Managing property details.

Difference in request parameters between HDCN and property-api

To see the difference in request parameters between the OTA_HotelDescriptiveContentNotif and property-api, see the Root parameter in HDCN column under the Request body parameters table.

What can you do with Property IDs?

Once you have created a property ID, you can use it to:

  • Add or update additional property details such as:
    • Property contact information
    • Facilities and room amenities
    • Room details including occupancy and bedding, and
    • Taxes and fees information
  • Retrieve property details either using the Property API or the OTA_HotelDescriptiveInfo endpoint.
  • Check whether a property is ready to be set to open and bookable.

Contacts API

Create and manage property contact information. You can create contact information for multiple contact types including those that are needed to make a property open and bookable.

The following table summarises the tasks, the HTTP method and the endpoints that the API supports.

Endpoint Task HTTP Method
contacts-api Create a contact. PUT
contacts-api Update/Overwrite an existing contact. PUT
contacts-api Delete a contact. PUT
contacts-api Retrieve contact details. GET

Benefits of using the Contacts API

The following are the benefits of using the contacts-api:

  • You can update any contact details including of types: General and Invoices when the property is open and bookable.
  • You can use the same contact details for multiple contact types. This reduces creating duplicate contacts for different purposes.
  • Get familiar with the validation checks early.
  • See an improved request and response body structure in Json.

For more details on the Contacts API, see Managing contact details.

Difference in request parameters between HDCN and contacts-api

To see the difference in request parameters between the OTA_HotelDescriptiveContentNotif and contacts-api, see the Root parameter in HDCN column under the Request body parameters table.

For all other APIs except property details, you need to specify a property ID

You need to specify a property ID to create contacts, room details, facilities & amenities or taxes & fees for a property and to set property settings.

Facilities API

Use the Facilities API to manage facilities at both the property and room-level.

Using the Facilities API, you can:

For more information, see the introduction to the Facilities API.

Managing property settings

Use the Property API's settings endpoint to manage settings at the property level like property's location coordinates, pets allowance, children policies and so on. For more information, see managing property settings.

Using modernised APIs along with OTA_HotelDescriptiveContentNotif

The following section lists the recommended approach when using either or both of the modernised APIs along with the OTA_HotelDescriptiveContentNotif (HDCN) endpoint.

Using Contacts API along with OTA_HotelDescriptiveContentNotif

When using Contacts API along with the OTA_HotelDescriptiveContentNotif endpoint, make sure to:

  • Omit the ContactInfos field from the OTA_HotelDescriptiveContentNotif endpoint call to retain the contact details managed using the Contacts API.
  • When you cannot use Contacts API due to some issues, make sure to send all the contact details using the OTA_HotelDescriptiveContentNotif endpoint to update the contacts.

Using Property Details API along with OTA_HotelDescriptiveContentNotif

When using Property Details API along with the OTA_HotelDescriptiveContentNotif endpoint, make sure to:

  • Omit the fields from the OTA_HotelDescriptiveContentNotif endpoint call to retain the information managed using the Property Details API.
  • When you cannot use the Property Details API due to some issues, you can use the OTA_HotelDescriptiveContentNotif endpoint to update the property details.
  • When using the Property Details API along with the OTA_HotelDescriptiveInfo endpoint to retrieve the property details, the contact of type:PhysicalLocation is created by default.

Using Property Details API, Contacts API along with OTA_HotelDescriptiveContentNotif

When using the OTA_HotelDescriptiveContentNotif endpoint along with the Contacts and Property Details APIs, make sure to:

  • Omit the ContactInfos and its child elements along with the parameters specified under Root Parameter in HDCN column in the Request body parameters table of Property Details API to retain the information managed by both the Contacts and Property Details API.
  • If you cannot use the Property Details API, you can continue using Contacts API as recommended in the Using Contacts API along with HDCN section.
    • Update the property details using the OTA_HotelDescriptiveContentNotif endpoint.
    • When updating the property's physical location contact, make sure to omit specifying the email field.
  • If you cannot use the Contacts API, you can continue using the Property Details API as recommended in the Using Property Details API along with HDCN section.
    • Use the OTA_HotelDescriptiveContentNotif endpoint to update the contact details.

Going Live

Before you go live with your API integration, you'll need to meet certain requirements. For more information, see Going Live.

Quick Actions

→ To create and manage a property, see the Property Details API.
→ To create and manage property contacts, see the Contacts API.
→ To create and manage property & room facilities, see the Facilities API.

Is this page helpful?    Yes   |    No