# HEM system

Beta Feature: HEM systems are currently in Beta and requires API version 2024-10-01. Contact your Customer Success Manager to enable this feature for your client.

The Home Energy Management (HEM) system models how energy devices work together in the real world. It links a user’s inverter, battery, and meter into one synchronized system within the Enode API - laying the foundation for consistent, end-to-end energy insights. This guide will help you understand how HEM systems work, how to integrate them, and how to make the most of their synchronized data.

### Why HEM systems?

When users install solar panels, batteries, and smart meters, vendors manage them as a unified system. Traditional device-by-device APIs require manual synchronization of data across devices, often resulting in inconsistencies or incomplete statistics.

HEM systems mirror how vendors organize devices, providing:

- **Synchronized data collection**: All devices are polled together, ensuring consistency across generation, consumption, and storage metrics.
- **Comprehensive statistics**: Access detailed time series data with 5–15 minute resolution (vendor dependent).
- **Simplified development**: A single API endpoint for complete home energy insights that match what users see in vendor apps.
- **Optimization-ready data**: Accurate, synchronized data enables both behind-the-meter and grid-level optimization strategies.

## Conceptual Model

HEM systems provide visibility across six core energy flows between the household, devices, and the grid including consumption, generation, battery charge and discharge, and grid import and export. Together, they represent the complete picture of a user's home energy ecosystem.

In Enode's model:

- **Device**: The physical hardware owned by the user, such as an inverter, meter, or battery.
- **Asset**: Enode's representation of that device in the API.
- **HEM system**: A synchronized aggregation of related assets at a single site, grouped by vendor and location. The HEM system reflects the vendor's natural site structure, enabling unified monitoring and analysis.

Each HEM system links these assets into one consistent data structure, ensuring synchronized statistics and a complete view of home energy performance.

![HEM system conceptual diagram](https://developers.enode.com/images/hem-system/core-energy-flows.png)

## Getting Started: Link devices, view status, query statistics

### Linking

HEM systems work best when users link multiple device types in one flow. Use **multi-type linking** to request scopes across inverters, batteries, and meters under a single vendor account. Learn more in the [Multi-type linking](https://developers.enode.com/docs/link-ui/multi-type-linking) guide.

After linking, Enode automatically creates a `hem-system` for devices that share the same location.

### Discovery

After creation, the `hem-system` sends webhook updates whenever new data is available. Learn more about [Webhooks](https://developers.enode.com/docs/webhooks) at Enode.

| Event | When sent | Use case |
| --- | --- | --- |
| `user:hem-system:discovered` | When a new system is created | Initialize system record |
| `user:hem-system:updated` | When new energy data arrives | Refresh dashboards |
| `user:hem-system:deleted` | When system is removed | Clean up linked assets |

### List and Read HEM systems

Use the following endpoints to list available systems or retrieve the current state of a specific system.

| Action | Description | Endpoint |
| --- | --- | --- |
| List all systems for your client | Returns all HEM systems across users | `GET /hem-systems` |
| List systems for a specific user | Returns all HEM systems for a given user | `GET /users/{userId}/hem-systems` |
| Read current system state | Returns current energy data for a specific system | `GET /hem-systems/{hemSystemId}` |

Assets linked to a HEM system will have `hemSystemId` in their payload. This can be used to determine the devices belonging to a system. Example payload can be referred from [Batteries API](https://developers.enode.com/api/reference#getBattery) section.

### Statistics

Use the statistics endpoints to retrieve power and energy data for generation, consumption, import, and export - helpful for analyzing both recent and historical flows.

| Interval | Description | Values |
| --- | --- | --- |
| Day | Granular 5–15 minute samples | **Power (kW)** |
| Month | Daily summaries | **Energy (kWh)** |

All timestamps use the HEM system's timezone.

```bash {% title="Example Request" %}
GET /hem-systems/{hemSystemId}/statistics?interval={YYYY-MM-DD}
```

### Data Availability

Not all metrics are available for every vendor or configuration. For example, battery SoC (state of charge) is not available for all vendors when querying at the month interval, but we include (as not available) it in the response for completeness. Each time series includes an `isAvailable` flag to indicate availability.

```json {% title="Example Response" %}
  {
    "timeseries": {
        "generation": {
            "isAvailable": true,
            "unit": "kW",
            "unitType": "Power",
            "sampling": {
                "mode": "bucketed",
                "resolution": "PT5M"
            },
            "timezone": "Europe/Berlin",
            "data": [
              ...
                {
                    "t": "2025-10-08T06:00:00+02:00",
                    "v": 0.001
                },
              ...
            ],
          },
          "import": {
                  "isAvailable": false,
                  "reason": "No data available for this timeseries for this interval"
          },
          ...
  }
}
```

### Test HEM systems on Sandbox Editor

If you would like to test HEM systems API with virtual devices, use our sandbox editor to create a virtual account. Please refer to the [sandbox guide](https://developers.enode.com/docs/sandbox) for guidance on how to add virtual devices and link users. By default, solar inverters, home batteries and meters on a virtual account will be attached to a single HEM system. After linking, you should be able to:

- get webhook events such as `user:hem-system:discovered`, `user:hem-system:updated`, `user:hem-system:deleted` based on the lifecycle of devices.
- fetch hem-systems through the APIs

Limitations: Sandbox editor currently does not support editing state of the HEM system in the UI. However, we mock updates to help you test the integration and webhook ingestion pipeline.

## Current Vendor Support

HEM systems are available only for vendors that support all three asset types: inverter, battery, and meter. This ensures full data synchronization across devices, though some differences in data resolution and metric availability remain across vendors. All vendors support querying by `MONTH` interval and report data in daily buckets.

Learn more about vendors Enode supports on our [brands overview](https://developers.enode.com/brands).

| Vendor | Resolution for `DAY` Interval | Notes |
| --- | --- | --- |
| Enphase | 15 min | Full support |
| FoxESS | 5 min | Full support |
| GivEnergy | 5 min | Full support |
| Huawei | 5 min | Full support |
| SolarEdge | 15 min | Full support |
| Solax | 5 min | Full support |
| Solis | 5 min | Full support |
| SMA | 5 min | Daily Statistics resolution is dependent on user's SMA subscription package and may be 15 min. |
| Tesla | 5 min | Battery SoC resolution at 15 min intervals |

## Error Handling & Troubleshooting

| Issue | Likely Cause | Fix |  |
| --- | --- | --- | --- |
| Data with null values | - Vendor delays | Future time buckets | There may be nulls for few historical buckets due to connection issues between the system and the vendor cloud or data loss. Treat nulls as nulls in your visualizations. |
| HTTP 400 Errors | - Bad Request | User credentials invalid | Fix query params. Check if the query interval is after the installation date. Guide the user to relink with updated credentials. |
| HTTP 422 Errors | - Statistics unavailable | Check Vendor support if a specific vendor and query interval combination is supported. |  |
| HTTP 503 Errors | - Vendor API Errors | Use exponential back-off and retry |  |
| `isAvailable: false` | - Missing device | Missing scope | If scopes are missing, reason will clarify with a message - `missing_scope_{{value}}` Guide the user to a link session with the required scopes. |

## API Reference

For complete API documentation see the [HEM system API Reference](https://developers.enode.com/api/reference#hem-systems).

## Support

Need help integrating HEM systems?

- **Beta Access**: Contact your Customer Success Manager
- **Technical Questions & Bug Reports**: Report issues through Zendesk

We're actively developing HEM systems and welcome your feedback to help shape the product.