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

API of simulated home appliances

simulator.home-connect.com

API of physical home appliances

api.home-connect.com or

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 to copy all clients to China.

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:

Expand source

{ // API Response Object
    "data": { ... },  // JSON Object containing the content of a successful request. Absent in case of error.
    "error": { ... }  // API Error Object containing details / reasons for the error. Absent in case of success.
}

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:

• Call /api/homeappliances to get the list of paired home appliances and evaluate if the home appliance is currently connected, i.e. online.
• Request /api/homeappliances/{haId}/status on each home appliance to get status information like the _RemoteControl _flag
• Request /api/homeappliances/{haId}/settings on each home appliance to get settings information like the current PowerState
• If you want to show the currently active or selected program, request /api/homeappliances/{haId}/programs/active or /api/homeappliances/{haId}/programs/selected, respectively.
• If required, request /api/homeappliances/{haId}/images on the fridge-freezer to get the list of stored images and then request /api/homeappliances/{haId}/images/{imagekey} for all 6 past images of interior and door camera. Thus, in total, these are 13 requests. If you also need the preview images, you have to do another 12 requests with the respective previewimagekey.
• Open the event monitoring channel for each home appliance on /api/homeappliances/{haId}/events. The channel will stay open and you receive all changes of the home appliance right after they occurred. This includes any change which the user did locally on the home appliance as well as changes via the API.

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:

• Connection state: The home appliance needs to be connected to the Home Connect server. The connection state can be retrieved by calling /api/homeappliances and reading the connected flag on the respective home appliance.
• BSH.Common.Status.RemoteControlActive: The RemoteControl flag needs to be set to true. It must be set once on the appliance manually by the user.
• BSH.Common.Status.RemoteControlStartAllowed: The RemoteStart flag needs to be set to true. It must be set on the appliance manually by the user.
• BSH.Common.Status.LocalControlActive: The LocalControl flag needs to be set to false. It is true whenever the user operates the home appliance locally.
• BSH.Common.Status.OperationState: The OperationState needs to be set to BSH.Common.EnumType.OperationState.Ready.

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 to_BSH.Common.EnumType.OperationState.Finished_ you can present a message to the user that the meal is ready. If the OperationState changes to_BSH.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.

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

Expand source

{
    "data": {
        "key": "ConsumerProducts.CoffeeMaker.Program.Beverage.CaffeLatte",
        "options": [
            {
                "key": "ConsumerProducts.CoffeeMaker.Option.BeanAmount",
                "value": "ConsumerProducts.CoffeeMaker.EnumType.BeanAmount.Mild",
                "name": "Puissance",
                "displayvalue": "Léger"
            },
            {
                "key": "ConsumerProducts.CoffeeMaker.Option.FillQuantity",
                "value": 120,
                "unit": "ml",
                "name": "Quantité"
            }
        ],
        "name": "Café au lait"
    }
}

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.

Expand source

{
    "error": {
        "key": "429",
        "description": "Too many parallel monitoring connections. Maximum is 10."
    }
}

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.

Expand source

{
    "error": {
        "key": "429",
        "description": "The rate limit \"5 start program calls in 1 minute\" was reached. Requests are blocked during the remaining period of 52 seconds."
    }
}

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

Errors may have a JSON payload with the following structure:

Expand source

{ // API Response Object
    "error": { // API Error Object
        "key": "...", // A system wide per error unique key
        "description": "..." // A human readable, English description about the reasons of the error
    }
}

Error Cases