Home Connect Developer Program

This page does NOT support Internet Explorer. Please use a modern browser like e.g. Google Chrome, Mozilla Firefox or Microsoft Edge.

General

Introduction
Copied link to clipboard

Home Connect offers a RESTful API to control and monitor enabled home appliances. The following chapters provide details about the usage of this API. If it's your first time working with the Home Connect API, please see our Quickstart guide.

API client based on Swagger and Postman Collections

Endpoints and Data Encoding
Copied link to clipboard

API of simulated home appliances

https://simulator.home-connect.com

API of physical home appliances

https://api.home-connect.com or

https://api.home-connect.cn - This domain has to be used if you want to create an application for China. In this case please enable Sync to China in the account settings.

Data Encoding

The Home Connect API is based on HTTPS carrier with JSON data encoding.

All JSON transfer units are encoded with the following structure:

Best Practices
Copied link to clipboard

React on home appliance state

To get the full state of all paired home appliances of a user and keep your application updated with the latest state changes, you have to:

Thus, in total you need 54 requests to get the full state of all 6 supported home appliances and be informed of each change.

Start program

In order to start a program, several pre-conditions have to be fulfilled:

If you have sent the activation command, check BSH.Common.Status.OperationState again to validate if the home appliance switched to BSH.Common.EnumType.OperationState.Run. It might happen that some problem, e.g. the water tank is empty, happened during the activation.

Pre-heat oven

If you want to pre-heat an oven, use the program Cooking.Oven.Program.HeatingMode.PreHeating with a duration longer than the oven requires to reach the target temperature. We recommend to use a minimum of 10 minutes. The oven will start a hot air program with the selected options.

Connect to the monitoring channel for this oven and wait for the Cooking.Oven.Event.PreheatFinished event. When you receive the event, notify the user that the oven is ready.

We recommend not to use the event Cooking.Oven.Status.CurrentCavityTemperature because the temperature might not provide the necessary accuracy.

Monitoring program progress

If you started a program on a home appliance, the home appliance will provide status updates on its event channel. Useful events are:

  • BSH.Common.Status.OperationState: Use this event to reflect the oven state in your application and identify manual user interaction. For instance, if the oven switches the OperationState toBSH.Common.EnumType.OperationState.Finished you can present a message to the user that the meal is ready. If the OperationState changes toBSH.Common.EnumType.OperationState.Pause, the user either pressed the Pause button or opened the door of the oven.
  • Connection state: The home appliance is disconnected from the Home Connect server, e.g. due to a network error.

Supported Languages
Copied link to clipboard

The Home Connect API supports many languages in addition to English. When making a GET request, you have the ability to add the Accept-Language header in order to get all feature keys and enumeration values in the requested language.

Please note that API errors are not translated, e.g. if remote start disabled error is returned during program start.

Supported Languages

Language tag follows the HTTP/1.1 specification, section 3.10.

Example

Used Accept-Language header: fr-FR

Rate Limiting
Copied link to clipboard

The Home Connect API uses the following rate limits. Please make sure not to reach the limits regularly, otherwise your client application may be blocked. At the moment two different rate limit types are supported.

Amount-based Rate Limits

Generally if too many requests are sent, further requests are rejected with the HTTP status code 429.

The following limits are currently configured:

  • 10 event monitoring channels per client and Home Connect user account at any time (the request for further channels will be blocked)
  • 10 requests per second on average (20 requests max. burst) with leaky bucket algorithm, otherwise HTTP 429 error

Example

No Retry-After header is set.

Time-based Rate Limits

Generally if too many requests are sent, further requests are rejected with the HTTP status code 429. In this case, please check the Retry-After header. This states the number of seconds that you need to wait, before you try your request again.

The following limits are currently configured:

  • 10 token refresh per minute and 100 token refresh per day
  • 1000 requests per client and Home Connect user account per day
    If the quota is reached, additional requests may be blocked. Thus, do not query for state information but use the monitoring function instead, and start/stop programs with care. Furthermore, only one monitoring channel per device per home appliance is allowed.
  • 50 requests per client and Home Connect user account per minute (more requests will be blocked for one minute)
  • 5 program starts per client and Home Connect user account per minute (more program starts will be blocked for one minute)
  • 5 program stops per client and Home Connect user account per minute (more program stops will be blocked for one minute)
  • 10 successive requests per client and Home Connect user account per 10 minutes which result in an error (more requests will be blocked for 10 minutes)

Example

Retry-After header is set to 52.

API Errors
Copied link to clipboard

The Home Connect API returns appropriate HTTP status codes for every request.

Errors may have a JSON payload with the following structure:

Error Cases