Documentation

Users and Homes

Copy page

TL;DR

• No user creation endpoint — just call any endpoint with your userId and the user + home are created on the fly
• The userId is your identifier (min. 5 chars) — use whatever ID your system already has for the user
• One user = one home. Use the same userId consistently across all calls for that user
• Deleting a user is the one exception: DELETE /v1/users/{userId} never creates on the fly — it hard-deletes the user (home, devices, vendor connections, subscription) and returns 404 if the user doesn't exist
• Whitelabel partners: if clever-PV runs your branded app, your existing app customers are addressed directly — nothing is ever created, and deletion is not available (see Addressing existing app customers)

Overview

The Clever-PV Connect API currently operates in a User/Home context. All endpoints require a userId parameter to identify which user and home the operation should be performed for.

Home-level configuration (location, solar/energy forecast, automation settings) is scoped to that single home.

Automatic Creation

There are intentionally no dedicated endpoints for creating Users and Homes.

Instead, Users and Homes are created automatically when you first call any endpoint that requires a userId parameter. This implicit, on-demand creation mechanism simplifies the integration process:

• When you call any Connect API endpoint with a userId parameter
• If no User exists for that userId, the system automatically creates:
  • A new User with the specified userId
  • A new Home associated with that User (using the same ID)

This applies to partners whose users only exist in the Connect API. It does not apply to whitelabel partners addressing existing app customers — there, customers are resolved and never created.

How It Works

The userId is chosen and managed by your application. You can use any string identifier that uniquely identifies a user in your system (e.g., UUID, email, or your internal user ID).

Example

When you make your first API call for a user:

Code
GET /v1/users/{userId}/vendors

If {userId} doesn't exist yet, the API will:

1. Create a new User with that userId
2. Create a new Home for that User
3. Then proceed with the requested operation (listing vendors in this example)

Subsequent calls with the same userId will use the existing User and Home.

Home timezone

When the Home is created on that first call, its timezone is taken from the X-Connect-TimeZone request header — an IANA identifier such as Europe/Berlin or America/New_York. If you don't send the header, the Home defaults to Europe/Berlin.

This timezone is more than cosmetic: it defines the day boundaries for date-based endpoints — e.g. which midnight-to-midnight window a Historical Energy Data date selects, and the start-of-day truncation for electricity tariff from/to dates. Returned timestamps remain UTC; only the day boundaries follow the Home's timezone.

Send X-Connect-TimeZone on the request that first provisions each user so the Home is created with the right timezone from the start. The Home's stored timezone is the single source of truth for these day boundaries.

For whitelabel app customers the Home already exists and carries the timezone chosen in the app — the header has no effect there.

Addressing existing app customers (whitelabel partners)

If clever-PV operates a branded (whitelabel) app for your organization, your customers already have accounts — created when they signed in to your app. Via the Connect API you address those existing customers directly; no user is ever created, linked or registered through the API.

Interested in this? Connect API access has to be activated for your whitelabel app before any of this works. If you run a whitelabel app and want to address your app customers via the Connect API, reach out to your clever-PV contact to get it set up.

Which userId to use

There is no registration or linking step and no partner-defined external id. Use the customer's identifier directly on any endpoint:

Code
GET /v1/users/{userId}/vendors

Which identifier that is depends on how customers sign in to your app:

App login	{userId} to use
Your own identity provider (SSO/OIDC)	The subject your IdP transmits when the customer signs in to the app. Every customer who has signed in at least once is addressable.
clever-PV's own user management	The customer's account id, as returned in the userId field of GET /v1/users.

With that {userId}, all endpoints in this documentation work exactly as described.

What is different for whitelabel apps

• No on-the-fly creation on any endpoint. An unknown {userId} returns 404 Not Found (errorCode: clientExternalUserNotFound) instead of silently creating a duplicate account. A 404 for a customer you know exists usually means they have never signed in to the app.
• DELETE /v1/users/{userId} is not available. It returns 403 Forbidden (errorCode: userDeletionNotAvailable). Customer accounts are managed in the app itself.
• Connect API access is activated per app by clever-PV. Until it is activated for your app — and unless your credentials belong to the partner the app is registered to — every request returns 403 Forbidden (errorCode: connectApiNotEnabledForApp), not just the user-scoped ones. If you see this code, your clever-PV contact can check the activation for you.
• Listings cover the whole app. GET /v1/users and GET /v1/devices return all customers of the app, not only those seen through your own credentials. clientId and clientName are null for those entries — whitelabel customers belong to the app, not to an individual API client. The userId in the listing is the same identifier the /v1/users/{userId}/… endpoints accept, so use the listing to discover it.

Deleting a User

When you no longer need a user — for example because the end customer closed their account in your system — you can remove it via the Connect API:

Code
DELETE /v1/users/{userId}

A successful request returns 204 No Content.

What gets deleted

This is a hard delete and cannot be undone. Deleting a user removes, in one operation:

• the User and its Home,
• all devices linked to that Home,
• all vendor connections (OAuth, OCPP, push, form, …),
• the Connect-API-managed subscription.

Important differences from other endpoints

Unlike every other user-scoped endpoint, the delete endpoint does not create the user on the fly:

• If a user exists for the given userId, it is deleted and you receive 204 No Content.
• If no user exists for the given userId, the request returns 404 Not Found (error code clientExternalUserNotFound) — nothing is created.

Deletion is scoped to your client: you can only delete users that were provisioned through your own Connect API credentials. A userId that belongs to a different client is treated as not found.

This endpoint is not available to whitelabel partners — for them it returns 403 Forbidden (errorCode: userDeletionNotAvailable).