# 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: 1. [Retrieve licence requirements for a property](/connectivity/docs/licences-api/managing-licences/#retrieving-licence-requirements). 2. Present the appropriate licence requirements to the property. 3. Send the licence information of a [property](/connectivity/docs/licences-api/managing-licences/#sending-licence-information-of-a-property) or [room type](/connectivity/docs/licences-api/managing-licences/#sending-licence-information-of-a-room-type). 4. Retrieve existing licence information per [property](/connectivity/docs/licences-api/managing-licences/#retrieving-property-licence-information) or [room type](/connectivity/docs/licences-api/managing-licences/#retrieving-room-type-licence-information) 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.](#retrieving-licence-requirements-by-property-id) * [If your property does not yet have a Booking.com ID, retrieve by location data.](#retrieving-licence-requirements-without-property-id) ### Retrieving licence requirements by property ID ```http 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 ```http 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](/connectivity/docs/b_xml-countries) | | `property_type_id` | Specifies the property type id. | int | required | To retrieve a list of valid property types, see [Property Class Type Codes.](/connectivity/docs/codes-pct) | #### Example call with query parameters ```http 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: ```json { "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: ```json { "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.](#sending-licence-information-of-a-property) * [Retrieving the existing licence information of a specific property.](#retrieving-property-licence-information) ### Sending licence information of a property ```http 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 ```json { "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: ```json { "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 ```http 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: ```json { "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.](#sending-licence-information-of-a-room-type) * [Retrieving the existing licence information of a specific room type.](#retrieving-room-type-licence-information) ### Sending licence information of a room type ```http 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 ```json { "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: ```json { "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 ```http 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: ```json { "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](#uploading-a-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](#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 - .pdf ``` 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 --boundary-- ``` #### Example request with a PDF file ```bash 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 ```bash 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: ```json { "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: ```json { "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: ```json { "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: ```json { "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: ```json { "meta": { "ruid": "UmFuZG9tSVYkc2RlIyh9Ya951VT0vsBCAFA/RugA75pfw5rz5ytfk2B7PgcnO+tBltJb/hDGmUcAAzpmaLpbmMD6WMO7gYxQ5r52nuzjm5XfyVH8ICbwcg==" }, "data": { "success": 1 }, "errors": [], "warnings": [] } ```