# Managing property facilities

Use this endpoint to add, update or delete property-level facility details.

You can:

- [Retrieve property-level facilities details](#retrieving-facilities-details-added-to-a-property)
- Add, modify or delete property-level facilities details
  - [Add single-instance facilities](#adding-single-instance-facilities)
  - [Add multi-instance facilities](#adding-multi-instance-facilities)


For multi-instance facilities, supports updating specific facility instances
To update specific facility instances of a multi-instance facility, make sure to specify the instance identifiers (`instance_id`) for the facilities. The API updates only those specific facility instances.

## Adding single-instance facilities

```http
PUT
https://supply-xml.booking.com/facilities-api/properties/{propertyId}
```

Swimming pool, restaurant, and parking are multi-instance facilities. Some other facilities also require a detail instance — check the `required_details_list` field in the [meta endpoint response](/connectivity/docs/content-api-modules/facilities-api/facilities-meta-endpoint) for each facility. For facilities with an empty `required_details_list`, set `state` to `PRESENT` or `MISSING`.
Depending on whether you want to add or remove a facility, you can either set the facility state to `PRESENT` or `MISSING`.
While adding property facilities, you can specify one or multiple facilities in the same request.

Note that setting the state to `MISSING` is equivalent to deleting the facility from the property.

### Request body example

Make sure to send an array in the request body even when adding or updating one facility.
The following request body example adds facility ID 418 and removes facility ID 419.

```json
[
  {
    "facility_id": 418,
    "state": "PRESENT"
  },
  {
    "facility_id": 419,
    "state": "MISSING"
  }
]
```

### Adding single-instance facility with additional details

Let's use the hiking facility as an example.
You can add this facility by specifying the `state = PRESENT` or `MISSING`.
However, you can also specify additional details for this facility, namely:

- OnsiteDetails.
- SurchargeDetails.


Use the meta endpoint response
Use the response from the meta endpoint to [understand all the supported facility details.](/connectivity/docs/content-api-modules/facilities-api/facilities-meta-endpoint)

Sample meta response showing hiking facility:

```json
 {
    "facility_id": 70,
    "booking_extended_legacy_code": 5020,
    "facility_name": "HIKING",
    "allowed_details_list": [
        "OnsiteDetails",
        "SurchargeDetails"
    ]
}
```

### Request body example

The following request body adds the facility ID 70 and specifies more details.

```json
[
    {
        "facility_id": 70,
        "instances": [
            {
                "on_site_details": {
                    "onsite_type": "OFFSITE"
                },
                "surcharge_details": {
                    "surcharge_type": "FREE"
                }
            }
        ],
        "state": "PRESENT"
    },
    ...
]
```

### Response body example

The following is a response snippet for the hiking facility using the meta endpoint:

```json
...
{
  "facility_id": 70,
  "booking_extended_legacy_code": 5020,
  "facility_name": "HIKING",
  "allowed_details_list": [
    "SurchargeDetails",
    "OnsiteDetails"
  ]
}
...
```

## Adding multi-instance facilities

```http
PUT
https://supply-xml.booking.com/facilities-api/properties/{propertyId}
```

Multi-instance facilities allow you to add multiple instances of a facility.
For example, multiple restaurants or parking lots on the property.
All multi-instance facilities require you to provide certain mandatory parameters depending on the facility.

When you successfully create a multi-instance facility, the PUT endpoint returns `{"data": {"success": true}}`. Use a subsequent GET request to retrieve the assigned `instance_id` for each new instance, then use those IDs to update or delete specific instances.

You can add multiple instances in a single request or [add additional instances later.](#adding-additional-instances-to-multi-instance-facilities)

We currently support three multi-instance facilities:

- Parking (facility_id: 2). Diamond Parking and Q-Park are instances of parking facilities.
- Restaurant (facility_id: 3)
- Swimming pool (facility_id: 433).


### Before adding a multi-instance facility

Use the meta endpoint response, and look for the `required_details_list` property under a specific facility to identify the list of required parameters that you must provide.
The required details differ based on the facility to add.
To understand the data model of the required details, see the [set facilities endpoint](/connectivity/docs/openapispecs/facilities-api/facilities-api-specification/manage-property-facilities/setfacilities) in the API specification — expand **Request body > instances** and use the **Any of** dropdown to browse each instance type and its fields.

For example, to add a `Restaurant` facility, you must provide restaurant details as a JSON body.
You can look for the `RestaurantDetails` schema in the [set facilities endpoint](/connectivity/docs/openapispecs/facilities-api/facilities-api-specification/manage-property-facilities/setfacilities) to understand how to build your request body.

Overlays facility instances for multi-instance facilities
Before adding a multi-instance facility, make sure that the facility is already not added to the property.
When updating an existing facility, make sure to specify all existing instances of the facility.
Otherwise, the endpoint deletes the omitted facility instances. To avoid overlay, include instance IDs of all the facility instances.

### Request body example

Let's consider adding parking as a multi-instance facility.
To add a facility with two parking instances, you can provide instance IDs of both Diamond Parking and Q-Park.
If `instanceId` is `null`, `0`  or missing, the endpoint adds a new facility instance.

The following request body example adds two parking instances.

```json
[
  {
    "facility_id": 2,
    "instances": [
      {
        "parking_details": {
          "name": "Diamond Parking",
          "parking_location": "NEARBY",
          "parking_access": "ONLY_GUESTS",
          "parking_reservation": "NEEDED"
        },
        "payment_details": {
          "charge_mode": "FREE"
        }
      },
      {
        "parking_details": {
          "name": "Q-Park",
          "parking_location": "ON_SITE",
          "parking_access": "GENERAL_PUBLIC",
          "parking_reservation": "NOT_NEEDED"
        },
        "payment_details": {
          "charge_mode": "FREE"
        }
      }
    ],
    "state": "PRESENT"
  }
]
```

### Updating an existing facility instances

Use the `PUT` method to update a facility instance. To update a multi-instance facility, make sure to provide the facility instance ID (`instanceId`).

You can get the instance ID details using the [GET request.](#retrieving-facilities-details-added-to-a-property)

Overlays instances of existing multi-instance facilities
To update a multi-instance facility, you must provide instance IDs of all instances of that facility. Otherwise, the endpoint deletes the omitted instances. To avoid overlay, include the instance IDs of all the facility instances.

```http
PUT 
https://supply-xml.booking.com/facilities-api/properties/{propertyId}
```

### Request body example

Let's consider that a property has both Diamond parking and Q-park facility instances added.
The following request updates the Diamond parking location to `ON_SITE` and removes the Q-Park parking `instance_id: 62497396`.

```json
[
  {
    "facility_id": 2,
    "instances": [
      {
        "instance_id": 62497395,
        "parking_details": {
          "name": "Diamond Parking",
          "parking_location": "ON_SITE",
          "parking_access": "ONLY_GUESTS",
          "parking_reservation": "NEEDED"
        },
        "payment_details": {
          "charge_mode": "FREE"
        }
      }
    ],
    "state": "PRESENT"
  }
]
```

### Deleting an existing property facility

```http
PUT 
https://supply-xml.booking.com/facilities-api/properties/{propertyId}
```

To delete the facility or all instances of a multi-instance facility (for example: all parking facility), you can change the facility state to missing:

### Request body example

The following request body removes the facility ID:2 from the property.

```json
[
  {
    "facility_id": 2,
    "state": "MISSING"
  }
]
```

## Retrieving facilities details added to a property

Use the `GET` method to retrieve instance IDs (`instanceId`s) along with the facility details for all the facility instances added to the property.

```http
GET
https://supply-xml.booking.com/facilities-api/properties/{propertyId}
```

### Response  body example

The following is a response body example:

```json
{
  "data": [
    ...
    {
      "facility_id": 2,
      "instances": [
        {
          "instance_id": 62497395,
          "parking_details": {
            "name": "Diamond Parking",
            "parking_type": "UNKNOWN_PARKING_TYPE",
            "parking_location": "NEARBY",
            "parking_access": "ONLY_GUESTS",
            "parking_reservation": "NEEDED",
            "max_height_m": 0.0,
            "has_valet_service": "NOT_SPECIFIED",
            "has_onsite_staff": "NOT_SPECIFIED",
            "has_gated_parking": "NOT_SPECIFIED",
            "has_security_cameras": "NOT_SPECIFIED",
            "has_ev_charging_station": "NOT_SPECIFIED",
            "has_accessible_parking_spots": "NOT_SPECIFIED"
          },
          "payment_details": {
            "charge_mode": "FREE"
          }
        },
        {
          "instance_id": 62497396,
          "parking_details": {
            "name": "Q-Park",
            "parking_type": "UNKNOWN_PARKING_TYPE",
            "parking_location": "ON_SITE",
            "parking_access": "GENERAL_PUBLIC",
            "parking_reservation": "NOT_NEEDED",
            "max_height_m": 0.0,
            "has_valet_service": "NOT_SPECIFIED",
            "has_onsite_staff": "NOT_SPECIFIED",
            "has_gated_parking": "NOT_SPECIFIED",
            "has_security_cameras": "NOT_SPECIFIED",
            "has_ev_charging_station": "NOT_SPECIFIED",
            "has_accessible_parking_spots": "NOT_SPECIFIED"
          },
          "payment_details": {
            "charge_mode": "FREE"
          }
        }
      ],
      "state": "PRESENT"
    },
    ...
  ],
  "warnings": [],
  "errors": [],
  "meta": {
    "ruid": "00000000-0000-0000-0000-000000000000"
  }
}
```

## Activating verbose response

To add more verbosity to the API responses and see additional information, use the `debugInfo` parameter.
The endpoint then returns information from the [meta endpoint](/connectivity/docs/content-api-modules/facilities-api/facilities-meta-endpoint) in the GET response.

Large payload
Adding this parameter increases the response payload size and is only intended for debugging purposes.
Avoid using this flag in your production environment, unless you are debugging.

Use the `debugInfo=true` query parameter to attach facility metadata objects to each facility instance.

```http
GET
https://supply-xml.booking.com/facilities-api/properties/{propertyId}?debugInfo=true
```

### Response example

For example, to get the `facility_name` value to understand what `facility_id`:7 means and to get the corresponding `ota_hotel_amenity_type` for the facility (if it exists), add `debugInfo=true` to the GET endpoint.

The following is a response example:

```json
{
  "data": [
    {
      "facility_id": 7,
      "state": "PRESENT",
      "property_facility_meta": {
        "facility_id": 7,
        "ota_hotel_amenity_type": 165,
        "facility_name": "BAR",
        "allowed_details_list": [
          "TemporarilyClosedDetails"
        ]
      }
    }
  ],
  "warnings": [],
  "errors": [],
  "meta": {
    "ruid": "example-ruid"
  }
}
```