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.

Managing property details

Use the Property Details API (property-api) to create, update and retrieve property details.

Creating property details

POST
https://supply-xml.booking.com/property-api/properties

Use the property-api endpoint to create a property by specifying the property details such as name, property category, physical location, check in/out time and few others. After successfully processing the request, the endpoint returns a property ID.

API validations

This section contains any validations that the API enforces when processing the request.

Make sure your request meets the following validations, failing which the API returns an error:

  • The latitude and longitude values correspond to the country specified under physical_address ... >... country_code. Otherwise, the API returns Cannot create a hotel because UFI country (countryCode) is different from property country (countryCode).
  • For non-test properties: Make sure the property is not a duplicate of an existing property. Property Details API defines a duplicate as having an exact match on: property name, address line, position.latitude, and position.longitude.
    • If the API finds a duplicate property AND the property is associated with your account then the API returns the existing properties’ ID so that you can add more room types or quantity. For more information, see the OTA Error Code 850.

Property naming convention

When naming a property, ensure that the name:

  • Has a length between 3 and 255 characters.
  • Does not contain a phone number (or no more than five consecutive numbers).
  • Only contains letters, numbers, or the following symbols: ! # & ` ' " - ,
  • Is not all in uppercase.
  • Does not support CJK Unified Ideographs.

Usage of certain words are restricted as property names

If a name is rejected, the property name could contain a restricted word. If you do not think this is the case, reach out to our Connectivity Support.

Header parameter

The following table describes the elements you can add in the header:

Header Description Type Required/
Optional
Notes
Content-Type: application/json Specifies the expected content type. string required
Accept-Version Specify the version number to get the API functionality specific to that version. string optional Currently supports the value: 1.0

Request body parameters

The following table describes the elements you can add in the request body:

Element Attribute Description Type Required/
Optional
Notes Root parameter in HDCN
> position Contains the geographical coordinates of the property. object required - >>>> Position
latitude Specifies the latitude coordinates. double required - Latitude
longitude Specifies the longitude coordinates. double required - Longitude
> check_in Contains the Booking.com check in time code for the earliest time a guest can check in. enumerated string required You can specify both from and until. Specify 24-hour check-in by using 00:00 for both from and until. >>>>> PolicyInfo.CheckInTime
from Specify the Booking.com Check-in for the earliest time a guest can check in. enumerated string required Format: HH:MM. Specify 24-hour check-in by using 00:00 for both from and until.
until Specify the Booking.com Check-in until when guests can check in. enumerated string optional Format: HH:MM. Specify 24-hour check-in by using 00:00 for both from and until.
> check_out Contains the Booking.com check out time code for the earliest time a guest can check out. enumerated string optional You can specify both from and until. Specify 24-hour check-in by using 00:00-00:00. >>>>> PolicyInfo.CheckOutTime
from Specify the Booking.com Check-out for the earliest time a guest can check out. enumerated string optional Format: HH:MM. Specify 24-hour check-in by using 00:00-00:00.
until Specify the Booking.com Check-out until when guests can check out. enumerated string required if check_out > from is specified Format: HH:MM.
> property_name Specifies the name of the property on Booking.com. string required Required when creating a new property.
Does not support using CJK Unified Ideographs.
>> HotelDescriptiveContent.HotelName
> property_category Specifies the property class type code. enumerated string required For a list of supported property class type codes, see Property Class Type Code. >>>>> HotelCategory
> primary_language Specifies the language in which the property wants their Booking.com extranet content and communication such as emails, notifications, and so on. enumerated string optional Default: en-gb. For a list of supported language codes, see Booking.com Language Code table. LanguageCode
> languages_spoken Contains the language(s) spoken at the property. string optional Can contain multiple Language elements. For a list of supported language codes, see Booking.com Language Code table. >>> HotelInfo.Languages
> room_count Specifies the number of sellable units the property offers. integer required A "sellable unit" is the smallest possible space that a guest can book at the property. In a property with 200 rooms, each room is a sellable unit, and the value would be 200.
In a holiday home, guests must typically book the home in its entirety, making the value 1.
>>>>> GuestRoomInfo.Quantity
> floor_count Specifies the total number of floors in the building, excluding the underground floors. non-negative optional Max value can be 200. >>>> TotalNumberOfFloors.Number
> stars Specifies the number of stars. You can set star rating only for Hotel properties such as Hostel, Resort, Motel or Capsule Hotel among others and not Apartment or Villa and so on. integer optional Accepts values: 05.
Starting from 1, accepts values in increments of .5.
Some countries don't use star ratings.
To see whether your property belongs to a Hotel property type, see the property class type table.
>>> AffiliationInfo > Awards > Award.Rating
> target Specifies whether it is a test or production-ready property. enumerated string required Accepts the following values:
- test
- production
> OTA_HotelDescriptiveContentNotif.Target
> provider_property_id Specifies a custom property ID. string optional Recommended for new properties. For example, the provider's internal ID.
Can contain a maximum of 16 characters.
>>> HotelInfo.ID
> currency_code Specifies the Booking.com defined currency for the property. enumerated string optional In select countries a currency other than the default can be selected. For more details see the information the currency documentation CurrencyCode
> physical_address Contains the property's physical address. object required -
city_name Species the name of the city, town, or village. string required Does not support using CJK Unified Ideographs. >>> ContactInfos
ContactProfileType=PhysicalLocation to update physical address details using HDCN.
country_code Species the two-letter country code. enumerated string required For more information on how to retrieve the country code details, see xml/countries endpoint. >>> ContactInfos
ContactProfileType=PhysicalLocation to update physical address details using HDCN.
postal_code Specifies the postal/zip code. string optional Make sure the zip code (postal_code) is relevant to the country specified in the country_code. >>> ContactInfos
ContactProfileType=PhysicalLocation to update physical address details using HDCN.
address_line Species the full street name and number. string required Does not support using CJK Unified Ideographs.
Should not contain abbreviations (such as "Rd." for "Road") and should not exceed 255 characters.
>>> ContactInfos
ContactProfileType=PhysicalLocation to update physical address details using HDCN.
display_address Specifies whether to hide the full address details from the guest. boolean optional - true : Shows the full address to the guest.
- false : Hides the full address from the guest.
>>> ContactInfos > HiddenAddress > ShouldHideAddress
ContactProfileType=PhysicalLocation to update physical address details using HDCN.
> translations Specifies the non-English translations of the physical address. object optional - >>> ContactInfos
ContactProfileType=PhysicalLocation to update physical address details using HDCN.
city_name Species the name of the city, town, or village. string required Does not support using CJK Unified Ideographs. >>> ContactInfos
ContactProfileType=PhysicalLocation to update physical address details using HDCN.
address_line Species the full street name and number. string required Does not support using CJK Unified Ideographs.
Should not contain abbreviations (such as "Rd." for "Road") and should not exceed 255 characters.
>>> ContactInfos
ContactProfileType=PhysicalLocation to update physical address details using HDCN.
language_code Species the Booking.com Language code for the address details. enumerated string required Used for non-English translations. For a list of supported language codes, see Booking.com Language Code table.
property_name Specifies the non-English name of the property on Booking.com. enumerated string required Does not support using CJK Unified Ideographs. >> HotelDescriptiveContent.HotelName
> legal_entity_id Specifies the ID of the legal entity to which the property belongs. integer required Only allowed for new properties. CompanyName > Code

Request body

The following is a request body example:

{
  "position": {
    "latitude": 52.388418,
    "longitude": 4.619941
  },
  "check_in": {
    "from": "12:30"
  },
  "check_out": {
    "from": "10:00",
    "until": "10:30"
  },
  "property_name": "Floating hotel",
  "property_category": 30,
  "primary_language": "en-gb",
  "languages_spoken": [
    "en-gb",
    "nl",
    "ms"
  ],
  "room_count": 8,
  "floor_count": 1,
  "provider_property_id": "flotella003",
  "stars": "4",
  "target": "test",
  "physical_address": {
    "city_name": "Overveen",
    "country_code": "NL",
    "postal_code": "2051",
    "address_line": "Zandvoort",
    "display_address": true
  },
  "translations": [
    {
      "city_name": "Overveen",
      "address_line": "Zandvoort",
      "language_code": "es",
      "property_name": "Floating hotel"
    }
  ],
  "legal_entity_id": "78775"
}

Response body

The following is a response body example:

{
  "data": {
    "property_id": 10664256
  },
  "warnings": [],
  "meta": {
    "ruid": "08240512-87h6-4575-p94g-e76me888fwq4"
  }
}

Response body elements

The following table describes the response elements:

Element Attribute Description Type Notes
data Root element object
> property_id Specifies the property ID that was created or modified. string -
warnings Contains any warnings in the response. object -
meta Contains metadata information about the response. object -
> ruid Specifies the unique request ID. string You can share this ID with Booking.com customer support when you run into an issue. This can help in understanding what went wrong.

Updating property details

PATCH
https://supply-xml.booking.com/property-api/properties/{propertyID}

Use the PATCH property-api endpoint along with the property ID as a path parameter to update the property details. All request parameters are optional. You can specify only the parameters that you want to change. Several request parameters can be unset by passing null as the value. This is reiterated in the respective parameter's description.

API validations

This section contains any validations that the API enforces when processing the request.

Make sure your request meets the following validations, failing which the API returns an error:

  • Cannot update a property if it is in one of the following statuses:
    • XML: Ready to check
    • XML: Ready to open
    • Closed Post Legal
    • Closed forever
    • XML: Hotel is Duplicate
  • Can update the following fields only if the property is in Test Hotel or XML: Being built status.
    • currency_code
    • position
      • latitude
      • longitude
    • physical_address
      • address_line
      • city_name
      • country_code
      • postal_code
      • primary_language

Header parameter

The following table describes the elements you can add in the header:

Header Description Type Required/
Optional
Notes
Accept-Version Specify the version number to get the API functionality specific to that version. string optional Currently supports the value: 1.0

Path parameter

The following table describes the elements you can add in the path:

Value Description Type Required/
Optional
Notes
{property ID} value Specify the unique ID of the property to update its details. integer required

Request body parameters

The following table describes the elements you can add in the request body:

Element Attribute Description Type Required/
Optional
Notes Name in HDCN
> position Contains the geographical coordinates of the property. object optional You can update this and its child elements only if the property is in status: Test Hotel or XML: Being built. >>>> Position
latitude Specifies the latitude coordinates. double optional Booking.com recommends that you set both latitude and longitude values in the same request. Latitude
longitude Specifies the longitude coordinates. double optional Booking.com recommends that you set both latitude and longitude values in the same request. Longitude
> check_in Contains the Booking.com check in time code for the earliest time a guest can check in. enumerated string optional You can specify both from and until. Specify 24-hour check-in by using 00:00 for both from and until. >>>>> PolicyInfo.CheckInTime
from Specify the Booking.com Check-in for the earliest time a guest can check in. enumerated string optional Format: HH:MM. Specify 24-hour check-in by using 00:00 for both from and until.
until Specify the Booking.com Check-in until when guests can check in.
To clear the existing value, specify null.
enumerated string optional Format: HH:MM. Specify 24-hour check-in by using 00:00 for both from and until.
> check_out Contains the Booking.com check out time code for the earliest time a guest can check out. enumerated string optional You can specify both from and until. Specify 24-hour check-in by using 00:00-00:00. >>>>> PolicyInfo.CheckOutTime
from Specify the Booking.com Check-out for the earliest time a guest can check out.
To clear the existing value, specify null.
enumerated string optional Format: HH:MM. Specify 24-hour check-in by using 00:00-00:00.
until Specify the Booking.com Check-out until when guests can check out. enumerated string optional If you want to (re)name a property, ensure the name follows Booking.com naming convention. >> HotelDescriptiveContent.HotelName
> property_name Specifies the name of the property on Booking.com. string optional Does not support using CJK Unified Ideographs. >> HotelDescriptiveContent.HotelName
> property_category Specifies the property class type code. enumerated string optional For a list of supported property class type codes, see Property Class Type Code. >>>>> HotelCategory
> primary_language Specifies the language in which the property wants their Booking.com extranet content and communication such as emails, notifications, and so on. enumerated string optional For a list of supported language codes, see Booking.com Language Code table.
Only possible to update if the property is in status: Test Hotel or XML: Being built.
LanguageCode
> languages_spoken Contains the language(s) spoken at the property.
To clear the existing value, specify null.
string optional Can contain multiple Language elements. For a list of supported language codes, see Booking.com Language Code table. >>> HotelInfo.Languages
> room_count Specifies the number of sellable units the property offers. integer optional A "sellable unit" is the smallest possible space that a guest can book at the property. In a property with 200 rooms, each room is a sellable unit, and the value would be 200.
In a holiday home, guests must typically book the home in its entirety, making the value 1.
>>>>> GuestRoomInfo.Quantity
> floor_count Specifies the total number of floors in the building, excluding the underground floors. non-negative optional Maximum value can be 200. >>>> TotalNumberOfFloors.Number
> stars Specifies the number of stars. You can set star rating only for Hotel properties such as Hostel, Resort, Motel or Capsule Hotel among others and not Apartment or Villa and so on. integer optional Accepts values: 05.
Starting from 1, accepts values in increments of .5.
Some countries don't use star ratings.
To see whether your property belongs to a Hotel property type, see the property class type table.
>>> AffiliationInfo > Awards > Award.Rating
> provider_property_id Specifies a custom property ID.
To clear the existing value, specify null.
string optional Can contain a maximum of 16 characters. >>> HotelInfo.ID
> currency_code Specifies the Booking.com defined currency for the property. enumerated string optional In select countries a currency other than the default can be selected. For more details see the information the currency documentation CurrencyCode
> physical_address Contains the property's physical address. object optional You can update this and its child elements only if the property is in status: Test Hotel or XML: Being built.
Booking.com recommends that you set all address details in a single request.
city_name Species the name of the city, town, or village. string optional Does not support using CJK Unified Ideographs. >>> ContactInfos
ContactProfileType=PhysicalLocation to update physical address details using HDCN.
country_code Species the two-letter country code. enumerated string optional For more information on how to retrieve the country code details, see xml/countries endpoint. >>> ContactInfos
ContactProfileType=PhysicalLocation to update physical address details using HDCN.
postal_code Specifies the postal/zip code. string optional - >>> ContactInfos
address_line Species the full street name and number. string optional Does not support using CJK Unified Ideographs.
Should not contain abbreviations (such as "Rd." for "Road") and should not exceed 255 characters.
>>> ContactInfos
ContactProfileType=PhysicalLocation to update physical address details using HDCN.
display_address Specifies whether to hide the full address details from the guest.
Recommended to also set address_line
boolean optional - true : Shows the full address to the guest.
- false : Hides the full address from the guest.
>>> ContactInfos > HiddenAddress > ShouldHideAddress
ContactProfileType=PhysicalLocation to update physical address details using HDCN.
> translations Specifies the non-English translations of the physical address and property name. object optional Note that updating translations fields only appends to existing values and does not overwrite them. For example, when you pass translations while creating a property (POST) for the languages es and fr and then update the translations using PATCH with translations for fr and de, then the property would have translations for es, fr (updated), and de. >>> ContactInfos
ContactProfileType=PhysicalLocation to update physical address details using HDCN.
city_name Species the name of the city, town, or village. string optional Does not support using CJK Unified Ideographs. >>> ContactInfos
ContactProfileType=PhysicalLocation to update physical address details using HDCN.
address_line Species the full street name and number. string optional Does not support using CJK Unified Ideographs.
Should not contain abbreviations (such as "Rd." for "Road") and should not exceed 255 characters.
>>> ContactInfos
ContactProfileType=PhysicalLocation to update physical address details using HDCN.
language_code Species the Booking.com Language code for the address details. enumerated string optional Used for non-English translations. For a list of supported language codes, see Booking.com Language Code table.
property_name Specifies the non-English name of the property on Booking.com. enumerated string required If you want to (re)name a property, ensure the name follows Booking.com naming convention.
Does not support using CJK Unified Ideographs.
>> HotelDescriptiveContent.HotelName

Request body

The following is a request body example:

{
  "check_in": {
    "from": "12:00"
  },
  "check_out": {
    "from": "09:30"
  },
  "languages_spoken": [
    "en-gb",
    "nl",
    "ms",
    "de",
    "fr",
    "pl"
  ]
}

Response body

{
  "data": {
    "property_id": 10664256
  },
  "warnings": [],
  "meta": {
    "ruid": "1c9bff15-f321-9l08-8rw4-df4fd1f1166b"
  }
}

Response body elements

The following table describes the response elements:

Element Attribute Description Type Notes
data Root element object
> property_id Specifies the property ID that was created or modified. string -
warnings Contains any warnings in the response. object -
meta Contains metadata information about the response. object -
> ruid Specifies the unique request ID. string You can share this ID with Booking.com customer support when you run into an issue. This can help in understanding what went wrong.

Retrieving property details

GET
https://supply-xml.booking.com/property-api/properties/{propertyID}

Use the GET property-api endpoint along with the property ID to retrieve the property details.

Header parameter

The following table describes the elements you can add in the header:

Header Description Type Required/
Optional
Notes
Accept-Version Specify the version number to get the API functionality specific to that version. string optional Currently supports the value: 1.0

Path parameter

The following table describes the elements you can add in the path:

Value Description Type Required/
Optional
Notes
{property ID} value Specify the unique ID of the property to retrieve its details. integer required

Response body

{
  "data": {
    "position": {
      "latitude": 52.388418,
      "longitude": 4.619941
    },
    "check_in": {
      "from": "12:00"
    },
    "check_out": {
      "from": "09:30",
      "until": "10:30"
    },
    "property_name": "Floating hotel",
    "property_category": 30,
    "primary_language": "en-gb",
    "languages_spoken": [
      "en-gb",
      "ms",
      "nl"
    ],
    "room_count": 8,
    "floor_count": 1,
    "provider_property_id": "flotella003",
    "stars": "4",
    "target": "test",
    "currency_code": "EUR",
    "property_id": 10664256,
    "status": "Test Hotel",
    "physical_address": {
      "city_name": "Overveen",
      "country_code": "nl",
      "postal_code": "2051",
      "address_line": "Zandvoort",
      "display_address": true
    },
    "translations": [
      {
        "city_name": "Overveen",
        "address_line": "Zandvoort",
        "language_code": "es",
        "property_name": "Floating hotel"
      }
    ],
    "legal_entity_id": "78775"
  },
  "meta": {
    "ruid": "2ccea0cc-9a0b-4179-9c20-9436e50cc070"
  }
}

Response body elements

The following table describes the response elements:

Element Attribute Description Type Notes
data Root element object
> position Contains the geographical coordinates of the property. object
latitude Specifies the latitude coordinates. double -
longitude Specifies the longitude coordinates. double -
> check_in Contains the Booking.com check in time code for the earliest time a guest can check in. string A value of 00:00 for both from and until means the property accepts 24-hour check in.
from Specifies the Booking.com check in for the earliest time a guest can check in. enumerated string -
until Specifies the Booking.com check in until when guests can check in. enumerated string -
> check_out Contains the Booking.com check out time code for the earliest time a guest can check out. string A value of 00:00 for both from and until means the property accepts 24-hour check out.
from Specifies the Booking.com check out for the earliest time a guest can check out. enumerated string -
until Specifies the Booking.com check out until when guests can check out. enumerated string -
> property_name Specifies the name of the property on Booking.com. string -
> property_category Specifies the property class type code. enumerated string -
> primary_language Specifies the language in which the property wants their Booking.com extranet content and communication. enumerated string -
> languages_spoken Contains the language(s) spoken at the property. string Can contain multiple Language elements.
> room_count Specifies the number of sellable units the property offers. integer -
> floor_count Specifies the total number of floors in the building. integer -
> target Specifies whether it is a test or production-ready property. enumerated string Contains one of the following values:
- test
- production
> stars Specifies the number of stars. integer -
> provider_property_id Specifies a custom property ID. string -
>> currency_code Specifies the Booking.com defined currency for the property. enumerated string -
> property_id Specifies the Booking.com generated property ID. string -
>> status Specifies the property status. enumerated string -
>> url [Only available when a property is in open and bookable status] Specifies the property's URL. string -
> physical_address Contains the property's physical address. object -
>> city_name Specifies the name of the city, town, or village. string -
>> country_code Specifies the two-letter country code. enumerated string -
>> postal_code Specifies the postal/zip code. string -
>> address_line Specifies the full street name and number. string -
>>> city_name Specifies the name of the city, town, or village. string -
>>> address_line Specifies the full street name and number. string -
>>> language_code Specifies the Booking.com Language code for the address details. enumerated string -
>>> property_name Specifies the non-English name of the property on Booking.com. enumerated string -
>> display_address Specifies whether to hide the address details. boolean - true : Shows the full address to the guest.
- false : Hides the full address from the guest.
> translations Specifies the non-English translations of the physical address object -
> legal_entity_id Specifies the ID of the legal entity to which the property belongs. integer -
warnings Contains any warnings in the response. object -
meta Contains metadata information about the response. object -
> ruid Specifies the unique request ID. string You can share this ID with Booking.com customer support when you run into an issue. This can help in understanding what went wrong.

Quick Actions


→ To create and manage property contacts, see Contacts API.