Skip to main content

​
Heat Pump Attributes

Heat pump attributes are writable parameters that control device behavior, optimization settings, and user preferences for heating and domestic hot water.

​
Required Parameters

​
user_id
string (UUID)
required
User ID that owns this heat pump device.Example: 016b78a7-0c7c-4241-a277-015c3ad3cb90Writable: No (set at device creation)

​
Device Configuration

​
building_id
string (UUID)
Building ID this heat pump belongs to. Optional - devices can exist without building assignment.Example: 016b78a7-0c7c-4241-a277-015c3ad3cb90Writable: Yes
​
device_model_id
string (UUID)
Device model identifier. Must be a valid UUID that your organization is authorized to use.Example: 016b78a7-0c7c-4241-a277-015c3ad3cb90Writable: Yes

​
Optimization Control

​
is_smart_optimization_active
boolean
Flag indicating whether Podero’s smart optimization is actively controlling this device.Set to false to pause optimization without disconnecting the device.Example: trueWritable: Yes
​
pause_power_until
datetime
Manual override timestamp to pause power consumption until a specific time.Set to a future timestamp to temporarily stop device operation. Set to null to resume normal operation.Example: 2023-03-22T13:54:34.000ZWritable: Yes
​
pause_power_active
boolean
Flag indicating whether the manual power pause override is currently active.Example: trueWritable: Yes

​
Heating Policy

​
is_heating_policy_enabled
boolean
Flag indicating whether the user has configured heating preferences.Example: trueWritable: Yes
​
maximum_temperature_limit
float
Maximum allowed indoor temperature in °C.The heat pump will not heat above this temperature.Example: 23.5Writable: Yes
​
minimum_temperature_limit
float
Minimum allowed indoor temperature in °C.The heat pump must maintain at least this temperature.Example: 19.5Writable: Yes
​
heating_policy_last_updated_utc
datetime
Timestamp when the heating policy was last updated. Read-only, automatically managed.Example: 2023-03-22T13:54:34.000ZWritable: No (system-managed)

​
Domestic Hot Water (DHW)

​
dhw_standard_temperature
float
Default temperature setpoint for domestic hot water in °C.Example: 48.0Writable: Yes
​
minimum_dhw_temperature_limit
float
Minimum allowed temperature for domestic hot water in °C.The system must maintain DHW at or above this temperature.Example: 40.0Writable: Yes

​
Away Mode

Away mode allows users to reduce energy consumption when they’re not home by lowering temperature limits temporarily.
​
is_away_mode_enabled
boolean
Flag indicating whether away mode is active.Example: trueWritable: Yes
​
away_mode_start
datetime
Timestamp when away mode should begin.Example: 2023-03-22T13:54:34.000ZWritable: Yes
​
away_mode_end
datetime
Timestamp when away mode should end and normal heating resumes.Example: 2023-03-22T18:30:00.000ZWritable: Yes
​
away_mode_minimum_temperature_limit
float
Minimum indoor temperature allowed during away mode in °C.Should be lower than the normal minimum temperature limit to save energy.Example: 19.0Writable: Yes
​
away_mode_minimum_dhw_temperature_limit
float
Minimum domestic hot water temperature allowed during away mode in °C.Should be lower than the normal DHW temperature to save energy.Example: 35.0Writable: Yes
​
away_mode_last_updated_at
datetime
Timestamp when away mode settings were last updated. Read-only, automatically managed.Example: 2023-03-22T13:54:34.000ZWritable: No (system-managed)

​
Usage Examples

​
Enable Optimization with Heating Policy

curl -X PUT \
  'https://app.podero.com/api/partners/v2.0/org/{org_id}/users/{user_id}/heat-pumps/{device_id}' \
  -H 'Authorization: Bearer {auth_token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "is_smart_optimization_active": true,
    "is_heating_policy_enabled": true,
    "minimum_temperature_limit": 20.0,
    "maximum_temperature_limit": 22.5,
    "dhw_standard_temperature": 48.0,
    "minimum_dhw_temperature_limit": 42.0
  }'

​
Configure Away Mode

curl -X PUT \
  'https://app.podero.com/api/partners/v2.0/org/{org_id}/users/{user_id}/heat-pumps/{device_id}' \
  -H 'Authorization: Bearer {auth_token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "is_away_mode_enabled": true,
    "away_mode_start": "2024-01-15T08:00:00Z",
    "away_mode_end": "2024-01-20T18:00:00Z",
    "away_mode_minimum_temperature_limit": 16.0,
    "away_mode_minimum_dhw_temperature_limit": 35.0
  }'

​
Pause Device Temporarily

# Pause for 2 hours
curl -X PUT \
  'https://app.podero.com/api/partners/v2.0/org/{org_id}/users/{user_id}/heat-pumps/{device_id}' \
  -H 'Authorization: Bearer {auth_token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "pause_power_until": "2024-01-15T14:00:00Z",
    "pause_power_active": true
  }'

​
Best Practices

  • Set minimum and maximum limits with at least 2-3°C difference
  • Consider user comfort and energy efficiency balance
  • DHW minimum should be at least 40°C to prevent Legionella growth
  • Away mode temperatures should still prevent freezing and maintain basic comfort
  • Set away mode start/end times in UTC with proper timezone handling
  • Clear away mode settings after the end time has passed
  • Reduce but don’t eliminate heating during away periods
  • Lower DHW temperature saves significant energy during absence
  • Use is_smart_optimization_active to pause optimization without disconnecting
  • Use pause_power_until for temporary manual overrides
  • Always provide future timestamps for pause operations
  • Set pause_power_until to null to resume immediately
  • Update heating policy when user preferences change
  • Consider seasonal adjustments to temperature limits
  • Monitor heating_policy_last_updated_utc to track changes
  • Validate temperature ranges before applying updates

Heat Pump State

Read-only state data and current readings

Setting Preferences

User workflow for configuring preferences

Device Onboarding

Connecting heat pump devices

Buildings

Building parameters reference