Property Health API overview

Use the Property Health API to retrieve health information for properties connected to your provider account. The API helps you identify properties that may need attention and can support dashboards, monitoring tools, and operational workflows.

With the Property Health API, you can:

• Retrieve health information for properties connected to your provider account.
• Retrieve health information for specific Booking.com property IDs.
• Narrow results by filtering on supported property health fields.
• For property-ID requests, identify requested property IDs that could not be returned.
• Use request metadata to help Booking.com support investigate issues.

For the full API schema, see the Property Health API OpenAPI specification.

Use Try it to send test requests directly from the developer portal. When using a live endpoint, use only test properties and valid JWT credentials for a machine account that has access to those properties.

Use a test setup first. The Property Health API is read-only, but live endpoint requests still use real authorization context and return real property health data for properties available to the selected machine account.

Property Health API requests use token-based authentication. Add an Authorization header with a Bearer JWT. Make sure the JWT belongs to a machine account that is configured for the Property Health API and has access to the test properties you use.

Do not use Try it with live JWTs on shared computers or in browsers with extensions that can inspect or monitor network traffic. Treat JWTs as credentials, and remove them from the browser environment after testing.

You can use Try it with both supported requests:

• Use POST /properties/health to retrieve property health for the authenticated provider context. Send an empty JSON object for an unfiltered lookup, or include filterBy to narrow the returned properties.
• Use POST /properties/health/by-type/property-ids to retrieve property health for specific Booking.com property IDs. Provide propertyIds with up to 2,000 IDs. You can also include filterBy to narrow the returned health records.

Successful responses include properties and meta. Include meta.ruid when contacting Booking.com support.

Before using the Property Health API, make sure that:

• You can authenticate with Booking.com Connectivity APIs.
• Your machine account has access to the properties you want to retrieve.

For more information about authentication, see Authentication.

The following table summarises the tasks, HTTP method, and endpoints that the API supports.

Use this request to retrieve property health information for properties available to your provider account.

The response contains up to 2,000 eligible properties selected by backend priority rules. The selection prioritizes actionable health and status signals, then applies deterministic property ID ordering where applicable.

POST https://supply-xml.booking.com/property-health-api/properties/health

Send an empty JSON object as the request body:

{}

You can also include filterBy to narrow the returned properties. For more information, see Filtering property health results.

Use this request to retrieve property health information for specific Booking.com property IDs. You can request up to 2,000 property IDs and can include filterBy to narrow the returned properties. For more information, see Filtering property health results.

The response only includes properties that can be returned for your machine account and have available health data. Requested property IDs that could not be returned or are not linked to the machine account ID are listed in notFoundIds.

POST https://supply-xml.booking.com/property-health-api/properties/health/by-type/property-ids

The following is an example request body:

{
  "propertyIds": [
    1000123,
    1000456
  ]
}

You can include filterBy in the same request to narrow the returned health records for the requested property IDs:

{
  "propertyIds": [
    1000123,
    1000456
  ],
  "filterBy": [
    {
      "field": "STATUS_CURRENT_STATUS",
      "operator": "EQUALS",
      "value": "Open"
    },
    {
      "field": "AVAILABILITY_RISK",
      "operator": "EQUALS",
      "value": "NO_RISK"
    }
  ]
}

The following table describes the elements of a successful response body:

Successful responses for POST /properties/health/by-type/property-ids can also include notFoundIds. This field contains requested property IDs that could not be returned or are not linked to the machine account ID.

The following shows a fully-populated property-ID lookup response example:

{
  "properties": [
    {
      "propertyId": 1000123,
      "propertyInfo": {
        "propertyName": "Canal View Hotel",
        "currencyCode": "EUR"
      },
      "status": {
        "currentStatus": "Open",
        "statusChangedAt": "2026-02-10T09:00:00Z",
        "statusDescription": "Your property is live and accepting bookings.",
        "timeInStatusDays": 30
      },
      "availability": {
        "risk": "NO_RISK",
        "bookableUntilDate": "2026-12-31",
        "bookablePeriod": 317,
        "reason": "Availability is open well into the future. No action is needed if your property is open."
      },
      "compliance": {
        "kypStatus": "APPROVED",
        "dsaStatus": "REQUESTED"
      },
      "reservations": {
        "gross": 10,
        "cancelled": 2,
        "net": 8
      },
      "dataAsOf": "2026-02-17T06:45:00Z"
    }
  ],
  "notFoundIds": [
    999999
  ],
  "meta": {
    "ruid": "ruid-1"
  }
}

The following table lists common response codes and the recommended action:

→ To learn how to authenticate, see Authentication.
→ To view the full API schema, see the Property Health API OpenAPI specification.
→ Before going live, see Going Live.