Managing licences
The Licences API enables you to present the relevant licence requirements elements to your connected properties. You can do that by following these high-level steps:
- Retrieve licence requirements for a property.
- Present the appropriate licence requirements to the property.
- Send the licence information of a property or room type.
- Retrieve existing licence information per property or room type to verify success.
Retrieving licence requirements
You can retrieve the same licence requirements data in two ways depending on the information that is available to you:
- If your property has a known Booking.com property ID, retrieve by property ID.
- If your property does not yet have a Booking.com ID, retrieve by location data.
Retrieving licence requirements by property ID
GET
https://supply-xml.booking.com/licenses/rules/properties/{property_id}
Query parameters
The following table describes the required query elements for this endpoint:
Parameter | Description | Type | Required/Optional | Notes |
---|---|---|---|---|
property_id | Specifies the property ID for which you want to retrieve licence requirements. | string | required |
Retrieving licence requirements without property ID
GET
https://supply-xml.booking.com/licenses/rules
Query parameters
The following table describes the required query elements for this endpoint:
Parameter | Description | Type | Required/Optional | Notes |
---|---|---|---|---|
lat | Specifies the latitude of the property. | float | required | |
long | Specifies the longitude of the property. | float | required | |
country_code | Specifies the country code of the property. | string | required | To retrieve a list of the available country codes, see retrieving country codes |
property_type_id | Specifies the property type id. | int | required | To retrieve a list of valid property types, see Property Class Type Codes. |
Example call with query parameters
GET
https://supply-xml.booking.com/licenses/rules?lat={latitude}&long={longitude}&country_code={country_code}&property_type_id={property_type_id}
Licence requirements response
These endpoints enable you to retrieve the regional licence requirements for a property, which you need to:
- Present the licence requirements to a property within your user interface.
- Send the licence information to Booking.com.
The minimal information you need to set up the licence requirements is:
- Whether the licence requirements are on the property or room level (
level
): It is either property or room type level, never both. - The possible
variants
of a licence and their ID (id
): This refers to possible variations of the licence requirements within a region. You must provide all possibilities to your properties. - All the licence requirements with their corresponding values.
Labels for licence variants
We have introduced an additional field to our licence requirements data structure: label
. The label
response element contains a short human-readable description of a licence variant.
Response body example
The following is a successful response body example for property-level licence requirements:
{
"data": {
"variants": [
{
"name": "japan_new_minpaku_shinpo_license_v1",
"label": "'Minpaku Shinpo' license (民泊新法)",
"id": 304,
"content": [
{
"format": "^(?!M123456789$)M[0-9]{9}$",
"name": "number",
"required": true,
"dataType": "string"
},
{
"name": "Japan_license_holder_name",
"required": true,
"dataType": "string"
},
{
"name": "issue_date",
"required": false,
"dataType": "date"
},
{
"name": "certificate_copy",
"required": false,
"dataType": "file"
}
]
},
{
"name": "japan_new_minpaku_tokku_license_v1",
"label": "'Minpaku Tokku' license( 特区民泊 )",
"id": 305,
"content": [
{
"name": "number",
"required": true,
"dataType": "string"
},
{
"name": "Japan_license_holder_name",
"required": true,
"dataType": "string"
},
{
"name": "issue_date",
"required": false,
"dataType": "date"
},
{
"name": "certificate_copy",
"required": false,
"dataType": "file"
}
]
},
{
"name": "japan_new_ryokan_license_v1",
"label": "Ryokan license ( 旅館業法 )",
"id": 306,
"content": [
{
"name": "number",
"required": true,
"dataType": "string"
},
{
"name": "Japan_license_holder_name",
"required": true,
"dataType": "string"
},
{
"name": "issue_date",
"required": false,
"dataType": "date"
},
{
"name": "certificate_copy",
"required": false,
"dataType": "file"
}
]
}
],
"name": "japan_new",
"id": 201,
"active": true,
"level": "room"
},
"meta": {
"ruid": "UmFuZG9tSVYkc2RlIyh9Ya3WbzHWV9oINucqsqdROrvtS9rIpvdyAOxIbeRs6frXvuFyeZSyZQqQwMdjjl6rcNDDXD3GD92hsDQb660wuG3S8pxmcUPe5w=="
},
"warnings": [],
"errors": []
}
The following is a successful response body example for room-level licence requirements:
{
"meta": {
"ruid": "UmFuZG9tSVYkc2RlIyh9YRVJicqEeLs1OoMxTc7Y+FITilxK+BbS8riILs03PNInVTmid8OsNX07muIUr/n1NTOnFG49M6sI8EVF3JITE0bIUe9mBnraMQ=="
},
"warnings": [],
"data": {
"variants": [
{
"id": 22,
"name": "paris_v1",
"content": [
{
"possibleValues": [
"private_person",
"professional_company"
],
"dataType": "string",
"required": true,
"name": "management_type"
},
{
"name": "number",
"required": true,
"dataType": "string",
"format": "^[0-9]{13}$"
},
{
"dataType": "string",
"possibleValues": [
"primary",
"secondary",
"other"
],
"required": true,
"name": "residence_type"
}
]
}
],
"name": "paris",
"id": 17,
"level": "room",
"active": true
},
"errors": []
}
Response body elements
The following table describes the response elements:
Element | Description | Type | Notes |
---|---|---|---|
data | Contains the response data. | object | |
: variants | Contains all the possible variants of licence requirements in the region of the specified property. | array | |
:: id | Specifies the unique ID of the licence requirements variant. | integer | |
:: name | Specifies the name of the licence requirements variant. | string | |
:: label | Short human-readable description of a licence variant. | string | |
:: content | Contains the mandatory and optional elements that you need to set up licence requirements. | array | |
::: required | Indicates whether the licence element is mandatory | boolean | |
::: dataType | Specifies the data type of the licence element. | string | |
::: name | Specifies the name of the licence element. | string | |
::: format | Specifies the format in which the licence element value should appear. | string | |
::: possibleValues | Contains the possible values for the licence element it is associated with. | array | |
: id | Specifies the ID of the main licence. | integer | |
: active | Indicates whether the licence requirements are active or not. | boolean | You can ignore this element. |
: level | Specifies whether the licence requirements are on the property or room level. | string | |
: name | Specifies the name of the property's region in which the licence requirements apply. | string | |
meta | Contains the meta data that comes with the response. | object | |
: ruid | Specifies the unique ID of the request. | string | You can send this ID to Booking.com customer support if you run into an issue. This can help to understand what went wrong. |
warnings | Contains potential warnings. These can help you improve your requests. | array | |
errors | Contains potential errors. These can help you understand what went wrong with your request. | array |
Managing property-level licences
This section describes all the possible actions related to managing licences for a property through the Licences API.
Quick actions:
- Sending the licence requirements of a specific property.
- Retrieving the existing licence information of a specific property.
Sending licence information of a property
PUT https://supply-xml.booking.com/licenses/data/properties/{property_id}
The PUT /data/properties/{property_id}
request enables you to send the appropriate licence information of a property to Booking.com.
Path parameters
The following table describes the required path elements for this endpoint:
Parameter | Description | Type | Required/Optional | Notes |
---|---|---|---|---|
property_id | Specifies the property ID for which you want to send the licence information. | string | required |
Request body parameters
Parameter | Description | Type | Required/Optional | Notes |
---|---|---|---|---|
data | Contains the request body elements. | object | required | |
: contentData | Contains the licence requirements in the form of name and value pairs. | array | required | |
:: name | Specifies the name of the licence requirements element. | string | required | You can have multiple licence elements (with corresponding values). This varies depending on the property region. |
:: label | Specifies a short human-readable description of a licence variant. | string | required | You can have multiple licence elements (with corresponding values). This varies depending on the property region. |
:: value | Specifies the value corresponding to the name of the licence requirements element. | string | required | You must follow the data type and format specified by dataType and format respectively. |
: variantId | Specifies the ID of the licence variant, which is applicable to the specified property. | string | required |
Request body example
{
"data": {
"contentData": [
{
"name": "issue_date",
"value": "2020-05-01"
},
{
"name": "number",
"value": "A123456789"
}
],
"variantId": 39
}
}
Response body example
The following is a successful response body example:
{
"meta": {
"ruid": "UmFuZG9tSVYkc2RlIyh9Ya3WbzHWV9oIS2wUEwGUyzk1LtPWGnHLXF8LvpWuxaR6kqjAJV6MUfTVZB/XTjfzyIYDmxbUfGao5aDqJEed4LVH8of5dFKEQw=="
},
"data": {
"success": 1
},
"errors": [],
"warnings": []
}
Response body elements
The following table describes the response elements:
Element | Description | Type | Notes |
---|---|---|---|
data | Contains the response data. | object | |
: success | Indicates whether the request was successful. | boolean | |
meta | Contains the meta data that comes with the response. | object | |
: ruid | Specifies the unique ID of the request. | string | You can send this ID to Booking.com customer support if you run into an issue. This can help to understand what went wrong. |
warnings | Contains potential warnings. These can help you improve your requests. | array | |
errors | Contains potential errors. These can help you understand what went wrong with your request. | array |
Retrieving property licence information
GET
https://supply-xml.booking.com/licenses/data/properties/{property_id}
The GET /data/properties/{property_id}
request enables you to retrieve the existing licence information for a property by specifying their id.
Path parameters
The following table describes the required path elements for this endpoint:
Parameter | Description | Type | Required/Optional | Notes |
---|---|---|---|---|
property_id | Specifies the property ID for which you want to retrieve licence information. | string | required |
Response body example
The following is a successful response body example:
{
"warnings": [],
"meta": {
"ruid": "UmFuZG9tSVYkc2RlIyh9YZSPD851yI7p72LK9h7sjamfHUFYIolonBz1VH3T3AnQLd321In8d74fyp5D7Kc+D5dghtTmY0+ap879E5pefN+kD+1KBSqpYQ=="
},
"errors": [],
"data": {
"variantId": 39,
"contentData": [
{
"name": "number",
"value": "A123456789",
"dataType": "string"
},
{
"value": "2020-05-01",
"name": "issue_date",
"dataType": "date"
}
]
}
}
Response body elements
The following table describes the response elements:
Element | Description | Type | Notes |
---|---|---|---|
data | Contains the response data. | object | |
: variantId | Specifies the ID of the licence variant. | integer | |
: contentData | Contains the licence elements in the form of name and value pairs. | array | required |
:: name | Specifies the name of the licence element. | string | required |
:: label | Specifies a short human-readable description of a licence variant. | string | required |
:: value | Specifies the value corresponding to the licence element name. | string | required |
meta | Contains the meta data that comes with the response. | object | |
: ruid | Specifies the unique ID of the request. | string | You can send this ID to Booking.com customer support if you run into an issue. This can help to understand what went wrong. |
warnings | Contains potential warnings. These can help you improve your requests. | array | |
errors | Contains potential errors. These can help you understand what went wrong with your request. | array |
Managing room-type licences
This section describes all the possible actions related to managing licences for a room type through the Licences API.
Quick actions:
- Sending the licence information of a specific room type.
- Retrieving the existing licence information of a specific room type.
Sending licence information of a room type
PUT
https://supply-xml.booking.com/licenses/data/properties/{property_id}/rooms/{room_id}
The PUT /data/properties/{property_id}/rooms/{room_id}
request enables you to send the appropriate licence information of a room type to Booking.com.
Path parameters
The following table describes the required path elements for this endpoint:
Parameter | Description | Type | Required/Optional | Notes |
---|---|---|---|---|
property_id | Specifies the property ID for which you want to send the room-level licence information. | string | required | |
room_id | Specifies the room type ID for which you want to send the licence information. | string | required |
Request body parameters
Parameter | Description | Type | Required/Optional | Notes |
---|---|---|---|---|
data | Contains the request body elements. | object | required | |
: contentData | Contains the licence requirements in the form of name and value pairs. | array | required | |
:: name | Specifies the name of the licence requirements element. | string | required | You can have multiple licence elements (with corresponding values). This varies depending on the property region. |
:: label | Specifies a short human-readable description of a licence variant. | string | required | You can have multiple licence elements (with corresponding values). This varies depending on the property region. |
:: value | Specifies the value corresponding to the name of the licence requirements element. | string | required | You must follow the data type and format specified by dataType and format respectively. |
: variantId | Specifies the ID of the licence variant, which is applicable to the specified room type. | string | required |
Request body example
{
"data": {
"contentData": [
{
"name": "management_type",
"value": "private_person"
},
{
"name": "residence_type",
"value": "primary"
},
{
"name": "number",
"value": "1234567890123"
}
],
"variantId": 22
}
}
Response body example
The following is a successful response body example:
{
"meta": {
"ruid": "UmFuZG9tSVYkc2RlIyh9Ya951VT0vsBCAFA/RugA75pfw5rz5ytfk2B7PgcnO+tBltJb/hDGmUcAAzpmaLpbmMD6WMO7gYxQ5r52nuzjm5XfyVH8ICbwcg=="
},
"data": {
"success": 1
},
"errors": [],
"warnings": []
}
Response body elements
The following table describes the response elements:
Element | Description | Type | Notes |
---|---|---|---|
data | Contains the response data. | object | |
: success | Indicates whether the request was successful. | boolean | |
meta | Contains the meta data that comes with the response. | object | |
: ruid | Specifies the unique ID of the request. | string | You can send this ID to Booking.com customer support if you run into an issue. This can help to understand what went wrong. |
warnings | Contains potential warnings. These can help you improve your requests. | array | |
errors | Contains potential errors. These can help you understand what went wrong with your request. | array |
Retrieving room type licence information
GET
https://supply-xml.booking.com/licenses/data/properties/{property_id}/rooms/{room_id}
The GET /data/properties/{property_id}/rooms/{room_id}
request enables you to retrieve the licence information of a room type.
Path parameters
The following table describes the required query elements for this endpoint:
Parameter | Description | Type | Required/Optional | Notes |
---|---|---|---|---|
property_id | Specifies the property ID for which you want to retrieve the room-level licence information. | string | required | |
room_id | Specifies the room type ID for which you want to retrieve licence information. | string | required |
Response body example
The following is a successful response body example:
{
"meta": {
"ruid": "UmFuZG9tSVYkc2RlIyh9YXTBNY4IOVJhfZ05YX5/i3BeIsA5ZVO6ajB+IPq4p7oawQeL7vr4M4BqBKHR0dtOQKlLOraXGARBH8Qz+5PgsKoYY7TOoAwi7g=="
},
"warnings": [],
"data": {
"contentData": [
{
"dataType": "string",
"name": "number",
"value": "1234567890123"
},
{
"value": "private_person",
"name": "management_type",
"dataType": "string"
},
{
"dataType": "string",
"name": "residence_type",
"value": "primary"
}
],
"variantId": 22
},
"errors": []
}
Response body elements
The following table describes the response elements:
Element | Description | Type | Notes |
---|---|---|---|
data | Contains the response data. | object | |
: variantId | Specifies the ID of the licence variant. | integer | |
: contentData | Contains the licence elements in the form of name and value pairs. | array | required |
:: name | Specifies the name of the licence element. | string | required |
:: value | Specifies a short human-readable description of a licence variant. | string | required |
:: value | Specifies the value corresponding to the licence element name. | string | required |
meta | Contains the meta data that comes with the response. | object | |
: ruid | Specifies the unique ID of the request. | string | You can send this ID to Booking.com customer support if you run into an issue. This can help to understand what went wrong. |
warnings | Contains potential warnings. These can help you improve your requests. | array | |
errors | Contains potential errors. These can help you understand what went wrong with your request. | array |
Managing licence file
For some regions and countries, you must provide a licence file to manage your licence requirements. This section explains how to upload and reference a licence file.
What are licence files?
License files are official documents (certificates, licenses, etc.) required in certain locations. You need to submit a license file if your property is located in:
- Quebec (province) and
- Japan - all property types to provide a copy of the licence.
How does it work?
Follow these two steps to manage license files:
Step 1: Upload a licence file using the /licenses/data/properties/{property_ID}/file
endpoint covered in Uploading property-level licence file section. The endpoint returns a UUID that uniquely identifies your licence file.
Step 2: Reference this UUID in the "name":"file"
parameter under Licence Content Data (contentData) in your request body. For more information, see Referencing uploaded licence file.
Note: You can only use the file reference for the same property_ID
it was generated for.
Uploading a licence file
You can upload a file to a specific property using the file upload endpoint. This endpoint accepts a single file per request and supports the following file formats:
- .jpg
- .jpeg
- .png or
POST
https://supply-xml.booking.com/licenses/data/properties/{property_ID}/file
Header parameters
The following table describes the elements you can add in the header:
Header | Description | Type | Required/ Optional | Notes |
---|---|---|---|---|
Authorization | Specifies the access token. | string | Required | |
Content-Type: | Specifies the expected content type. | string | Required | Depending on the file type, you can use the following values: - image/jpeg - image/png - application/pdf |
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 check or update state. | integer | Required |
Request body
This endpoint accepts multipart/form-data with a single file field:
file
Request body structure
The request uses multipart/form-data
encoding:
--boundary
Content-Disposition: form-data; name="file"; filename="example.pdf"
Content-Type: application/pdf
<binary_file_data>
--boundary--
Example request with a PDF file
curl --location 'https://supply-xml.booking.com/licenses/data/properties/13186624/file' \
--form 'file=@"/path/to/licence_file.pdf"'
Example request with an image file
curl --location ''https://supply-xml.booking.com/licenses/data/properties/13186624/file' \
--form 'file=@"/path/to/licence_file-jpg-example.jpg"'
Response body example
The following is a successful response body example for a file upload:
{
"data": {
"uuid": "c46d8ef8-c9b9-4140-aa07-903cec2e5e97"
},
"warnings": [],
"errors": [],
"meta": {
"ruid": "bb6adb3b-1918-46ab-9b61-45bce39f8e7f"
}
}
Response body elements
The following table describes the response elements:
Element | Description | Type | Notes |
---|---|---|---|
data | Contains the response data. | object | |
: success | Indicates whether the request was successful. | boolean | |
meta | Contains the meta data that comes with the response. | object | |
: ruid | Specifies the unique ID of the request. | string | You can send this ID to Booking.com customer support if you run into an issue. This can help to understand what went wrong. |
warnings | Contains potential warnings. These can help you improve your requests. | array | |
errors | Contains potential errors. These can help you understand what went wrong with your request. | array |
Retrieving licence file copy
Use the GET
method to retrieve a licence file.
GET
https://supply-xml.booking.com/licenses/data/properties/{property_ID}/file/{uuid}
Path parameters
The following table describes the required path elements for this endpoint:
Parameter | Description | Type | Required/Optional | Notes |
---|---|---|---|---|
property_ID | Specifies the property ID for which you want to send the licence information. | string | required | |
uuid | Specifies the UUID of the uploaded licence file. | string | required |
Header parameter
The following table describes the elements you can add in the header:
Header | Description | Type | Required/ Optional | Notes |
---|---|---|---|---|
Authorization | Specifies the access token. | string | Required |
Response body
The response to this endpoint is served as application/octet-stream
(a binary file).
Response headers
Content-Disposition: attachment; filename="example.pdf"
Content-Encoding: identity
Content-Type
application/octet-stream
Referencing uploaded licence file
After uploading a licence file, use the returned UUID to reference it in subsequent API calls.
The UUID returned in the upload response:
- Uniquely identifies the uploaded file
- Can be used to attach the uploaded file to a specific licence (Licence Data).
- Allows you to retrieve the file using GET endpoint
The UUID format follows the standard UUID v4 specification and remains constant for the lifetime of the uploaded file.
Request body example (property-level license)
PUT
https://supply-xml.booking.com/licenses/data/properties/{property_id}
The following is a successful request body example for property-level licence requirements:
{
"data": {
"contentData": [
{
"name": "issue_date",
"value": "2020-05-01"
},
{
"name": "number",
"value": "A123456789"
},
{
"name": "file",
"value": "b3448515-5b37-4cb9-837d-e8affbb83daf"
}
],
"variantId": 39
}
}
Response body example
The following is a successful response body example for property-level licence requirements:
{
"meta": {
"ruid": "UmFuZG9tSVYkc2RlIyh9Ya3WbzHWV9oIS2wUEwGUyzk1LtPWGnHLXF8LvpWuxaR6kqjAJV6MUfTVZB/XTjfzyIYDmxbUfGao5aDqJEed4LVH8of5dFKEQw=="
},
"data": {
"success": 1
},
"errors": [],
"warnings": []
}
Request body example (room-level license)
The following is a successful request body example for room-level licence requirements:
{
"data": {
"contentData": [
{
"name": "management_type",
"value": "private_person"
},
{
"name": "residence_type",
"value": "primary"
},
{
"name": "number",
"value": "1234567890123"
},
{
"name": "file",
"value": "b3448515-5b37-4cb9-837d-e8affbb83daf"
}
],
"variantId": 22
}
}
Response body example
The following is a successful response body example for room-level licence requirements:
{
"meta": {
"ruid": "UmFuZG9tSVYkc2RlIyh9Ya951VT0vsBCAFA/RugA75pfw5rz5ytfk2B7PgcnO+tBltJb/hDGmUcAAzpmaLpbmMD6WMO7gYxQ5r52nuzjm5XfyVH8ICbwcg=="
},
"data": {
"success": 1
},
"errors": [],
"warnings": []
}