Documentation for server-to-server API. We recommend first going through the Getting Started Guide to get an overview of the functionalities of the API.

End-user

We believe the end-user’s primary goal is to take control of their electricity consumption with minimal to no effort. End-users want easy-to-use, safe, and explainable processes to reduce their energy costs. The software should abstract away complexity to only present end-users with vital information that is easy to understand regardless of the end-user’s technical knowledge. End-users want proof that the optimization is working and want to be able to feel good - and show their peers - that they are using electricity in a smart way while doing the right thing: reducing their CO2 footprint.

The following set of APIs aims to achieve the end-user’s goals in the most efficient and frictionless way. We are constantly searching for new ways to improve API. Your feedback is very welcome. You can reach us by talking to your account manager or sending us an email at [email protected].

Add an end-user and connect a device

Instantiate end-user account: In most end-user applications of our Partners, an end-user who wants to use the device optimization has to opt into the optimization service (e.g. upon visiting a dedicated subpage of the mobile or web app). We suggest that once the end-user opts in, the Partner backend triggers the process of creating a new end-user account on the Podero platform by sending a POST request. The API returns a unique user_id, which can be used for subsequent requests for this end-user.
Create a device for the end-user: A new empty device can be created by sending a POST request for a specific end-user (the endpoint is dependent on which device type it is). Optionally, an end-user building can be provided in the request, which the device is then linked to (more information on adding buildings can be found below). No additional information needs to be provided. You will receive the unique device_id, as well as a unique authorization URL, which allows you to easily embed our Whitelabel onboarding form in your frontend application.
Whitelabel onboarding form - manufacturer selection: The form leads the end-user through a device type-specific selection of available manufacturers. The onboarding form will always be up to date since it is maintained by Podero.
Whitelabel onboarding form - connect device:

After selecting their device manufacturer, the end-user is prompted to connect their device. The user journey continues depending on the device manufacturer:
1. The end-user is prompted to authenticate using their device-specific credentials (see below) either:
  1. via a redirect to the manufacturer’s authentication webpage (e.g. Nibe myUplink) or
  2. via a generic login screen that calls the manufacturer’s authentication API in the background (e.g. Tesla).
  - Test credentials for a Nibe myUplink heat pump and a Tesla Electric Vehicle
  The test credentials are only valid for testing and sandbox purposes.
2. The end-user is redirected to the Podero Gateway ordering journey (see section “Connect gateway”).
Whitelabel onboarding form - success page: The end-user sees a success page after completing the onboarding flow and is subsequently redirected back to the Partner application. In the sandbox onboarding form, the redirect is not enabled.

Untitled

Examples of setting preferences and other end-user data

Setting device-specific preferences

Set heating temperature range for a specific heat_pump_id

curl -X 'PUT' \\
  '<https://app.podero.com/api/partners/v2.0/org/{org_id}/users/{user_id}/heat-pumps/{heat_pump_id}>' \\
  -H 'accept: application/json' \\
  -H 'Content-Type: application/json' \\
  -H 'Authorization: Bearer {auth_token}'
	-d '{
			"maximum_temperature_limit": 21.5,
			"minimum_temperature_limit": 19.0,
	}'

Set min & max battery charge for a specific electric_vehicle_id

curl -X 'PUT' \\
  '<https://app.podero.com/api/partners/v2.0/org/{org_id}/users/{user_id}>}/electric-vehicles/{device_id}' \\
  -H 'accept: application/json' \\
  -H 'Content-Type: application/json' \\
  -H 'Authorization: Bearer {auth_token}'
	-d '{
			"charge_target_min": 50,
			"charge_target_max": 80,
	}'

Deactivate optimized steering for a specific electric_vehicle_id

curl -X 'PUT' \\
  '<https://app.podero.com/api/partners/v2.0/org/{org_id}/users/{user_id}>}/electric-vehicles/{device_id}' \\
  -H 'accept: application/json' \\
  -H 'Content-Type: application/json' \\
  -H 'Authorization: Bearer {auth_token}'
	-d '{
			"is_smart_optimization_active": false,
	}'

Update energy contract data with new hourly price data starting at next full hour for a specific energy_contract_id:

curl -X 'PUT' \\
  '<https://app.podero.com/api/partners/v2.0/org/{org_id}/users/{user_id}/energy-contracts/{energy_contract_id}>' \\
  -H 'accept: application/json' \\
  -H 'Content-Type: application/json' \\
  -H 'Authorization: Bearer {auth_token}'
	-d '{
			"hourly_energy_price": [0.20, 0.20, 0.18, 0.14, 0.09, 0.09, 0.08, 0.09, 0.1, 0.15, 0.25, 0.31, 0.32]
	}'

Buildings

The building model is used to group devices together to facilitate photovoltaic self-consumption optimization (i.e. to use as much home-generated electricity as possible) or home/EV-battery consumption optimization (i.e. to use stored energy most efficiently, for example by using the battery to supply electricity to other household devices at the highest spot prices). It is not necessary to create a building when adding a device. Devices can be linked to a building at a later stage.

Create a building

curl -X 'POST' \\
  '<https://app.podero.com/api/partners/v2.0/org/{org_id}/users/{user_id}/buildings>' \\
  -H 'accept: application/json' \\
  -H 'Content-Type: application/json' \\
  -H 'Authorization: Bearer {auth_token}'
	-d '{
		"name": "Vacation House"
  }'

Link existing device to building

curl -X 'PUT' \\
  '<https://app.podero.com/api/partners/v2.0/org/{org_id}/users/{user_id}/heat-pumps/{device_id}>' \\
  -H 'accept: application/json' \\
  -H 'Content-Type: application/json' \\
  -H 'Authorization: Bearer {auth_token}'
	-d '{
			"building_id" : "497f6eca-6276-4993-bfeb-53cbbbba6f08"
	}'