Skip to main content

​
Adding a Heat Pump

In this step, we will attach our first device to a user by triggering an Onboarding Session to our Connect UI.

​
Create an Onboarding Session

We need to specify parameters which will determine what is shown in the onboarding session and certain parameters of the device, such as language, price zone, and the URLs to which we want to return after completing the onboarding. 
curl -X POST \
  'https://app.podero.com/api/partners/v2.0/device-onboarding' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {auth_token}' \
  -d '{
    "language": "de",
    "price_zone_default": "AT",
    "is_smart_optimization_active_default": true,
    "success_url": "https://my-customerportal.com/success",
    "cancel_url": "https://my-customerportal.com/error",
    "user_id": "{user_id}"
  }'

​
Request Parameters

​
language
string
required
Language code for the Connect UI interface (e.g., “de”, “en”, “fr”).
​
price_zone_default
string
required
Default price zone/country code (e.g., “AT”, “DE”, “CH”).
​
is_smart_optimization_active_default
boolean
Whether smart optimization should be enabled by default.
​
success_url
string
required
URL to redirect the user after successful device onboarding.
​
cancel_url
string
required
URL to redirect the user if onboarding is cancelled or fails.
​
user_id
string (UUID)
required
The ID of the user who will own this device.

​
Response

In the response, you will receive the authentication URL: 
{
  "authentication_url": "https://connect.podero.com?onboarding_session_id=497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "user": "a169451c-8525-4352-b8ca-070dd449a1a5",
  "success_url": "https://www.success.com",
  "cancel_url": "https://www.error.com",
  "expiration_date": "2024-08-24",
  "object_id": null,
  "external_metadata": {}
}

​
Redirect to Connect UI

Use the authentication_url to redirect your user to Connect UI. Connect UI handles:
  • Selection of the correct device type and manufacturer
  • Authentication with the device manufacturer
  • Secure device linking
You can also assemble the URL yourself:
  • Base URL: https://connect.podero.com
  • URL Parameter: ?onboarding_session_id={session_id}
To skip device type selection and go directly to heat pumps, use: https://connect.podero.com/heat-pumps?onboarding_session_id={session_id}

​
The Onboarding Flow

In the device onboarding process in Connect UI, the user will be asked to provide their credentials, serial number, or other methods of authentication (depending on the manufacturer). Some devices are only supported via Gateway. Upon successful creation of a device, the user will be redirected to your success_url, which will be appended with the deviceId as a URL parameter. Example: https://my-customerportal.com/success?deviceId=8c6efd5a-36d2-4c3d-83a8-b7c9f39242cd This contains the unique UUID of the device that has just been created. You can use this for further requests to the API.

​
Test Credentials

For testing purposes of the Connect UI flow, you can use the Nibe myUplink Demo credentials:
Please use sparingly to avoid rate limiting the test account.
Test credentials for a myUplink heat pump:
These test credentials are only valid for testing and sandbox purposes.

​
Next Step

Retrieve Device Data

Read data from your connected heat pump