JouloDocs
Api referenceEnergy

Get your energy contract and household

What Joulo knows about your home: the energy contract (supplier, dynamic or not, the supplier markup and standing charge, your own fixed tariff), and the household answers from the dashboard. Null means you did not answer. A field in inferred_fields is Joulo's estimate, not your answer. Your addresses are not here: they sit behind their own scope, at /locations. Requires the profile:read scope.

GET
/household

Authorization

AuthorizationBearer <token>

API token from the Joulo dashboard, or an OAuth2 access token.

In: header

Response Body

curl -X GET "https://api.joulo.nl/functions/v1/api/household"
{
  "contract": {
    "supplier": "Tibber",
    "supplier_has_dynamic_contracts": true,
    "dynamic": true,
    "own_fixed_eur_per_kwh": null,
    "markup_eur_per_kwh": 0.018,
    "standing_eur_per_month": 6.99,
    "tariff_as_of": "2026-09-29"
  },
  "household": {
    "housing_type": "koop",
    "has_solar": true,
    "solar_kwp": 4.2,
    "has_battery": false,
    "battery_brand": null,
    "battery_kwh": null,
    "has_heat_pump": false,
    "has_ems": false,
    "ev_count": 1,
    "car_ownership": "prive",
    "annual_km_band": "10k_20k",
    "charges_elsewhere": false,
    "has_charge_card": true,
    "charge_card_provider": "shell_recharge"
  },
  "inferred_fields": [
    "dynamic"
  ],
  "updated_at": "2026-10-02T06:30:51+00:00"
}
{
  "error": "Missing or invalid API token"
}
{
  "error": "Insufficient scope",
  "required_scope": "chargers:read"
}