Documentation

Interventions

Copy page

TL;DR

• interventions[] on a capability = it's blocked. The capability exists but can't be used until the user takes action
• Most common: authentication-required → resolve with PUT /devices/{id}/connect (re-auth flow)
• subscription-upgrade-required → user needs a plan upgrade, you can't resolve this via API
• Always iterate interventions[] and drive your UI from the id — this table shows every possible value and how to fix it

Quick reference of intervention codes you may encounter and how to resolve them.

Vehicles

General (any car you connect)

Intervention	When you see it	Resolution
home-location-required	Shown on the core capability while no home location is stored. The home-location capability is not listed in capabilities[] until it is set; the PUT is accepted anyway.	Set it via PUT /v1/users/{userId}/devices/{deviceId}/home-location. Send real latitude/longitude — they drive at-home detection and gate solar-aware charging. Omitting them defaults to 0,0, which clears this intervention but leaves the vehicle permanently "not at home". Address fields (city/postalCode/street) are informational only. Details: home-location capability.
connector-type-required	Shown on the core capability while connector-type is not set.	Set it via PUT /v1/users/{userId}/devices/{deviceId}/connector-type.
location-not-available	Vehicle location data is not available (e.g., vendor does not provide location). Shown on the location-detection capability.	Informational only — no action required. This intervention does not block device control. Note: without location data the system cannot determine whether the vehicle is at its home location, so the vehicle may be controlled even when away from home (e.g., at a public charging station).

VW CCO

Intervention	When you see it	Resolution
add-charging-location-required	Shown on the core capability while the charging location is not set (VW CCO only).	The end user first sets the charging location (position) for the clever-PV charging contract in the vehicle (infotainment) or VW app — the chargingLocationId in the add-charging-location capability's data (read-only, not sent by you) identifies that contract. Then resolve via PUT /v1/users/{userId}/devices/{deviceId}/add-charging-location with body { }. The PUT only verifies that the charging location exists on the VW side — it does not set or change anything, and the vehicle's current position is irrelevant. If the location is not yet set in the vehicle, the PUT fails with 412 / errorCode: chargingLocationNotVerified — retry after the user has set it.

Tesla Official

Intervention	When you see it	Resolution
certificate-required	The clever-PV virtual key is not installed on the vehicle.	Read the url (Tesla deep link) from the install-certificate capability's data in GET /v1/users/{userId}/devices/{deviceId} — there is no per-capability GET endpoint. The user opens it on a smartphone with the Tesla app installed and confirms adding the clever-PV virtual key to the vehicle. Then resolve via PUT /v1/users/{userId}/devices/{deviceId}/install-certificate with body { }.
authentication-required	OAuth/auth fails or needs re-authentication.	Resolve via PUT /v1/users/{userId}/devices/{deviceId}/connect.
missing-scopes-required	Required OAuth scopes are missing — e.g. the user revoked clever-PV's permissions in their Tesla account. The vehicle cannot be controlled while this is active.	Read the url from the set-scopes capability's data in GET /v1/users/{userId}/devices/{deviceId} — it points to the Tesla account settings where the user (re-)grants the permissions; then resolve via PUT /v1/users/{userId}/devices/{deviceId}/set-scopes with body { }.

Heat Pumps

Bosch/Buderus

Intervention	When you see it	Resolution
approval-required	Contract status is not active during onboarding.	Resolves automatically, once the contract is active; the intervention is removed automatically.

Offline >= 5 days

Intervention	When you see it	Resolution
authentication-required	Device is offline >= 5 days.	Resolve by re-authenticating (PUT /v1/users/{userId}/devices/{deviceId}/connect).

Electric Meters

Shelly (legacy)

Intervention	When you see it	Resolution
measurement-purpose-required	Measurement purpose is not confirmed. Setup stays incomplete on creation until you confirm it.	Resolve via PUT /v1/users/{userId}/devices/{deviceId}/measurement-purpose with purpose set to gridMeter or pvProduction.

Battery operating mode

Intervention	When you see it	Resolution
smart-price-control-enabled	Shown on the operation-mode capability when the home's battery Smart Price Control automation is active. Manual mode changes are blocked while Smart Price Control is running.	Disable Smart Price Control via PUT …/home/automation-settings (smartPriceControl.enabled: false), then retry the PUT.
control-permission-required	Shown on the operation-mode capability when clever-PV is not (yet) permitted to control the battery — the control-permission state is forbidden or pending. PUTs to operation-mode fail with 400 while this intervention is present.	Resolve via PUT /v1/users/{userId}/devices/{deviceId}/control-permission with { "request": "allow" }. SigEnergy: takes effect immediately. Fronius: the user receives a verification e-mail and must confirm it — the state stays pending (and the intervention remains) until confirmed.

Target Charging (Cars & Wallboxes)

Intervention	When you see it	Resolution
target-charging-setup-required	Shown on the target-charging capability when the EV's battery capacity or consumption is not configured (null or <= 0). Both values are required before target charging can be enabled.	Set both values: PUT /v1/users/{userId}/devices/{deviceId}/battery-capacity with { "batteryCapacity": <Wh> } and PUT /v1/users/{userId}/devices/{deviceId}/consumption with { "consumption": <Wh/km> }. The intervention clears automatically on the next read once both values are positive.

How target-charging-setup-required works

Why it exists. Target charging plans how much energy must flow into the vehicle by a given time. To translate the configured target (targetWh, targetSoC) into a concrete charge plan, the system needs the EV's battery capacity (Wh) and its energy consumption. Without both values a plan cannot be computed, so the capability is blocked.

Where the values live. Both values are stored per device: for a car on its charging settings, for a wallbox on the wallbox itself. They are set via the battery-capacity and consumption capabilities. A value counts as "set" only if it is greater than 0.

What is blocked — and what is not. The intervention only blocks enabling target charging, i.e. a PUT /v1/users/{userId}/devices/{deviceId}/target-charging with "enabled": true while it is currently disabled. That request fails with 422 (ConnectApiProblemDetails, errorCode: "interventionFound"; the detail text names the intervention id). Everything else still works while the intervention is present:

• GET still returns the capability with the full plan data.
• Disabling ("enabled": false) is never blocked.
• Updating plan parameters (targetWh, executionTime, weekDays, …) without flipping enabled from false to true is not blocked either.

If the home additionally lacks the required subscription, subscription-upgrade-required takes precedence and the enable attempt fails with 402 instead.

Lifecycle. The intervention is computed at read time on every request — it is never persisted. There is no separate "resolve" call: once both values are positive, the next GET no longer includes it and enabling succeeds.

Diagnosing which value is missing. The GET response of target-charging includes the current batteryCapacity and consumption as nullable fields in data, so you can tell which of the two still needs to be set.

Cars linked to a clever-PV wallbox — rejected without an intervention

A car whose connector-type is cpvWallbox (equivalently: link-to-wallbox reports linked: true) charges through a wallbox that clever-PV controls, and its charging plan belongs on the wallbox device. Enabling target-charging on the car is rejected with 500 and errorCode: "carLinkedToWallbox" — the same applies to boost and on-off on the car. No intervention is shown for this state, so check link-to-wallbox.linked / connector-type.connectorType before offering plan modes on the car. wallPlug and unknownWallbox are not affected. Details and the wallbox-side setup: target-charging details.

General Onboarding

Intervention	When you see it	Resolution
authentication-required	Authentication issues with the device.	Resolve by re-authenticating (PUT /v1/users/{userId}/devices/{deviceId}/connect).
email-verification-required	The email-verification capability is present	Resolve via PUT /v1/users/{userId}/devices/{deviceId}/email-verification.

Subscription / Automation

Smart mode

Intervention	When you see it	Resolution
subscription-upgrade-required	Your plan is free or expired. On a starter plan, only if another device already has smart mode enabled.	Not resolvable via the Connect API. Direct the user to upgrade their clever-PV plan in the customer portal; the intervention clears automatically once the new plan is active.

Scheduling

Intervention	When you see it	Resolution
subscription-upgrade-required	Your plan does not include the Schedule feature.	Not resolvable via the Connect API. Direct the user to upgrade to a plan that includes scheduling; the intervention clears automatically once the new plan is active.

Battery automation

Home-level battery automation preconditions (solar forecast, battery capacity, firmware, operating mode, vendor email consent) appear as interventions on GET …/home/automation-settings — not on a device's capabilities[].interventions[]. See Home automation settings below.

The one battery intervention you can see on a device capability is smart-price-control-enabled on operation-mode — see Battery operating mode.

Home automation settings

These intervention ids appear under each setting's interventions[] on GET /v1/users/{userId}/home/automation-settings. Drive partner UI from id; use deviceId when present to point the user at the right device.

Intervention	Where / when	Resolution
solar-forecast-setup-required	smartPriceControl / chargeShifting when the home's solar forecast is not enabled. deviceId is null.	Enable the forecast via PUT …/home/solar-forecast ({ "enabled": true }). Requires a home location and a producing device.
battery-capacity-required	smartPriceControl / chargeShifting when a battery's capacity is unknown. deviceId is the electric meter id.	Set capacity via PUT /v1/users/{userId}/devices/{deviceId}/battery-capacity with { "batteryCapacity": <Wh> }. See battery-capacity.
battery-software-update-required	smartPriceControl / chargeShifting when the battery firmware is too old for smart control. deviceId is the electric meter id.	Resolved by the end user in the vendor's app/portal (firmware update). Not resolvable via the Connect API.
wrong-operating-mode	smartPriceControl / chargeShifting when the battery is in a vendor operating mode that blocks smart control. deviceId is the electric meter id.	Resolved by the end user in the vendor's app/portal (switch to an allowed mode). Not resolvable via the Connect API.
email-verification-required	smartPriceControl / chargeShifting when the vendor requires email consent before battery control. deviceId is the electric meter id.	Resolve via PUT /v1/users/{userId}/devices/{deviceId}/email-verification when that capability is present; otherwise the user confirms in the vendor portal.
authentication-required	smartPriceControl / chargeShifting when the battery/vendor connection needs re-authentication. deviceId is the electric meter id.	Resolve via PUT /v1/users/{userId}/devices/{deviceId}/connect (re-auth flow).

Notes

• These ids are evaluated at read time on the automation-settings endpoint. They do not appear in a device's capabilities[].interventions[] (except overlaps like authentication-required / email-verification-required that also exist in onboarding contexts).
• When a setting's applicable is false, its interventions[] is empty — applicability and interventions are separate signals. Details: Automation Settings.