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

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.

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)

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.

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.