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 or the provided LEID then the API returns the existing properties’ ID so that you can add more room types or quantity or ask the property owner to update the existing property. For more information, see the OTA Error Code 850.
- In the case that you still wish to create the property, you can avoid the duplicate block by ensuring that the property name or address line is unique.

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 check-in details.	object	required	Specify 24-hour check-in by using `00:00` for both `from` and `until`.	>>>>> PolicyInfo.CheckInTime
	`from`	Specifies the earliest time a guest can check-in.	enumerated string	required	Accepted values follow the Booking.com Check-In / Check-Out Times format.
	`until`	Specifies the latest time when a guest can check-in.	enumerated string	optional	Accepted values follow the Booking.com Check-In / Check-Out Times format.
> `check_out`		Contains the check-out details.	object	optional	Specify 24-hour check-out by using `00:00` for both `from` and `until`.	>>>>> PolicyInfo.CheckOutTime
	`from`	Specifies the earliest time a guest can check-out.	enumerated string	optional	Accepted values follow the Booking.com Check-In / Check-Out Times format.
	`until`	Specifies the latest time when a guest can check-out.	enumerated string	required if `check_out` > `from` is specified	Accepted values follow the Booking.com Check-In / Check-Out Times format.
> `property_name`		Specifies the name of the property on Booking.com.	string	required	Does not support using CJK Unified Ideographs.	>> HotelDescriptiveContent.HotelName
> `property_category`		Specifies the property class type code.	integer	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.	array of enumerated strings	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.	integer	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: `0`–`5`. 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.	array of objects	optional	-	>>> ContactInfos `ContactProfileType`=`PhysicalLocation` to update physical address details using HDCN.
	`city_name`	Species the name of the city, town, or village.	string	required		>>> ContactInfos `ContactProfileType`=`PhysicalLocation` to update physical address details using HDCN.
	`address_line`	Species the full street name and number.	string	required	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		>> 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-21g4-4575-p94g-e76me888fwq4"
  }
}

Response body elements¶

The following table describes the response elements:

Element	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
- primary_language
- 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`}	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		>>>> 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 check-in details.	object	optional	Specify 24-hour check-in by using `00:00` for both `from` and `until`.	>>>>> PolicyInfo.CheckInTime
	`from`	Specifies the earliest time a guest can check-in.	enumerated string	optional
	`until`	Specifies the latest time when a guest can check-in. To clear the existing value, specify `null`.	enumerated string	optional
> `check_out`		Contains the check-out details.	object	optional	Specify 24-hour check-out by using `00:00` for both `from` and `until`.	>>>>> PolicyInfo.CheckOutTime
	`from`	Specifies the earliest time a guest can check-out. To clear the existing value, specify `null`.	enumerated string	optional	Specify 24-hour check-in by using `00:00-00:00`.
	`until`	Specifies the earliest time a guest can check-out.	enumerated string	optional		>> HotelDescriptiveContent.HotelName
> `property_name`		Specifies the name of the property on Booking.com.	string	optional	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
> `property_category`		Specifies the property class type code.	integer	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`.	array of enumerated strings	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.	integer	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.	string	optional	Accepts values: `0`–`5`. Half star increments are possible (e.g. `1.5`), but rarely used 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.	array of objects	optional	Note that updating `translations` fields only appends to or updates the existing values and does not delete translations that are omitted. 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	required		>>> ContactInfos `ContactProfileType`=`PhysicalLocation` to update physical address details using HDCN.
	`address_line`	Species the full street name and number.	string	required	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	If you want to (re)name a property, ensure the name follows Booking.com naming convention.	>> 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-h4742-9l08-2ew3-df4fd1f1166b"
  }
}

Response body elements¶

The following table describes the response elements:

Element	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`}	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. Note: Changes that may be immediately reflected via APIs or Extranet may take extra time to show up in our traveller facing products because the use of caches and data materlization.	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.

Is this page helpful? Yes | No