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.

Quickstart

The Home Connect API
Copied link to clipboard

This API provides access to home appliances connected to Home Connect. Developers can use the Home Connect API to monitor and control these appliances. For instance, you could turn on your coffee machine and make your favorite cup of coffee. The following Quickstart guide will help you get started with exactly that.

Simulator vs. Home Connect API

"But how can I test my application?" you're asking. Of course you can use your very own Home Connect home appliance, with the actual Home Connect API, if you own one. In case you don't, we also provide a virtual environment with simulated appliances. This allows you to jump-start your development and test your applications. Please note that some of the actions you are able to perform on the simulators are not possible through the real API. One example of this is opening/closing doors. You can find the simulators here.

Using the simulator

To use the simulator, log into your account and navigate to Simulators. At the Applications page you will find an existing application called API Web Client. As you progress through the guide use the Client ID of this application and a scope of CoffeeMaker.

Host

https://simulator.home-connect.com

Using the real API

To experiment with the real API, you will have to create a new application. As you follow this guide please use the credentials of that specific application.

Host

https://api.home-connect.com

https://api.home-connect.cn (Greater China)

Authorization
Copied link to clipboard

For your application to interact with home appliances it needs to get authorized by the API. We will guide you through the steps required to complete the OAuth 2.0 Authorization Code Grant Flow process. Successful authorization will result in the API responding with a JSON Web Token.

Step 1: Get the Client ID

To get started, visit the Home Connect Developer Portal and register an account. After registration please access the application overview page. Here you can find all your applications, including a predefined one called API Web Client.

API Web Client
Use the Client ID of the API Web Client application and insert it into the query string of the URL.
To start testing on a real appliance, you should register an application first. Please choose the Authorization Code Grant Flow and fill out all required fields. Once done, complete the query string in the URL with your application's details.

Step 2: Authorization URL and Response

Next, call the authorize endpoint. Easiest way to do this is to copy the URL into your browser.

https://simulator.home-connect.com/security/oauth/authorize?response_type=code&client_id={client_id}&scope=IdentifyAppliance%20CoffeeMaker&redirect_uri=https://api-docs.home-connect.com/quickstart/
Sign in to try it outright-arrow
Copy to clipboard copy to clipboard
https://api.home-connect.com/security/oauth/authorize?response_type=code&client_id={client_id}&scope={scope}&redirect_uri={redirect_uri}
Sign in to try it outright-arrow
Copy to clipboard copy to clipboard

When prompted, log in with your Home Connect Account and grant access. The API will respond with a HTTP 302 redirect to the defined redirect_uri. A request parameter in this response will contain the authorization code.

Response

Step 3: Retrieve Token

Call the token endpoint including the authorization code obtained in previous step:

curl -X POST "https://simulator.home-connect.com/security/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "client_id={client_id}" \
  --data-urlencode "redirect_uri=https://api-docs.home-connect.com/quickstart/ \
  --data-urlencode "grant_type=authorization_code" \
  --data-urlencode "code={code}"
Sign in to try it outright-arrow
Copy to clipboard copy to clipboard
curl -X POST "https://api.home-connect.com/security/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "client_id={client_id}" \
  --data-urlencode "client_secret={client_secret}" \
  --data-urlencode "redirect_uri={redirect_uri}" \
  --data-urlencode "grant_type=authorization_code" \
  --data-urlencode "code={code}"
Sign in to try it outright-arrow
Copy to clipboard copy to clipboard

Response

Conclusion

You should now have a valid access token which enables you to use the API!
For more detailed information about the authorization process visit the dedicated page.

Monitoring
Copied link to clipboard

There are a few common use cases when developing an application with the Home Connect API. Displaying live status information of home appliances is one of them. Let's find out how to do that.

Step 1: Choose an Appliance to Use

To identify our home appliances, let us first request a list of all currently paired devices:

curl -X GET "https://simulator.home-connect.com/api/homeappliances" \
  -H "Authorization: Bearer {access_token}"
Sign in to try it outright-arrow
Copy to clipboard copy to clipboard
curl -X GET "https://api.home-connect.com/api/homeappliances" \
  -H "Authorization: Bearer {access_token}"
Sign in to try it outright-arrow
Copy to clipboard copy to clipboard

Every home appliance has a unique id, a haId, which we can see in the response from the API. For next calls, make sure to replace {haId} placeholders with the one of your chosen appliance.

Response

Step 2: Retrieve the Operation State

curl -X GET "https://simulator.home-connect.com/api/homeappliances/{haId}/status/BSH.Common.Status.OperationState" \
  -H "Authorization: Bearer {access_token}"
Sign in to try it outright-arrow
Copy to clipboard copy to clipboard
curl -X GET "https://api.home-connect.com/api/homeappliances/{haId}/status/BSH.Common.Status.OperationState" \
  -H "Authorization: Bearer {access_token}"
Sign in to try it outright-arrow
Copy to clipboard copy to clipboard

As simple as that, you can retrieve the current operation state of your home appliance. You can read more about status information on the states page.

Response

Controlling
Copied link to clipboard

Monitoring your home appliances is pretty neat. What's even more neat though is being able to control it. So to conclude the Quickstart, we're going to find out how to toggle our home appliances on/off and start a program.

Step 1: Turn On

The power state setting of a home appliance is what tells you whether the appliance is on or off. In general, you will be able to write this setting to toggle it. Some appliances don't have that capability. For more detailed information on which appliances do, visit the power state page.

A response of 204 - No Content is a sign the operation was successful. In that case your coffee machine should turn on and start rinsing.

curl -X PUT https://simulator.home-connect.com/api/homeappliances/{haId}/settings/BSH.Common.Setting.PowerState \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/vnd.bsh.sdk.v1+json" \
  --data-raw '{
   "data": {
    "key": "BSH.Common.Setting.PowerState",
    "value": "BSH.Common.EnumType.PowerState.On"
   }
  }'
Sign in to try it outright-arrow
Copy to clipboard copy to clipboard
curl -X PUT https://api.home-connect.com/api/homeappliances/{haId}/settings/BSH.Common.Setting.PowerState \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/vnd.bsh.sdk.v1+json" \
  --data-raw '{
   "data": {
    "key": "BSH.Common.Setting.PowerState",
    "value": "BSH.Common.EnumType.PowerState.On"
   }
  }'
Sign in to try it outright-arrow
Copy to clipboard copy to clipboard

Step 2: Start Program

And finally we will instruct the coffee machine to make 35ml of strong Espresso. You can find the coffee machine programs and options in detail here.

Once again, a response of 204 - No Content means it worked. Go to your coffee machine to find yourself a freshly brewed Espresso

curl -X PUT https://simulator.home-connect.com/api/homeappliances/{haId}/programs/active \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/vnd.bsh.sdk.v1+json" \
  --data-raw '{
   "data": {
   "key": "ConsumerProducts.CoffeeMaker.Program.Beverage.Espresso",
   "options": [
    {
     "key": "ConsumerProducts.CoffeeMaker.Option.BeanAmount",
     "value": "ConsumerProducts.CoffeeMaker.EnumType.BeanAmount.Strong"
    },
    {
     "key": "ConsumerProducts.CoffeeMaker.Option.FillQuantity",
     "value": 35
    }
   ]
  }
}'
Sign in to try it outright-arrow
Copy to clipboard copy to clipboard
curl -X PUT https://api.home-connect.com/api/homeappliances/{haId}/programs/active \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/vnd.bsh.sdk.v1+json" \
  --data-raw '{
   "data": {
   "key": "ConsumerProducts.CoffeeMaker.Program.Beverage.Espresso",
   "options": [
    {
     "key": "ConsumerProducts.CoffeeMaker.Option.BeanAmount",
     "value": "ConsumerProducts.CoffeeMaker.EnumType.BeanAmount.Strong"
    },
    {
     "key": "ConsumerProducts.CoffeeMaker.Option.FillQuantity",
     "value": 35
    }
   ]
  }
}'
Sign in to try it outright-arrow
Copy to clipboard copy to clipboard

Conclusion

Congrats on making it to the end of the Quickstart. You now know the basics of the Home Connect API and we cannot wait to see what new applications you're coming up with!