Self-certification tutorial: Rooms API

In this tutorial, you will use the Rooms API to:

Create a unit (why unit instead of room?)
Read back the unit details
Update the unit details
Delete the unit
Contact connectivity support to validate your integration and enable live/production property access

Who is this for

You should follow this if you are a developer who has completed the integration of Rooms API and is looking to start using this with live properties in production.

Before you start

You will need to use an existing test property which was either created by Property API or found in the list of test properties on the provider portal.

Step 1 - Create a unit

With your new Rooms API integration, create a mono-room like Double or a multi-room unit like Apartment within your system that will trigger a request to create the unit within Booking.com via the endpoint listed below. Save the RUID to include in your report to connectivity support (see below).

Sample request

POST
https://supply-xml.booking.com/rooms-api/properties/{propertyId}/units

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

The following is a request body example for creating a single-room unit Double:

{
  "configuration": {
    "unit_type_id": 9,
    "rooms": [
      {
        "type": "GUEST_ROOM",
        "bed_configurations": [
          {
            "beds": [
              {
                "bed_type_id": 3,
                "bed_count": 1
              }
            ],
            "is_default_configuration": true
          },
          {
            "beds": [
              {
                "bed_type_id": 1,
                "bed_count": 2
              }
            ],
            "is_default_configuration": false
          }
        ]
      }
    ]
  },
  "unit_name_id": 255,
  "number_of_units": 20,
  "smoking_policy": "NONSMOKING",
  "size": {
    "value": 24,
    "unit": "SQM"
  },
  "partner_reference_name": "Test double with multiple bed configurations",
  "floor_numbers_located_on": [
    1,
    2,
    3,
    4,
    5
  ],
  "occupancy": {
    "max_guests": 2,
    "max_adults": 2,
    "max_children": 1
  },
  "max_children_that_pay_children_rate": 1,
  "extra_beds_configuration": {
    "extra_beds": 0,
    "cribs": 1,
    "is_crib_and_extra_bed_allowed": false
  }
}

The following is a request body example for creating a multi-room unit Apartment:

{
  "configuration": {
    "unit_type_id": 1,
    "rooms": [
      {
        "type": "BEDROOM_SUBROOM",
        "bed_configurations": [
          {
            "beds": [
              {
                "bed_type_id": 6,
                "bed_count": 1
              },
              {
                "bed_type_id": 1,
                "bed_count": 1
              }
            ],
            "is_default_configuration": true
          }
        ]
      },
      {
        "type": "BEDROOM_SUBROOM",
        "bed_configurations": [
          {
            "beds": [
              {
                "bed_type_id": 1,
                "bed_count": 3
              }
            ],
            "is_default_configuration": true
          }
        ]
      },
      {
        "type": "LIVING_ROOM_SUBROOM",
        "bed_configurations": [
          {
            "beds": [
              {
                "bed_type_id": 5,
                "bed_count": 1
              }
            ],
            "is_default_configuration": true
          }
        ]
      }
    ]
  },
  "unit_name_id": 1463,
  "number_of_units": 5,
  "smoking_policy": "SMOKING_AND_NONSMOKING",
  "size": {
    "value": 155,
    "unit": "SQM"
  },
  "partner_reference_name": "Test two-bedroom apartment",
  "floor_numbers_located_on": [
    2
  ],
  "occupancy": {
    "max_guests": 5,
    "max_adults": 5,
    "max_children": 4
  },
  "max_children_that_pay_children_rate": 2,
  "extra_beds_configuration": {
    "extra_beds": 1,
    "cribs": 0,
    "is_crib_and_extra_bed_allowed": false
  }
}

Response body

The following is a response body example:

{
  "data": {
    "unit_id": 1178287071
    // other unit details
  },
  "warnings": [],
  "errors": [],
  "meta": {
    "ruid": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
  }
}

Step 2 - Read the property's units

Using your system, trigger a read request of the unit you have just created. Save the RUID to include in your report to connectivity support.

Sample request

GET
https://supply-xml.booking.com/rooms-api/properties/{propertyId}/units

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

Response body

{
  "data": [
    {
      "unit_id": 1178287071,
      "configuration": {
        "unit_type_id": 9,
        "rooms": [
          {
            "type": "GUEST_ROOM",
            "bed_configurations": [
              {
                "beds": [
                  {
                    "bed_type_id": 3,
                    "bed_count": 1
                  }
                ],
                "is_default_configuration": true
              },
              {
                "beds": [
                  {
                    "bed_type_id": 1,
                    "bed_count": 2
                  }
                ],
                "is_default_configuration": false
              }
            ]
          }
        ]
      },
      "unit_name_id": 255,
      "number_of_units": 20,
      "smoking_policy": "NONSMOKING",
      "size": {
        "value": 24.0,
        "unit": "SQM"
      },
      "partner_reference_name": "Test double with multiple bed configurations",
      "floor_numbers_located_on": [
        1,
        2,
        3,
        4,
        5
      ],
      "occupancy": {
        "max_guests": 2,
        "max_adults": 2,
        "max_children": 1
      },
      "max_children_that_pay_children_rate": 1,
      "extra_beds_configuration": {
        "extra_beds": 0,
        "cribs": 1,
        "is_crib_and_extra_bed_allowed": false
      }
    },
    {
      "unit_id": 1178287072,
      "configuration": {
        "unit_type_id": 1,
        "rooms": [
          {
            "type": "BEDROOM_SUBROOM",
            "bed_configurations": [
              {
                "beds": [
                  {
                    "bed_type_id": 1,
                    "bed_count": 1
                  },
                  {
                    "bed_type_id": 6,
                    "bed_count": 1
                  }
                ],
                "is_default_configuration": true
              }
            ]
          },
          {
            "type": "BEDROOM_SUBROOM",
            "bed_configurations": [
              {
                "beds": [
                  {
                    "bed_type_id": 1,
                    "bed_count": 3
                  }
                ],
                "is_default_configuration": true
              }
            ]
          },
          {
            "type": "LIVING_ROOM_SUBROOM",
            "bed_configurations": [
              {
                "beds": [
                  {
                    "bed_type_id": 5,
                    "bed_count": 1
                  }
                ],
                "is_default_configuration": true
              }
            ]
          }
        ]
      },
      "unit_name_id": 1463,
      "number_of_units": 5,
      "smoking_policy": "SMOKING_AND_NONSMOKING",
      "size": {
        "value": 155.0,
        "unit": "SQM"
      },
      "partner_reference_name": "Test two-bedroom apartment",
      "floor_numbers_located_on": [
        2
      ],
      "occupancy": {
        "max_guests": 5,
        "max_adults": 5,
        "max_children": 4
      },
      "max_children_that_pay_children_rate": 2,
      "extra_beds_configuration": {
        "extra_beds": 1,
        "cribs": 0,
        "is_crib_and_extra_bed_allowed": false
      }
    }
  ],
  "warnings": [],
  "errors": [],
  "meta": {
    "ruid": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
  }
}

Step 3 - Update the unit

Using your system, trigger an update request using the endpoint listed below. Save the RUID to include in your report to connectivity support.

Sample Request

PATCH
https://supply-xml.booking.com/rooms-api/properties/{propertyId}/units/{unitId}

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

Request body:

The following is a request body example:

{
  "smoking_policy": "SMOKING",
  "size": {
      "value": 45.0,
      "unit": "SQM"
  },
  "occupancy": {
      "max_guests": 4,
      "max_adults": 4,
      "max_children": 3
  }
}

Response body

{
  "warnings": [],
  "errors": [],
  "meta": {
    "ruid": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
  }
}

Step 4 - Delete the unit

Using your system, trigger a delete request using the endpoint listed below. Save the RUID to include in your report to connectivity support.

Sample Request

DELETE
https://supply-xml.booking.com/rooms-api/properties/{propertyId}/units/{unitId}

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

Response body

{
  "warnings": [],
  "errors": [],
  "meta": {
    "ruid": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
  }
}

Step 5 - Send the RUIDs to Booking.com

Send via your organization’s domain email the RUID values obtained in the response bodies of the POST, GET, PATCH and DELETE requests to connectivity@booking.com for validation and certification.

Email template

I would like to be certified for production use of Rooms API. Please find the RUIDs for all of the steps in the tutorial.

I look forward to hearing from you.