Enode API 2024-10-01

This reference provides a comprehensive overview of the Enode API endpoints for accessing and controlling its hardware and features. The API follows REST principles, and uses OAuth 2.0.

This page features detailed documentation for each of our endpoints. You can also explore our API through our updated OpenAPI specifications or Postman collection.

The API is versioned, and all documentation on this page, including the links to the OpenAPI specifications and Postman collection is specific to the selected version.

Environments

We provide multiple environments, each with unique data access policies, and live/mocked vendors.

Environments are isolated from each other. Client credentials are tied to a specific environment and cannot be reused across environments.

Copy linkProduction

Features the latest stable software, live vendors, and strict data access controls.

Name	URL
API	https://enode-api.production.enode.io
OAuth Token	https://oauth.production.enode.io/oauth2/token
Link UI	https://link.enode.com

Copy linkSandbox

Includes the latest stable software and mocked vendors/vehicles/chargers.

Name	URL
API	https://enode-api.sandbox.enode.io
OAuth Token	https://oauth.sandbox.enode.io/oauth2/token
Link UI	https://link.sandbox.enode.io

Authentication

The Enode API uses OAuth 2.0 client access tokens for authenticating server requests.

Copy linkAPI credentials

Enode API access begins with a client and its corresponding client ID and client secret. Clients organize data, are separate, and relate to a specific environmentAPI.

API credentials are used to obtain an access tokenAPI for accessing client-wide endpointsAPI and user-specific endpointsAPI.

Key	Description
Client ID	The identifier for your client, referred to as the `client_id`.
Client secret	The secret for your client, referred to as the `client_secret`.

Copy linkGetting an access token

The access token authorizes client access to all data and functionality. Obtain it via the OAuth 2.0 client credentials grant using the API credentialsAPI and the relevant OAuth URLsAPI for your client's environment.

Token request example

curl https://oauth.{YOUR_CLIENT_ENVIRONMENT}.enode.io/oauth2/token \
-X POST \
-u {YOUR_CLIENT_ID}:{YOUR_CLIENT_SECRET} \
-d "grant_type=client_credentials"
curl https://oauth.{YOUR_CLIENT_ENVIRONMENT}.enode.io/oauth2/token \
-X POST \
-u {YOUR_CLIENT_ID}:{YOUR_CLIENT_SECRET} \
-d "grant_type=client_credentials"

After requesting the token URL, you'll receive an access token in the response. Cache this token on your server until it expires and needs refreshingAPI. Keep the access token secret.

Token response example

{
  "access_token": "{YOUR_ACCESS_TOKEN}",
  "expires_in": 3599,
  "scope": "",
  "token_type": "bearer"
}
{
  "access_token": "{YOUR_ACCESS_TOKEN}",
  "expires_in": 3599,
  "scope": "",
  "token_type": "bearer"
}

Copy linkRefreshing access tokens

Access tokens expire hourly, indicated by the expires_in key in the response. When expired, obtain a new tokenAPI.

Copy linkAccessing the API with the access token

Authenticate all API requests using a bearer authentication header. This header accesses client-wide endpoints (service healthAPI, tariffsAPI, user managementAPI, and webhooksAPI).

Type	Value
Header	`Authorization: Bearer {YOUR_ACCESS_TOKEN}`

Client resource request example

curl https://enode-api.{YOUR_CLIENT_ENVIRONMENT}.enode.io/health/ready \
-H "Authorization: Bearer {YOUR_ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
curl https://enode-api.{YOUR_CLIENT_ENVIRONMENT}.enode.io/health/ready \
-H "Authorization: Bearer {YOUR_ACCESS_TOKEN}" \
-H "Content-Type: application/json" \

Copy linkAccessing user-specific endpoints

For resources specific to a user, include an additional header with the user ID along with the general authorization header. For versions newer than 2023-08-01, this is no longer required.

Use this additional header for general user endpoints (locationsAPI, usersAPI, schedulesAPI, statisticsAPI) and device-specific endpoints (chargersAPI, HVACsAPI, solar invertersAPI, and vehiclesAPI).

Type	Value
Header	`Enode-User-Id: {USER_ID}`

User resource request example

curl https://enode-api.{YOUR_CLIENT_ENVIRONMENT}.enode.io/me \
-X GET \
-H "Authorization: Bearer {YOUR_ACCESS_TOKEN}" \
-H "Enode-User-Id: {USER_ID}" \
curl https://enode-api.{YOUR_CLIENT_ENVIRONMENT}.enode.io/me \
-X GET \
-H "Authorization: Bearer {YOUR_ACCESS_TOKEN}" \
-H "Enode-User-Id: {USER_ID}" \

Response times

Enode resources like Schedules and Locations have response times of <200ms. However, vehicle interactions involve various delays and timing characteristics.

Understanding the range of possible timings without diving into vendor-specific causes, helps you account for these factors in your UX design.

Copy linkAPI GET requests

Copy linkGet Vehicle

Get Vehicles and List Vehicles are fast operations since all data is prefetched by Enode and shared from a cache.

On API versions prior to 2023-08-01 it is possible to request a synchronous update where data is fetched directly from the vendor. Such requests have longer response times, sometimes 30 seconds or more, depending on the characteristics of the underlying vendor APIs. From 2023-08-01 onwards this has been replaced by the refresh hintAPI mechanism.

Copy linkLink User

The Login step usually takes <2 seconds, but can rarely take up to 30 seconds due to background negotiations, retries, and initial vehicle data fetching.

The final Accept step experiences similar delays as List Vehicles.

Copy linkCharging commands

Charging commands show significant timing variability among vendors. Initiating the action is instant, but the updated charging state typically takes 20 seconds to appear. Occasionally the action may take 5 minutes or more to confirm.

Copy linkWebhooks

Webhooks typically involve polling and dynamically adjust the polling rate based on various factors to balance prompt updates with avoiding unnecessary load on the vehicle.

The maximum baseline delay between a real-world change (e.g., a vehicle being plugged in) and the resulting webhook notification is typically 7 minutes. However, actual delays can vary depending on factors such as vehicle activity and network conditions. Below is a general guide for typical webhook delays:

Vehicle context	Typical delay
default	~7 minutes
charging	~2-5 minutes
smartcharge PLAN:*	~2 minutes
sleeping	~20 minutes

If you'd like to request a faster refresh, you can call the various /refresh-hint endpoints found on devices to queue an accelerated data refresh.

Scopes

Access to the data and controls of a device are scoped by an inclusive scopes structure. The scopes are requested in the Link user endpoint via the scopes parameter. Scopes are presented to your user in Link UI, and explained through example data and examples of features enabled by each scope. Your user is not able to de-select or configure scopes themselves in Link UI.

Data scopes include all data and states we fetch from the device, excluding location data, and is always required (e.g vehicle:read:data)
Location scopes include the location coordinates of the device (e.g. vehicle:read:location)
Control scopes are always explicit to the type of control that is requested (e.g. vehicle:control:charging)

The applied scopes are surfaced through the scopes object in device responses (see example below).

Copy linkOverview of scopes

Asset type	Scope	Description
Battery	`battery:control:operation_mode`	Controls the operation mode of the battery
	`battery:read:location`	Reads the GPS coordinates of the battery
	`battery:read:data`	Reads the battery data, such as the charge state, configuration and general information
Charger	`charger:control:charging`	Controls the max current configuration and/or charging of the charger
	`charger:read:data`	Reads the charger data, such as the charge state and general information
HVAC	`hvac:control:mode`	Controls the mode (permanent hold or follow schedule) of the HVAC unit
	`hvac:read:data`	Reads the HVAC data, such as the information, thermostat state and temperature state
Inverter	`inverter:read:data`	Reads the inverter data, such as the production state and general information
	`inverter:read:location`	Reads the GPS coordinates of the inverter
Meter	`meter:read:location`	Reads the GPS coordinates of the meter
	`meter:read:data`	Reads the meter data, such as energy state and general information
Vehicle	`vehicle:control:charging`	Controls the charging of the vehicle
	`vehicle:read:data`	Reads the vehicle data, such as charge state, odometer and general information
	`vehicle:read:location`	Reads the GPS coordinates of the vehicle

Copy linkHandling excluded scopes

Copy linkThe relationship between scopes and capabilities

If a device is missing a scope, e.g. a charger that does not have the charger:control:charging scope set, will always have the charging related capabilities will always be set as isCapable: false with no intervention specified.

Example charger response

{
  "id": "2211e263-0362-4235-83f4-887bdf3ee414",
  "userId": "17d9f847-8a1c-4158-adaa-4911a7acd5f9",
  "vendor": "ZAPTEC",
  "lastSeen": "2023-03-21T21:08:27.596Z",
  "isReachable": true,
  "locationId": "2211e263-d6d4-d6d4-d6d4-dbdd77ec82b6",
  "scopes": ["charger:read:data"], // Scopes applied to the device
  "chargeState": { ... },
  "information": { ... },
  "capabilities": {
    "information": {
      "isCapable": true, // Capable via the charger:read:data scope
      "interventionIds": []
    },
    "chargeState": {
      "isCapable": true, // Capable via the charger:read:data scope
      "interventionIds": []
    },
    "startCharging": {
      "isCapable": false, // Missing charger:control:charging scope
      "interventionIds": []
    },
    "stopCharging": {
      "isCapable": false, // Missing charger:control:charging scope
      "interventionIds": []
    },
    "setMaxCurrent": {
      "isCapable": false, // Missing charger:control:charging scope
      "interventionIds": []
    }
  }
}
{
  "id": "2211e263-0362-4235-83f4-887bdf3ee414",
  "userId": "17d9f847-8a1c-4158-adaa-4911a7acd5f9",
  "vendor": "ZAPTEC",
  "lastSeen": "2023-03-21T21:08:27.596Z",
  "isReachable": true,
  "locationId": "2211e263-d6d4-d6d4-d6d4-dbdd77ec82b6",
  "scopes": ["charger:read:data"], // Scopes applied to the device
  "chargeState": { ... },
  "information": { ... },
  "capabilities": {
    "information": {
      "isCapable": true, // Capable via the charger:read:data scope
      "interventionIds": []
    },
    "chargeState": {
      "isCapable": true, // Capable via the charger:read:data scope
      "interventionIds": []
    },
    "startCharging": {
      "isCapable": false, // Missing charger:control:charging scope
      "interventionIds": []
    },
    "stopCharging": {
      "isCapable": false, // Missing charger:control:charging scope
      "interventionIds": []
    },
    "setMaxCurrent": {
      "isCapable": false, // Missing charger:control:charging scope
      "interventionIds": []
    }
  }
}

Copy linkResponses when the location scope is excluded

Devices with a missing location scopes will respond with longitude: null and latitude: null as part of their location object.

Copy linkResponses when a control scopes is excluded

Devices with missing control scopes will respond with a 403 error, and the action or command will not go through to the device.

Copy linkApplying new scopes to a device

To set new scopes for a device, it needs to be re-linked via the Link userAPI endpoint by setting new scope values in the scopes parameter.

Errors and problems

Copy linkErrors when accessing a User's resources

When using an access_token to access a user's resources, you may encounter the following 4XX range HTTP Status Codes:

HTTP Status Code	Explanation
400 Bad Request	The request payload failed schema validation or parsing
401 Unauthorized	Missing or invalid authentication details
403 Forbidden	Authentication succeeded, but the user lacks access to the resource due to a missing control scope.
404 Not Found	Requested resource doesn't exist
405 Method Not Allowed	Vendor unavailability prevented request completion
408 Request Timeout	Vendor timeout prevented request completion
409 Conflict	Vendor rejection prevented request completion
424 Failed Dependency	Failed vendor requests prevented request completion
429 Too Many Requests	Vendor rate limiting prevented request completion

In all cases, an RFC7807 Problem Details body is returned to aid in debugging.

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json
{
  "type": "https://developers.enode.com/problems/bad-request",
  "title": "Payload validation failed",
  "detail": "\"authorizationRequest.scope\" is required",
}
HTTP/1.1 400 Bad Request
Content-Type: application/problem+json
{
  "type": "https://developers.enode.com/problems/bad-request",
  "title": "Payload validation failed",
  "detail": "\"authorizationRequest.scope\" is required",
}

Copy linkProblems

Title	Description
Bad request	Some part of the request was malformed. See associated detail message for more information.
Enode Controlled Entity	This entity is currently managed by Smart Charging or Schedules and cannot accept manual commands. Either disable the feature controlling the target, or force charging to start through our External Start APIAPI.
Entity Not Found	The requested entity was not found on the user's account.
Forbidden	The current context is not allowed to access the requested resource.
Not Found	The requested entity was not found on the user's account. If requesting vendor entities, ensure you're using the top level `id` field and not `information.id`. `information.id` is the ID the vendor uses to refer to the entity and changes over time.
Server Error	A critical error has occurred. An employee has been alerted and will work to remedy the situation
Service Unavailable	The service is currently unavailable. Most likely the service was slow to respond, might be overloaded or down for maintenance. Other endpoints might still be available. You may want to retry the request using a randomized backoff delay. Check the Enode Status page if this problem persists.
Timeout	A request timed out. If this problem was returned by a route that tried to communicate with vendor APIs, remove the fields query parameter to fetch the Enode hosted cache. This cache is updated every 10 minutes.
Unauthorized	The request contained an invalid or expired token.
Validation Error	The response we prepared failed to pass outgoing validation. An employee has been alerted and will work to remedy the situation.

Versioning

Enode's REST API is versioned. A dated version is released when breaking changes occur, while new features and bug fixes (additive changes) are available in all supported API versions.

You can view all available versions and updates in the changelog.

API clients are pinned to the latest API version upon creation, affecting all API requests and webhook events. API responses include an Enode-Version header, and webhook events have a version field.

You can override the API version on a specific request by sending an Enode-Version in the request header.

Copy linkBreaking changes

Breaking changes will be released as a new version. When a new version is released, the previous version is supported for six months before deactivation. Enode staff will notify you in advance. Each API version comes with a migration guide explaining changes and upgrade suggestions.

We consider the following breaking changes

Changing a request’s authorization or authentication requirements
Adding a new required input parameter
Changing input validation
Removing an HTTP route or method
Removing or renaming a response parameter

All other additive changes are considered backwards compatible.

Copy linkVersion Lifecycle

Current

This is the latest API version, recommended for all customers.
It is the default version for new clients and the default version documented in our API Reference.
There is only ever one Current API version.

Deprecated

This version has been superseded by a newer version. Multiple Deprecated versions can exist.
Customers can still choose this version for new clients or webhook subscriptions at developers.enode.com.
Documentation will be marked as Deprecated.
New functionality may not be released to Deprecated versions and supported exclusively on the Current API version.
We recommend you to upgrade to the Current version as soon as possible.

Legacy

This version has been deprecated for 6 months. Multiple Legacy versions can exist.
Customers cannot select this version for new clients or webhook subscriptions.
Documentation will not be accessible from the API Reference. You can review Legacy documentation by logging in to your organization dashboard and selecting a client with a Legacy version.
Functionality may be degraded, and no new features will be added.
4 weeks after entering Legacy status, we will begin preparations for automatically upgrading clients on this version. Enode will conduct API brownouts for clients still using Legacy versions at this time. During these brownouts, we will randomly reject API requests using the Legacy API version.
8 weeks after entering Legacy status, clients and webhooks using this version will be automatically upgraded to the Current API version.

Copy linkLabels

Some of the products or endpoints we have available are labelled. Here's an explanation of each.

Copy linkBeta

This product or endpoint is now feature complete and the implementation will not change. There may be bugs or stability issues but they are actively being worked on. We are still open to receiving feedback before delivering a stable release.

Copy linkEarly Adopter

This feature or endpoint is available to early adopters for initial feedback. The implementation is still evolving and may change or be removed.

Copy linkDeprecated

Individual features, endpoints, or fields tagged as Deprecated will be removed in a future version of the API. If you are using deprecated functionality you should update your application to use alternative features or methods we provide.

Pagination

Enode endpoints returning collections of a specific type of resource, such as GET /vehicles, will return a paginated response. Each response will consist of a subset of the resources, called a page. To retrieve the entire collection, subsequent pages need to be fetched.

Each response includes two properties: data and pagination. The data property contains the records of the current page and the pagination property contains cursors that can be used to fetch additional pages. These cursors, before and after, are unique identifiers for specific records in the dataset that help you keep track of your position and navigate through the pages.

Copy linkQuerying a paginated API endpoint

When querying a paginated endpoint, you may provide the following pagination query parameters:

Pagination query parameter example

{
  "pageSize": 50,
  "before": "MjAyMy0wNy0xOFQxMDowODowMi4zNzNa",
  "after": "MjAyMy0wNi0xNlQwOTowMzowMS4yNjJa"
}
{
  "pageSize": 50,
  "before": "MjAyMy0wNy0xOFQxMDowODowMi4zNzNa",
  "after": "MjAyMy0wNi0xNlQwOTowMzowMS4yNjJa"
}

All of these pagination query parameters are optional. If pageSize is not provided, the default page size of 50 is used. If neither before nor after are provided, the returned page will contain the first set of resources in the collection.

The before and after parameters are mutually exclusive. If both are supplied, the API will return an error.

Responses from most paginated endpoints are sorted in descending order according to when the resource was created. Hence, for a request like GET /vehicles, the most recently linked vehicles appear on the first page.

Copy linkHow to navigate through paginated API responses

The pagination property in a paginated response typically looks like this:

Pagination property example

"pagination": {
  "before": "MjAyMy0wNy0xOFQxMDowODowMi4zNzNa",
  "after": "MjAyMy0wNi0xNlQwOTowMzowMS4yNjJa"
}
"pagination": {
  "before": "MjAyMy0wNy0xOFQxMDowODowMi4zNzNa",
  "after": "MjAyMy0wNi0xNlQwOTowMzowMS4yNjJa"
}

The pagination property provides the cursors required to fetch the next and previous pages of resources:

before contains the cursor to be used to fetch the previous page.
after contains the cursor to be used to fetch the next page.

One or both cursors may be null instead of a string. This occurs when:

You are on the first page. There are no preceding resources, so before will now be null as otherwise it would point to an empty page.
You are on the last page. There are no subsequent resources, so after will now be null as otherwise it would point to an empty page.
The entire collection fits on the first page. There are no preceding or subsequent resources, so both before and after are null.

Copy linkFull example response

Example paginated response

{
    "data": [
        {
            "id": "0",
            "vendor": "TESLA",
            ...
            "isReachable": true
        },
        ...
        {
            "id": "49",
            "vendor": "TESLA",
            ...
            "isReachable": true
        }
    ],
    "pagination": {
        "before": null,
        "after": "MjAyMy0wNy0xOFQxMDowNDowMi4zNzNa"
    }
}
{
    "data": [
        {
            "id": "0",
            "vendor": "TESLA",
            ...
            "isReachable": true
        },
        ...
        {
            "id": "49",
            "vendor": "TESLA",
            ...
            "isReachable": true
        }
    ],
    "pagination": {
        "before": null,
        "after": "MjAyMy0wNy0xOFQxMDowNDowMi4zNzNa"
    }
}

In this example, the data array includes the resource records for the current page. The pagination object provides the cursors for navigating to adjacent pages.

Images

Enode provides product images for vehicles and other assets. Image URLs are returned in the imageUrl field of API responses, such as GET /vehicles/{vehicleId} and webhook payloads.

Images are served through a global CDN with on-the-fly transformations including resizing, format conversion, and quality adjustment.

Copy linkBase URL

Images are served from https://cdn.images.enode.com/assets/{imageId}.{ext}.

Copy linkSupported formats

Format	Extension	MIME Type
PNG	`.png`	`image/png`
WebP	`.webp`	`image/webp`
AVIF	`.avif`	`image/avif`

Copy linkQuery parameters

Parameter	Description	Default
`width`	Output width in pixels (1-2048)	Original
`height`	Output height in pixels (1-2048)	Original
`fit`	Resize mode (see below)	`cover`
`quality`	Compression quality (1-100) or `"auto"`. Applies to WebP and AVIF only.	`auto`

Copy linkFit modes

Mode	Behavior
`cover`	Fill entire area, crop if needed (CSS `object-fit: cover`)
`contain`	Fit within area, preserve aspect ratio (CSS `object-fit: contain`)
`fill`	Stretch to fill, may distort (CSS `object-fit: fill`)
`inside`	Like `contain`, but never upscale
`outside`	Like `cover`, but never downscale

Copy linkExamples

Basic image request

curl "https://cdn.images.enode.com/assets/{imageId}.png"

Resize to 400px width

curl "https://cdn.images.enode.com/assets/{imageId}.png?width=400"

Convert to WebP with custom quality

curl "https://cdn.images.enode.com/assets/{imageId}.webp?quality=80"

Resize and convert

curl "https://cdn.images.enode.com/assets/{imageId}.webp?width=800&height=600&fit=contain"

Copy linkCaching

Images are served with long-lived cache headers. Transformed images are cached on the CDN, so subsequent requests for the same transformation are served directly from cache.

Flex price signals

Price signals are the value signal that an energy retailer sends to influence optimization. They are always scoped to an area within a zone. Each push may trigger re-optimization of affected assets.

Push price signal

PUT /flex/price-signals/{zoneId}/areas/{areaId}

Push a price signal for a specific area within a zone. Replaces all existing data in the window [firstValue.at, to) with the provided values. Each push may trigger re-optimization of all assets at locations in that area.

Request

Path parameters

zoneId string Required

The zone identifier. Corresponds to a market bidding zone (e.g., NO1, BE, SE3).

areaId string Required

The area identifier. A customer-defined subdivision within a zone (e.g., a forecast area or grid area).

Attributes

currency string Required
ISO 4217 currency code. Must match the zone's configured currency. Acts as a confirmation to prevent misconfiguration.
to string<date-time> Required
End of the replacement window (exclusive). All existing data in [firstValue.at, to) is replaced with the provided values.
values array of object Required
The price signal values. At least one value is required. Values must be ordered chronologically. Each value defines the price from its timestamp until the next value (step function). The first value's 'at' defines the start of the replacement window.
Show child attributes
- values[].at string<date-time> Required
  UTC timestamp when this price becomes effective. The price applies from this point until the next value (or until the window end).
- values[].price number Required
  The price value in the zone's configured currency per kWh.

Response 204

Price signal accepted.

Response 400

Zone is not activated, or the currency does not match the zone's configured currency.

Get price signal

GET /flex/price-signals/{zoneId}/areas/{areaId}

Retrieve the current price signal for a specific area over a time range.

Request

Path parameters

zoneId string Required

The zone identifier. Corresponds to a market bidding zone (e.g., NO1, BE, SE3).

areaId string Required

The area identifier. A customer-defined subdivision within a zone (e.g., a forecast area or grid area).

Query parameters

from string<date-time> Required

Start of the time range (UTC).

to string<date-time> Required

End of the time range (UTC).

Response 200

Successful.

Attributes

zoneId string
The zone this price signal belongs to.
areaId string
The area this price signal belongs to.
currency string
The currency of the price values.
from string<date-time>
Start of the queried time range.
to string<date-time>
End of the queried time range.
values array of object
The price signal values within the queried range.
Show child attributes
- values[].at string<date-time>
  UTC timestamp when this price becomes effective. The price applies from this point until the next value (or until the window end).
- values[].price number
  The price value in the zone's configured currency per kWh.

Response 400

Invalid query parameters.

Response 404

Zone not found or no price signal exists for this area.

Push price signal (bulk)

PUT /flex/price-signals/{zoneId}/areas

Push the same price signal to multiple areas in one call. Each area gets its own stored price signal — this is a convenience to reduce HTTP calls when many areas share the same price.

Request

Path parameters

zoneId string Required

The zone identifier. Corresponds to a market bidding zone (e.g., NO1, BE, SE3).

Attributes

areas array of string Required
The area identifiers to push the price signal to. All listed areas receive the same values.
currency string Required
ISO 4217 currency code. Must match the zone's configured currency.
to string<date-time> Required
End of the replacement window (exclusive).
values array of object Required
The price signal values. Applied identically to all listed areas.
Show child attributes
- values[].at string<date-time> Required
  UTC timestamp when this price becomes effective. The price applies from this point until the next value (or until the window end).
- values[].price number Required
  The price value in the zone's configured currency per kWh.

Response 204

Price signals accepted for all listed areas.

Response 400

Zone is not activated, or the currency does not match the zone's configured currency.

Flex segments

Segments partition households by their asset type composition (e.g., EV-only, EV+solar). Segment definitions are zone-agnostic and apply across all zones for a client. Segments are provably disjoint — no household can match more than one segment.

Create segment

POST /flex/segments

Create a segment definition. Segments partition households by their asset type composition. The system validates that the new segment does not overlap with any existing segment — if any possible household profile would match multiple segments, the request is rejected with an explanation.

Request

Attributes

name string Required
Human-readable name for the segment. Must be unique per client.
household object Required
Filter that determines which households match this segment based on asset type composition.
Show child attributes
- household.includes array of string Required
  Asset types the household must have (AND — all must be present).
- household.excludes array of string Optional
  Asset types the household must not have (none may be present). Omit for no restriction.

Response 201

Segment created.

Attributes

id string<uuid>
Unique identifier for the segment.
name string
Human-readable name for the segment.
household object
Filter that determines which households match this segment.
Show child attributes
- household.includes array of string
  Asset types the household must have (AND — all must be present).
- household.excludes array of string
  Asset types the household must not have (none may be present).
createdAt string<date-time>
When the segment was created.
updatedAt string<date-time>
When the segment was last updated.

Response 409

Segment overlaps with an existing segment, or a segment with this name already exists.

List segments

GET /flex/segments

List all segment definitions for the client. Segments are zone-agnostic — the same definitions apply across all zones.

Response 200

Successful.

Attributes (list of object)

id string<uuid>
Unique identifier for the segment.
name string
Human-readable name for the segment.
household object
Filter that determines which households match this segment.
Show child attributes
- household.includes array of string
  Asset types the household must have (AND — all must be present).
- household.excludes array of string
  Asset types the household must not have (none may be present).
createdAt string<date-time>
When the segment was created.
updatedAt string<date-time>
When the segment was last updated.

Get segment

GET /flex/segments/{segmentId}

Get a segment definition by ID.

Request

Path parameters

segmentId string<uuid> Required

The segment identifier.

Response 200

Successful.

Attributes

id string<uuid>
Unique identifier for the segment.
name string
Human-readable name for the segment.
household object
Filter that determines which households match this segment.
Show child attributes
- household.includes array of string
  Asset types the household must have (AND — all must be present).
- household.excludes array of string
  Asset types the household must not have (none may be present).
createdAt string<date-time>
When the segment was created.
updatedAt string<date-time>
When the segment was last updated.

Response 404

Segment not found.

Replace segment

PUT /flex/segments/{segmentId}

Replace a segment definition. The disjointness check runs against all other existing segments. If the update would create an overlap, it is rejected. Changes take effect on the next shape computation.

Request

Path parameters

segmentId string<uuid> Required

The segment identifier.

Attributes

name string Required
Human-readable name for the segment. Must be unique per client.
household object Required
Filter that determines which households match this segment based on asset type composition.
Show child attributes
- household.includes array of string Required
  Asset types the household must have (AND — all must be present).
- household.excludes array of string Optional
  Asset types the household must not have (none may be present). Omit for no restriction.

Response 200

Segment replaced.

Attributes

id string<uuid>
Unique identifier for the segment.
name string
Human-readable name for the segment.
household object
Filter that determines which households match this segment.
Show child attributes
- household.includes array of string
  Asset types the household must have (AND — all must be present).
- household.excludes array of string
  Asset types the household must not have (none may be present).
createdAt string<date-time>
When the segment was created.
updatedAt string<date-time>
When the segment was last updated.

Response 404

Segment not found.

Response 409

Updated segment would overlap with an existing segment, or the new name conflicts with another segment.

Delete segment

DELETE /flex/segments/{segmentId}

Delete a segment definition. Assets at households previously in this segment will appear in 'unassigned' on the next shape computation.

Request

Path parameters

segmentId string<uuid> Required

The segment identifier.

Response 204

Segment deleted.

Response 404

Segment not found.

Flex shape

The Flex Shape API exposes an aggregated controllable energy load per zone, broken down by segment. Trading algorithms use the shape to construct bid curves. The additivity guarantee holds: total = sum(segments) + unassigned.

Get flex shape

GET /flex/shape/{zoneId}

Get the flex shape for a zone, broken down by segment. Returns all segments in a single response — one HTTP request per zone returns everything needed to construct bid curves. The additivity guarantee holds: for every chunk, total = sum(segments) + unassigned.

Request

Path parameters

zoneId string Required

The zone identifier. Corresponds to a market bidding zone (e.g., NO1, BE, SE3).

Query parameters

area string Optional

Comma-separated list of area identifiers. When provided, only households at locations in one of the listed areas are included.

Response 200

Shape retrieved.

Attributes

zoneId string
The zone this shape belongs to.
computedAt string<date-time>
When this shape was computed.
chunkSizeMinutes number
The size of each chunk in minutes.
revisionId string
Revision identifier. Changes when the shape is recomputed.
total object
Aggregate across all assets in the zone, regardless of segment. The additivity guarantee holds: total = sum(segments) + unassigned.
Show child attributes
- total.assetCount integer
  The total number of assets in the zone.
- total.startAt string<date-time>
  The timestamp of the first chunk.
- total.endAt string<date-time>
  The timestamp after the last chunk.
- total.chunks array of object
  The forecast chunks aggregated across all assets in the zone.
  Show child attributes
  - total.chunks[].timestamp string<date-time>
    The start timestamp of the chunk.
  - total.chunks[].forecast object
    Forecast attributes for this chunk, with a confidence score.
    Show child attributes
    total.chunks[].forecast.expectedKw number
    The expected mean load in kW.
    total.chunks[].forecast.minimumKw number
    The achievable minimum mean load in kW.
    total.chunks[].forecast.maximumKw number
    The achievable maximum mean load in kW.
    total.chunks[].forecast.confidence number
    Probability that the expectedKw forecast is within a small (configurable) margin of the realized load (0.0-1.0).
segments array of object
One entry per defined segment that has matched households in this zone.
Show child attributes
- segments[].segmentId string<uuid>
  The segment this shape belongs to.
- segments[].name string
  Human-readable segment name.
- segments[].assetCount integer
  The number of assets at households matching this segment.
- segments[].chunks array of object
  The forecast chunks for this segment.
  Show child attributes
  - segments[].chunks[].timestamp string<date-time>
    The start timestamp of the chunk.
  - segments[].chunks[].forecast object
    Forecast attributes for this chunk, with a confidence score.
    Show child attributes
    segments[].chunks[].forecast.expectedKw number
    The expected mean load in kW.
    segments[].chunks[].forecast.minimumKw number
    The achievable minimum mean load in kW.
    segments[].chunks[].forecast.maximumKw number
    The achievable maximum mean load in kW.
    segments[].chunks[].forecast.confidence number
    Probability that the expectedKw forecast is within a small (configurable) margin of the realized load (0.0-1.0).
unassigned object
Assets at households that matched no segment definition.
Show child attributes
- unassigned.assetCount integer
  The number of assets at households that matched no segment.
- unassigned.chunks array of object
  The forecast chunks for unassigned households.
  Show child attributes
  - unassigned.chunks[].timestamp string<date-time>
    The start timestamp of the chunk.
  - unassigned.chunks[].forecast object
    Forecast attributes for this chunk, with a confidence score.
    Show child attributes
    unassigned.chunks[].forecast.expectedKw number
    The expected mean load in kW.
    unassigned.chunks[].forecast.minimumKw number
    The achievable minimum mean load in kW.
    unassigned.chunks[].forecast.maximumKw number
    The achievable maximum mean load in kW.
    unassigned.chunks[].forecast.confidence number
    Probability that the expectedKw forecast is within a small (configurable) margin of the realized load (0.0-1.0).

Response 400

Invalid request parameters.

Response 404

Zone not found or not activated.

Get segment shape

GET /flex/shape/{zoneId}/segments/{segmentId}

Get the flex shape for a single segment within a zone. Useful for integrations that poll one segment on a tight loop or for webhook-driven updates that reference a specific segment.

Request

Path parameters

zoneId string Required

The zone identifier. Corresponds to a market bidding zone (e.g., NO1, BE, SE3).

segmentId string<uuid> Required

The segment identifier.

Query parameters

area string Optional

Comma-separated list of area identifiers. When provided, only households at locations in one of the listed areas are included.

Response 200

Shape retrieved.

Attributes

startAt string<date-time>
The timestamp of the first chunk.
endAt string<date-time>
The timestamp after the last chunk.
chunkSizeMinutes number
The size of each chunk in minutes.
computedAt string<date-time>
When this shape was computed.
assetCount integer
The number of assets at households matching this segment.
revisionId string
Revision identifier. Changes when the shape is recomputed.
chunks array of object
The forecast chunks for this segment.
Show child attributes
- chunks[].timestamp string<date-time>
  The start timestamp of the chunk.
- chunks[].forecast object
  Forecast attributes for this chunk, with a confidence score.
  Show child attributes
  - chunks[].forecast.expectedKw number
    The expected mean load in kW.
  - chunks[].forecast.minimumKw number
    The achievable minimum mean load in kW.
  - chunks[].forecast.maximumKw number
    The achievable maximum mean load in kW.
  - chunks[].forecast.confidence number
    Probability that the expectedKw forecast is within a small (configurable) margin of the realized load (0.0-1.0).

Response 400

Invalid request parameters.

Response 404

Zone or segment not found.

Get flex status

GET /flex/shape/{zoneId}/status

Health indicators for a zone with a per-segment breakdown. Trading systems use these as circuit-breaker inputs to detect unusual or unpredictable behavior.

Request

Path parameters

zoneId string Required

The zone identifier. Corresponds to a market bidding zone (e.g., NO1, BE, SE3).

Response 200

Status retrieved.

Attributes

zoneId string
The zone this status belongs to.
computedAt string<date-time>
When this status was computed.
isForecastStable boolean
Whether the forecast revision variance of near-term horizons is within configured bounds.
isSolvent boolean
Whether the execution engine has sufficient inventory of asset flexibility to fulfill its plans.
isControlNominal boolean
Whether the success rate of asset control actions is within typical expectations.
segments array of object
Per-segment health breakdown.
Show child attributes
- segments[].segmentId string<uuid>
  The segment this status belongs to.
- segments[].name string
  Human-readable segment name.
- segments[].isForecastStable boolean
  Whether the forecast revision variance of near-term horizons is within configured bounds.
- segments[].isSolvent boolean
  Whether the execution engine has sufficient inventory of asset flexibility to fulfill its plans for this segment.
- segments[].isControlNominal boolean
  Whether the success rate of asset control actions is within typical expectations for this segment.

Response 404

Zone not found or not activated.

Flex zones

Zones represent market bidding zones (e.g., NO1, BE, SE3). A zone must be activated before price signals can be pushed or optimization can run. Each zone has a configured currency and contains areas — customer-defined subdivisions used for price signal scoping.

Activate zone

POST /flex/zones/{zoneId}

Activate a zone for flex optimization. Sets the currency used for all price signals and tariff validation in this zone. The zone must have at least one location, and all locations must have an area assigned.

Request

Path parameters

zoneId string Required

The zone identifier. Corresponds to a market bidding zone (e.g., NO1, BE, SE3).

Attributes

currency string Required
The currency for this zone. Both tariffs and price signals must match this currency.

Response 201

Zone activated.

Attributes

id string
The zone identifier. Corresponds to a market bidding zone.
currency string
The configured currency for this zone.
createdAt string<date-time>
When the zone was activated.
updatedAt string<date-time>
When the zone was last updated.

Response 400

Zone cannot be activated. Either no locations exist in the zone, or some locations are missing an area.

Response 409

Zone is already activated.

Get zone

GET /flex/zones/{zoneId}

Get an activated zone by ID.

Request

Path parameters

zoneId string Required

The zone identifier. Corresponds to a market bidding zone (e.g., NO1, BE, SE3).

Response 200

Successful.

Attributes

id string
The zone identifier. Corresponds to a market bidding zone.
currency string
The configured currency for this zone.
createdAt string<date-time>
When the zone was activated.
updatedAt string<date-time>
When the zone was last updated.

Response 404

Zone not found or not activated.

Delete zone

DELETE /flex/zones/{zoneId}

Deactivate a zone. Price signals and optimization will stop for this zone.

Request

Path parameters

zoneId string Required

The zone identifier. Corresponds to a market bidding zone (e.g., NO1, BE, SE3).

Response 204

Zone deactivated.

Response 404

Zone not found or not activated.

List zones

GET /flex/zones

List all activated zones.

Response 200

Successful.

Attributes (list of object)

id string
The zone identifier. Corresponds to a market bidding zone.
currency string
The configured currency for this zone.
createdAt string<date-time>
When the zone was activated.
updatedAt string<date-time>
When the zone was last updated.

List areas in zone

GET /flex/zones/{zoneId}/areas

List all areas in a zone, aggregated from location data. Each area includes a location count and whether a price signal has been pushed. Useful for discovering misconfigured areas or areas missing price signals.

Request

Path parameters

zoneId string Required

The zone identifier. Corresponds to a market bidding zone (e.g., NO1, BE, SE3).

Response 200

Successful.

Attributes

zoneId string
The zone these areas belong to.
areas array of object
The areas in this zone.
Show child attributes
- areas[].areaId string
  The area identifier.
- areas[].locationCount integer
  The number of locations in this area.
- areas[].hasPriceSignal boolean
  Whether a price signal has been pushed for this area.

Response 404

Zone not found or not activated.

Flexible ev charging

Flexible EV Charging allows you to setup constraints for local optimization for your EVs, while providing flexibility to the Flex Shape API.

Create policy

POST /flex/vehicle-policies

Create a new Flexible EV Charging Policy, associated with one location and vehicle pair. Only one policy can be created per unique pair of location and vehicle. A Flex Policy cannot be enabled on a vehicle controlled by other Enode features, like Schedules or Smart Charging.

Creating a Flex Policy will first emit a Flex Policy CreatedAPI, then a Flex Policy StatusAPI event as the Policy Status gets re-calculated.

Request

Attributes

locationId string Required
The ID of the location at which this policy is applied.
vehicleId string Required
The ID of the vehicle for which this policy applies.
batteryReserve number Required
Upon arrival at the location, the vehicle will immediately charge to this battery level without regard to prices or flexibility demands. This charging is reflected in the Policy Status State as SCHEDULE:BATTERY_RESERVE. Must be between 0% and 20%. Note: For Mercedes-Benz vehicles, batteryReserve must be set to 50, as these vehicles always charge to 50% SOC upon plug-in.
schedule object Required
The weekly schedule of Policy settings. The upcoming schedule settings should be read from the Policy Status object, under settings.regularSchedule.
Show child attributes
- schedule.monday object Required
  The schedule settings for a particular day of the week.
  Show child attributes
  - schedule.monday.deadline string Required
    The time of day the user wants their vehicle to be charged by on a specific day of the week.
  - schedule.monday.minimumChargeTarget number Required
    The minimum acceptable battery level the user needs to reach by their deadline on a specific day of the week. The vehicle may, under some circumstances, charge to a higher battery level than the minimumChargeTarget. If the minimumChargeTarget is higher than the vehicle's chargeLimit, the vehicle will charge to the chargeLimit instead. Must be greater than or equal to the batteryReserve. For Mercedes-Benz vehicles, the minimumChargeTarget minimum is 50%, see batteryReserve for more details.
- schedule.tuesday object Required
  The schedule settings for a particular day of the week.
  Show child attributes
  - schedule.tuesday.deadline string Required
    The time of day the user wants their vehicle to be charged by on a specific day of the week.
  - schedule.tuesday.minimumChargeTarget number Required
    The minimum acceptable battery level the user needs to reach by their deadline on a specific day of the week. The vehicle may, under some circumstances, charge to a higher battery level than the minimumChargeTarget. If the minimumChargeTarget is higher than the vehicle's chargeLimit, the vehicle will charge to the chargeLimit instead. Must be greater than or equal to the batteryReserve. For Mercedes-Benz vehicles, the minimumChargeTarget minimum is 50%, see batteryReserve for more details.
- schedule.wednesday object Required
  The schedule settings for a particular day of the week.
  Show child attributes
  - schedule.wednesday.deadline string Required
    The time of day the user wants their vehicle to be charged by on a specific day of the week.
  - schedule.wednesday.minimumChargeTarget number Required
    The minimum acceptable battery level the user needs to reach by their deadline on a specific day of the week. The vehicle may, under some circumstances, charge to a higher battery level than the minimumChargeTarget. If the minimumChargeTarget is higher than the vehicle's chargeLimit, the vehicle will charge to the chargeLimit instead. Must be greater than or equal to the batteryReserve. For Mercedes-Benz vehicles, the minimumChargeTarget minimum is 50%, see batteryReserve for more details.
- schedule.thursday object Required
  The schedule settings for a particular day of the week.
  Show child attributes
  - schedule.thursday.deadline string Required
    The time of day the user wants their vehicle to be charged by on a specific day of the week.
  - schedule.thursday.minimumChargeTarget number Required
    The minimum acceptable battery level the user needs to reach by their deadline on a specific day of the week. The vehicle may, under some circumstances, charge to a higher battery level than the minimumChargeTarget. If the minimumChargeTarget is higher than the vehicle's chargeLimit, the vehicle will charge to the chargeLimit instead. Must be greater than or equal to the batteryReserve. For Mercedes-Benz vehicles, the minimumChargeTarget minimum is 50%, see batteryReserve for more details.
- schedule.friday object Required
  The schedule settings for a particular day of the week.
  Show child attributes
  - schedule.friday.deadline string Required
    The time of day the user wants their vehicle to be charged by on a specific day of the week.
  - schedule.friday.minimumChargeTarget number Required
    The minimum acceptable battery level the user needs to reach by their deadline on a specific day of the week. The vehicle may, under some circumstances, charge to a higher battery level than the minimumChargeTarget. If the minimumChargeTarget is higher than the vehicle's chargeLimit, the vehicle will charge to the chargeLimit instead. Must be greater than or equal to the batteryReserve. For Mercedes-Benz vehicles, the minimumChargeTarget minimum is 50%, see batteryReserve for more details.
- schedule.saturday object Required
  The schedule settings for a particular day of the week.
  Show child attributes
  - schedule.saturday.deadline string Required
    The time of day the user wants their vehicle to be charged by on a specific day of the week.
  - schedule.saturday.minimumChargeTarget number Required
    The minimum acceptable battery level the user needs to reach by their deadline on a specific day of the week. The vehicle may, under some circumstances, charge to a higher battery level than the minimumChargeTarget. If the minimumChargeTarget is higher than the vehicle's chargeLimit, the vehicle will charge to the chargeLimit instead. Must be greater than or equal to the batteryReserve. For Mercedes-Benz vehicles, the minimumChargeTarget minimum is 50%, see batteryReserve for more details.
- schedule.sunday object Required
  The schedule settings for a particular day of the week.
  Show child attributes
  - schedule.sunday.deadline string Required
    The time of day the user wants their vehicle to be charged by on a specific day of the week.
  - schedule.sunday.minimumChargeTarget number Required
    The minimum acceptable battery level the user needs to reach by their deadline on a specific day of the week. The vehicle may, under some circumstances, charge to a higher battery level than the minimumChargeTarget. If the minimumChargeTarget is higher than the vehicle's chargeLimit, the vehicle will charge to the chargeLimit instead. Must be greater than or equal to the batteryReserve. For Mercedes-Benz vehicles, the minimumChargeTarget minimum is 50%, see batteryReserve for more details.

Response 200

Policy created

Attributes

id string
The ID of the flex policy.
vehicleId string
The ID of the vehicle for which this policy applies.
locationId string
The ID of the location at which this policy is applied. When the vehicle is not at this location, the Policy Status State will be UNAVAILABLE.
batteryReserve number
Upon arrival at the location, the vehicle will immediately charge to this battery level without regard to prices or flexibility demands. This charging is reflected in the Policy Status State as SCHEDULE:BATTERY_RESERVE. Must be between 0% and 20%. Note: For Mercedes-Benz vehicles, batteryReserve must be set to 50, as these vehicles always charge to 50% SOC upon plug-in.
lastObservedLocationChargeLimit number
The vehicle's charge limit as last observed at this policy's location. Defaults to 100 until first observed. Used for validating that targets do not exceed the vehicle's charge limit at this location.
schedule object
The weekly schedule of Policy settings. The upcoming schedule settings should be read from the Policy Status object, under settings.regularSchedule.
Show child attributes
- schedule.monday object
  The schedule settings for a particular day of the week.
  Show child attributes
  - schedule.monday.deadline string
    The time of day the user wants their vehicle to be charged by on a specific day of the week.
  - schedule.monday.minimumChargeTarget number
    The minimum acceptable battery level the user needs to reach by their deadline on a specific day of the week. The vehicle may, under some circumstances, charge to a higher battery level than the minimumChargeTarget. If the minimumChargeTarget is higher than the vehicle's chargeLimit, the vehicle will charge to the chargeLimit instead. Must be greater than or equal to the batteryReserve. For Mercedes-Benz vehicles, the minimumChargeTarget minimum is 50%, see batteryReserve for more details.
- schedule.tuesday object
  The schedule settings for a particular day of the week.
  Show child attributes
  - schedule.tuesday.deadline string
    The time of day the user wants their vehicle to be charged by on a specific day of the week.
  - schedule.tuesday.minimumChargeTarget number
    The minimum acceptable battery level the user needs to reach by their deadline on a specific day of the week. The vehicle may, under some circumstances, charge to a higher battery level than the minimumChargeTarget. If the minimumChargeTarget is higher than the vehicle's chargeLimit, the vehicle will charge to the chargeLimit instead. Must be greater than or equal to the batteryReserve. For Mercedes-Benz vehicles, the minimumChargeTarget minimum is 50%, see batteryReserve for more details.
- schedule.wednesday object
  The schedule settings for a particular day of the week.
  Show child attributes
  - schedule.wednesday.deadline string
    The time of day the user wants their vehicle to be charged by on a specific day of the week.
  - schedule.wednesday.minimumChargeTarget number
    The minimum acceptable battery level the user needs to reach by their deadline on a specific day of the week. The vehicle may, under some circumstances, charge to a higher battery level than the minimumChargeTarget. If the minimumChargeTarget is higher than the vehicle's chargeLimit, the vehicle will charge to the chargeLimit instead. Must be greater than or equal to the batteryReserve. For Mercedes-Benz vehicles, the minimumChargeTarget minimum is 50%, see batteryReserve for more details.
- schedule.thursday object
  The schedule settings for a particular day of the week.
  Show child attributes
  - schedule.thursday.deadline string
    The time of day the user wants their vehicle to be charged by on a specific day of the week.
  - schedule.thursday.minimumChargeTarget number
    The minimum acceptable battery level the user needs to reach by their deadline on a specific day of the week. The vehicle may, under some circumstances, charge to a higher battery level than the minimumChargeTarget. If the minimumChargeTarget is higher than the vehicle's chargeLimit, the vehicle will charge to the chargeLimit instead. Must be greater than or equal to the batteryReserve. For Mercedes-Benz vehicles, the minimumChargeTarget minimum is 50%, see batteryReserve for more details.
- schedule.friday object
  The schedule settings for a particular day of the week.
  Show child attributes
  - schedule.friday.deadline string
    The time of day the user wants their vehicle to be charged by on a specific day of the week.
  - schedule.friday.minimumChargeTarget number
    The minimum acceptable battery level the user needs to reach by their deadline on a specific day of the week. The vehicle may, under some circumstances, charge to a higher battery level than the minimumChargeTarget. If the minimumChargeTarget is higher than the vehicle's chargeLimit, the vehicle will charge to the chargeLimit instead. Must be greater than or equal to the batteryReserve. For Mercedes-Benz vehicles, the minimumChargeTarget minimum is 50%, see batteryReserve for more details.
- schedule.saturday object
  The schedule settings for a particular day of the week.
  Show child attributes
  - schedule.saturday.deadline string
    The time of day the user wants their vehicle to be charged by on a specific day of the week.
  - schedule.saturday.minimumChargeTarget number
    The minimum acceptable battery level the user needs to reach by their deadline on a specific day of the week. The vehicle may, under some circumstances, charge to a higher battery level than the minimumChargeTarget. If the minimumChargeTarget is higher than the vehicle's chargeLimit, the vehicle will charge to the chargeLimit instead. Must be greater than or equal to the batteryReserve. For Mercedes-Benz vehicles, the minimumChargeTarget minimum is 50%, see batteryReserve for more details.
- schedule.sunday object
  The schedule settings for a particular day of the week.
  Show child attributes
  - schedule.sunday.deadline string
    The time of day the user wants their vehicle to be charged by on a specific day of the week.
  - schedule.sunday.minimumChargeTarget number
    The minimum acceptable battery level the user needs to reach by their deadline on a specific day of the week. The vehicle may, under some circumstances, charge to a higher battery level than the minimumChargeTarget. If the minimumChargeTarget is higher than the vehicle's chargeLimit, the vehicle will charge to the chargeLimit instead. Must be greater than or equal to the batteryReserve. For Mercedes-Benz vehicles, the minimumChargeTarget minimum is 50%, see batteryReserve for more details.

Response 400

Invalid policy configuration

Response 409

A policy already exists for this vehicle and location pair.

List policies

GET /flex/vehicle-policies

Lists all Flexible EV Charging Policies, optionally filtered by location and/or user. See our Pagination documentationAPI for information on how to paginate the results.

Request

Query parameters

after string Optional

Opaque cursor used to fetch next page. Cannot be set together with before. Refer to PaginationAPI for more information.

before string Optional

Opaque cursor used to fetch previous page. Cannot be used together with after. Refer to PaginationAPI for more information.

pageSize integer Optional

Number of records to return per page. Default page size is 50.

locationId string Optional

userId string Optional

Response 200

Policies retrieved

Attributes

data array of object
Show child attributes
- data[].id string
  The ID of the flex policy.
- data[].vehicleId string
  The ID of the vehicle for which this policy applies.
- data[].locationId string
  The ID of the location at which this policy is applied. When the vehicle is not at this location, the Policy Status State will be UNAVAILABLE.
- data[].batteryReserve number
  Upon arrival at the location, the vehicle will immediately charge to this battery level without regard to prices or flexibility demands. This charging is reflected in the Policy Status State as SCHEDULE:BATTERY_RESERVE. Must be between 0% and 20%. Note: For Mercedes-Benz vehicles, batteryReserve must be set to 50, as these vehicles always charge to 50% SOC upon plug-in.
- data[].lastObservedLocationChargeLimit number
  The vehicle's charge limit as last observed at this policy's location. Defaults to 100 until first observed. Used for validating that targets do not exceed the vehicle's charge limit at this location.
- data[].schedule object
  The weekly schedule of Policy settings. The upcoming schedule settings should be read from the Policy Status object, under settings.regularSchedule.
  Show child attributes
  - data[].schedule.monday object
    The schedule settings for a particular day of the week.
    Show child attributes
    data[].schedule.monday.deadline string
    The time of day the user wants their vehicle to be charged by on a specific day of the week.
    data[].schedule.monday.minimumChargeTarget number
    The minimum acceptable battery level the user needs to reach by their deadline on a specific day of the week. The vehicle may, under some circumstances, charge to a higher battery level than the minimumChargeTarget. If the minimumChargeTarget is higher than the vehicle's chargeLimit, the vehicle will charge to the chargeLimit instead. Must be greater than or equal to the batteryReserve. For Mercedes-Benz vehicles, the minimumChargeTarget minimum is 50%, see batteryReserve for more details.
  - data[].schedule.tuesday object
    The schedule settings for a particular day of the week.
    Show child attributes
    data[].schedule.tuesday.deadline string
    The time of day the user wants their vehicle to be charged by on a specific day of the week.
    data[].schedule.tuesday.minimumChargeTarget number
    The minimum acceptable battery level the user needs to reach by their deadline on a specific day of the week. The vehicle may, under some circumstances, charge to a higher battery level than the minimumChargeTarget. If the minimumChargeTarget is higher than the vehicle's chargeLimit, the vehicle will charge to the chargeLimit instead. Must be greater than or equal to the batteryReserve. For Mercedes-Benz vehicles, the minimumChargeTarget minimum is 50%, see batteryReserve for more details.
  - data[].schedule.wednesday object
    The schedule settings for a particular day of the week.
    Show child attributes
    data[].schedule.wednesday.deadline string
    The time of day the user wants their vehicle to be charged by on a specific day of the week.
    data[].schedule.wednesday.minimumChargeTarget number
    The minimum acceptable battery level the user needs to reach by their deadline on a specific day of the week. The vehicle may, under some circumstances, charge to a higher battery level than the minimumChargeTarget. If the minimumChargeTarget is higher than the vehicle's chargeLimit, the vehicle will charge to the chargeLimit instead. Must be greater than or equal to the batteryReserve. For Mercedes-Benz vehicles, the minimumChargeTarget minimum is 50%, see batteryReserve for more details.
  - data[].schedule.thursday object
    The schedule settings for a particular day of the week.
    Show child attributes
    data[].schedule.thursday.deadline string
    The time of day the user wants their vehicle to be charged by on a specific day of the week.
    data[].schedule.thursday.minimumChargeTarget number
    The minimum acceptable battery level the user needs to reach by their deadline on a specific day of the week. The vehicle may, under some circumstances, charge to a higher battery level than the minimumChargeTarget. If the minimumChargeTarget is higher than the vehicle's chargeLimit, the vehicle will charge to the chargeLimit instead. Must be greater than or equal to the batteryReserve. For Mercedes-Benz vehicles, the minimumChargeTarget minimum is 50%, see batteryReserve for more details.
  - data[].schedule.friday object
    The schedule settings for a particular day of the week.
    Show child attributes
    data[].schedule.friday.deadline string
    The time of day the user wants their vehicle to be charged by on a specific day of the week.
    data[].schedule.friday.minimumChargeTarget number
    The minimum acceptable battery level the user needs to reach by their deadline on a specific day of the week. The vehicle may, under some circumstances, charge to a higher battery level than the minimumChargeTarget. If the minimumChargeTarget is higher than the vehicle's chargeLimit, the vehicle will charge to the chargeLimit instead. Must be greater than or equal to the batteryReserve. For Mercedes-Benz vehicles, the minimumChargeTarget minimum is 50%, see batteryReserve for more details.
  - data[].schedule.saturday object
    The schedule settings for a particular day of the week.
    Show child attributes
    data[].schedule.saturday.deadline string
    The time of day the user wants their vehicle to be charged by on a specific day of the week.
    data[].schedule.saturday.minimumChargeTarget number
    The minimum acceptable battery level the user needs to reach by their deadline on a specific day of the week. The vehicle may, under some circumstances, charge to a higher battery level than the minimumChargeTarget. If the minimumChargeTarget is higher than the vehicle's chargeLimit, the vehicle will charge to the chargeLimit instead. Must be greater than or equal to the batteryReserve. For Mercedes-Benz vehicles, the minimumChargeTarget minimum is 50%, see batteryReserve for more details.
  - data[].schedule.sunday object
    The schedule settings for a particular day of the week.
    Show child attributes
    data[].schedule.sunday.deadline string
    The time of day the user wants their vehicle to be charged by on a specific day of the week.
    data[].schedule.sunday.minimumChargeTarget number
    The minimum acceptable battery level the user needs to reach by their deadline on a specific day of the week. The vehicle may, under some circumstances, charge to a higher battery level than the minimumChargeTarget. If the minimumChargeTarget is higher than the vehicle's chargeLimit, the vehicle will charge to the chargeLimit instead. Must be greater than or equal to the batteryReserve. For Mercedes-Benz vehicles, the minimumChargeTarget minimum is 50%, see batteryReserve for more details.
pagination object
Cursors to the pages before and after current page. See the PaginationAPI section for reference.
Show child attributes
- pagination.after string or null
- pagination.before string or null

Response 400

Invalid query parameters

Get policy

GET /flex/vehicle-policies/{policyId}

Get a Flexible EV Charging Policy

Request

Path parameters

policyId string<uuid> Required

The ID of the flex policy.

Response 200

Policy retrieved

Attributes

id string
The ID of the flex policy.
vehicleId string
The ID of the vehicle for which this policy applies.
locationId string
The ID of the location at which this policy is applied. When the vehicle is not at this location, the Policy Status State will be UNAVAILABLE.
batteryReserve number
Upon arrival at the location, the vehicle will immediately charge to this battery level without regard to prices or flexibility demands. This charging is reflected in the Policy Status State as SCHEDULE:BATTERY_RESERVE. Must be between 0% and 20%. Note: For Mercedes-Benz vehicles, batteryReserve must be set to 50, as these vehicles always charge to 50% SOC upon plug-in.
lastObservedLocationChargeLimit number
The vehicle's charge limit as last observed at this policy's location. Defaults to 100 until first observed. Used for validating that targets do not exceed the vehicle's charge limit at this location.
schedule object
The weekly schedule of Policy settings. The upcoming schedule settings should be read from the Policy Status object, under settings.regularSchedule.
Show child attributes
- schedule.monday object
  The schedule settings for a particular day of the week.
  Show child attributes
  - schedule.monday.deadline string
    The time of day the user wants their vehicle to be charged by on a specific day of the week.
  - schedule.monday.minimumChargeTarget number
    The minimum acceptable battery level the user needs to reach by their deadline on a specific day of the week. The vehicle may, under some circumstances, charge to a higher battery level than the minimumChargeTarget. If the minimumChargeTarget is higher than the vehicle's chargeLimit, the vehicle will charge to the chargeLimit instead. Must be greater than or equal to the batteryReserve. For Mercedes-Benz vehicles, the minimumChargeTarget minimum is 50%, see batteryReserve for more details.
- schedule.tuesday object
  The schedule settings for a particular day of the week.
  Show child attributes
  - schedule.tuesday.deadline string
    The time of day the user wants their vehicle to be charged by on a specific day of the week.
  - schedule.tuesday.minimumChargeTarget number
    The minimum acceptable battery level the user needs to reach by their deadline on a specific day of the week. The vehicle may, under some circumstances, charge to a higher battery level than the minimumChargeTarget. If the minimumChargeTarget is higher than the vehicle's chargeLimit, the vehicle will charge to the chargeLimit instead. Must be greater than or equal to the batteryReserve. For Mercedes-Benz vehicles, the minimumChargeTarget minimum is 50%, see batteryReserve for more details.
- schedule.wednesday object
  The schedule settings for a particular day of the week.
  Show child attributes
  - schedule.wednesday.deadline string
    The time of day the user wants their vehicle to be charged by on a specific day of the week.
  - schedule.wednesday.minimumChargeTarget number
    The minimum acceptable battery level the user needs to reach by their deadline on a specific day of the week. The vehicle may, under some circumstances, charge to a higher battery level than the minimumChargeTarget. If the minimumChargeTarget is higher than the vehicle's chargeLimit, the vehicle will charge to the chargeLimit instead. Must be greater than or equal to the batteryReserve. For Mercedes-Benz vehicles, the minimumChargeTarget minimum is 50%, see batteryReserve for more details.
- schedule.thursday object
  The schedule settings for a particular day of the week.
  Show child attributes
  - schedule.thursday.deadline string
    The time of day the user wants their vehicle to be charged by on a specific day of the week.
  - schedule.thursday.minimumChargeTarget number
    The minimum acceptable battery level the user needs to reach by their deadline on a specific day of the week. The vehicle may, under some circumstances, charge to a higher battery level than the minimumChargeTarget. If the minimumChargeTarget is higher than the vehicle's chargeLimit, the vehicle will charge to the chargeLimit instead. Must be greater than or equal to the batteryReserve. For Mercedes-Benz vehicles, the minimumChargeTarget minimum is 50%, see batteryReserve for more details.
- schedule.friday object
  The schedule settings for a particular day of the week.
  Show child attributes
  - schedule.friday.deadline string
    The time of day the user wants their vehicle to be charged by on a specific day of the week.
  - schedule.friday.minimumChargeTarget number
    The minimum acceptable battery level the user needs to reach by their deadline on a specific day of the week. The vehicle may, under some circumstances, charge to a higher battery level than the minimumChargeTarget. If the minimumChargeTarget is higher than the vehicle's chargeLimit, the vehicle will charge to the chargeLimit instead. Must be greater than or equal to the batteryReserve. For Mercedes-Benz vehicles, the minimumChargeTarget minimum is 50%, see batteryReserve for more details.
- schedule.saturday object
  The schedule settings for a particular day of the week.
  Show child attributes
  - schedule.saturday.deadline string
    The time of day the user wants their vehicle to be charged by on a specific day of the week.
  - schedule.saturday.minimumChargeTarget number
    The minimum acceptable battery level the user needs to reach by their deadline on a specific day of the week. The vehicle may, under some circumstances, charge to a higher battery level than the minimumChargeTarget. If the minimumChargeTarget is higher than the vehicle's chargeLimit, the vehicle will charge to the chargeLimit instead. Must be greater than or equal to the batteryReserve. For Mercedes-Benz vehicles, the minimumChargeTarget minimum is 50%, see batteryReserve for more details.
- schedule.sunday object
  The schedule settings for a particular day of the week.
  Show child attributes
  - schedule.sunday.deadline string
    The time of day the user wants their vehicle to be charged by on a specific day of the week.
  - schedule.sunday.minimumChargeTarget number
    The minimum acceptable battery level the user needs to reach by their deadline on a specific day of the week. The vehicle may, under some circumstances, charge to a higher battery level than the minimumChargeTarget. If the minimumChargeTarget is higher than the vehicle's chargeLimit, the vehicle will charge to the chargeLimit instead. Must be greater than or equal to the batteryReserve. For Mercedes-Benz vehicles, the minimumChargeTarget minimum is 50%, see batteryReserve for more details.

Response 404

Policy not found

Update policy

PATCH /flex/vehicle-policies/{policyId}

Performs a partial update of a Flexible EV Charging Policy. The update will first emit a Flex Policy UpdatedAPI event, then a Flex Policy StatusAPI event as the Policy Status gets re-calculated.

Request

Path parameters

policyId string<uuid> Required

The ID of the flex policy.

Attributes

batteryReserve number Optional
Upon arrival at the location, the vehicle will immediately charge to this battery level without regard to prices or flexibility demands. This charging is reflected in the Policy Status State as SCHEDULE:BATTERY_RESERVE. Must be between 0% and 20%. Note: For Mercedes-Benz vehicles, batteryReserve must be set to 50, as these vehicles always charge to 50% SOC upon plug-in.
schedule object Optional
Show child attributes
- schedule.monday object Optional
  The schedule settings for a particular day of the week.
  Show child attributes
  - schedule.monday.deadline string Required
    The time of day the user wants their vehicle to be charged by on a specific day of the week.
  - schedule.monday.minimumChargeTarget number Required
    The minimum acceptable battery level the user needs to reach by their deadline on a specific day of the week. The vehicle may, under some circumstances, charge to a higher battery level than the minimumChargeTarget. If the minimumChargeTarget is higher than the vehicle's chargeLimit, the vehicle will charge to the chargeLimit instead. Must be greater than or equal to the batteryReserve. For Mercedes-Benz vehicles, the minimumChargeTarget minimum is 50%, see batteryReserve for more details.
- schedule.tuesday object Optional
  The schedule settings for a particular day of the week.
  Show child attributes
  - schedule.tuesday.deadline string Required
    The time of day the user wants their vehicle to be charged by on a specific day of the week.
  - schedule.tuesday.minimumChargeTarget number Required
    The minimum acceptable battery level the user needs to reach by their deadline on a specific day of the week. The vehicle may, under some circumstances, charge to a higher battery level than the minimumChargeTarget. If the minimumChargeTarget is higher than the vehicle's chargeLimit, the vehicle will charge to the chargeLimit instead. Must be greater than or equal to the batteryReserve. For Mercedes-Benz vehicles, the minimumChargeTarget minimum is 50%, see batteryReserve for more details.
- schedule.wednesday object Optional
  The schedule settings for a particular day of the week.
  Show child attributes
  - schedule.wednesday.deadline string Required
    The time of day the user wants their vehicle to be charged by on a specific day of the week.
  - schedule.wednesday.minimumChargeTarget number Required
    The minimum acceptable battery level the user needs to reach by their deadline on a specific day of the week. The vehicle may, under some circumstances, charge to a higher battery level than the minimumChargeTarget. If the minimumChargeTarget is higher than the vehicle's chargeLimit, the vehicle will charge to the chargeLimit instead. Must be greater than or equal to the batteryReserve. For Mercedes-Benz vehicles, the minimumChargeTarget minimum is 50%, see batteryReserve for more details.
- schedule.thursday object Optional
  The schedule settings for a particular day of the week.
  Show child attributes
  - schedule.thursday.deadline string Required
    The time of day the user wants their vehicle to be charged by on a specific day of the week.
  - schedule.thursday.minimumChargeTarget number Required
    The minimum acceptable battery level the user needs to reach by their deadline on a specific day of the week. The vehicle may, under some circumstances, charge to a higher battery level than the minimumChargeTarget. If the minimumChargeTarget is higher than the vehicle's chargeLimit, the vehicle will charge to the chargeLimit instead. Must be greater than or equal to the batteryReserve. For Mercedes-Benz vehicles, the minimumChargeTarget minimum is 50%, see batteryReserve for more details.
- schedule.friday object Optional
  The schedule settings for a particular day of the week.
  Show child attributes
  - schedule.friday.deadline string Required
    The time of day the user wants their vehicle to be charged by on a specific day of the week.
  - schedule.friday.minimumChargeTarget number Required
    The minimum acceptable battery level the user needs to reach by their deadline on a specific day of the week. The vehicle may, under some circumstances, charge to a higher battery level than the minimumChargeTarget. If the minimumChargeTarget is higher than the vehicle's chargeLimit, the vehicle will charge to the chargeLimit instead. Must be greater than or equal to the batteryReserve. For Mercedes-Benz vehicles, the minimumChargeTarget minimum is 50%, see batteryReserve for more details.
- schedule.saturday object Optional
  The schedule settings for a particular day of the week.
  Show child attributes
  - schedule.saturday.deadline string Required
    The time of day the user wants their vehicle to be charged by on a specific day of the week.
  - schedule.saturday.minimumChargeTarget number Required
    The minimum acceptable battery level the user needs to reach by their deadline on a specific day of the week. The vehicle may, under some circumstances, charge to a higher battery level than the minimumChargeTarget. If the minimumChargeTarget is higher than the vehicle's chargeLimit, the vehicle will charge to the chargeLimit instead. Must be greater than or equal to the batteryReserve. For Mercedes-Benz vehicles, the minimumChargeTarget minimum is 50%, see batteryReserve for more details.
- schedule.sunday object Optional
  The schedule settings for a particular day of the week.
  Show child attributes
  - schedule.sunday.deadline string Required
    The time of day the user wants their vehicle to be charged by on a specific day of the week.
  - schedule.sunday.minimumChargeTarget number Required
    The minimum acceptable battery level the user needs to reach by their deadline on a specific day of the week. The vehicle may, under some circumstances, charge to a higher battery level than the minimumChargeTarget. If the minimumChargeTarget is higher than the vehicle's chargeLimit, the vehicle will charge to the chargeLimit instead. Must be greater than or equal to the batteryReserve. For Mercedes-Benz vehicles, the minimumChargeTarget minimum is 50%, see batteryReserve for more details.

Response 200

Policy updated

Attributes

id string
The ID of the flex policy.
vehicleId string
The ID of the vehicle for which this policy applies.
locationId string
The ID of the location at which this policy is applied. When the vehicle is not at this location, the Policy Status State will be UNAVAILABLE.
batteryReserve number
Upon arrival at the location, the vehicle will immediately charge to this battery level without regard to prices or flexibility demands. This charging is reflected in the Policy Status State as SCHEDULE:BATTERY_RESERVE. Must be between 0% and 20%. Note: For Mercedes-Benz vehicles, batteryReserve must be set to 50, as these vehicles always charge to 50% SOC upon plug-in.
lastObservedLocationChargeLimit number
The vehicle's charge limit as last observed at this policy's location. Defaults to 100 until first observed. Used for validating that targets do not exceed the vehicle's charge limit at this location.
schedule object
The weekly schedule of Policy settings. The upcoming schedule settings should be read from the Policy Status object, under settings.regularSchedule.
Show child attributes
- schedule.monday object
  The schedule settings for a particular day of the week.
  Show child attributes
  - schedule.monday.deadline string
    The time of day the user wants their vehicle to be charged by on a specific day of the week.
  - schedule.monday.minimumChargeTarget number
    The minimum acceptable battery level the user needs to reach by their deadline on a specific day of the week. The vehicle may, under some circumstances, charge to a higher battery level than the minimumChargeTarget. If the minimumChargeTarget is higher than the vehicle's chargeLimit, the vehicle will charge to the chargeLimit instead. Must be greater than or equal to the batteryReserve. For Mercedes-Benz vehicles, the minimumChargeTarget minimum is 50%, see batteryReserve for more details.
- schedule.tuesday object
  The schedule settings for a particular day of the week.
  Show child attributes
  - schedule.tuesday.deadline string
    The time of day the user wants their vehicle to be charged by on a specific day of the week.
  - schedule.tuesday.minimumChargeTarget number
    The minimum acceptable battery level the user needs to reach by their deadline on a specific day of the week. The vehicle may, under some circumstances, charge to a higher battery level than the minimumChargeTarget. If the minimumChargeTarget is higher than the vehicle's chargeLimit, the vehicle will charge to the chargeLimit instead. Must be greater than or equal to the batteryReserve. For Mercedes-Benz vehicles, the minimumChargeTarget minimum is 50%, see batteryReserve for more details.
- schedule.wednesday object
  The schedule settings for a particular day of the week.
  Show child attributes
  - schedule.wednesday.deadline string
    The time of day the user wants their vehicle to be charged by on a specific day of the week.
  - schedule.wednesday.minimumChargeTarget number
    The minimum acceptable battery level the user needs to reach by their deadline on a specific day of the week. The vehicle may, under some circumstances, charge to a higher battery level than the minimumChargeTarget. If the minimumChargeTarget is higher than the vehicle's chargeLimit, the vehicle will charge to the chargeLimit instead. Must be greater than or equal to the batteryReserve. For Mercedes-Benz vehicles, the minimumChargeTarget minimum is 50%, see batteryReserve for more details.
- schedule.thursday object
  The schedule settings for a particular day of the week.
  Show child attributes
  - schedule.thursday.deadline string
    The time of day the user wants their vehicle to be charged by on a specific day of the week.
  - schedule.thursday.minimumChargeTarget number
    The minimum acceptable battery level the user needs to reach by their deadline on a specific day of the week. The vehicle may, under some circumstances, charge to a higher battery level than the minimumChargeTarget. If the minimumChargeTarget is higher than the vehicle's chargeLimit, the vehicle will charge to the chargeLimit instead. Must be greater than or equal to the batteryReserve. For Mercedes-Benz vehicles, the minimumChargeTarget minimum is 50%, see batteryReserve for more details.
- schedule.friday object
  The schedule settings for a particular day of the week.
  Show child attributes
  - schedule.friday.deadline string
    The time of day the user wants their vehicle to be charged by on a specific day of the week.
  - schedule.friday.minimumChargeTarget number
    The minimum acceptable battery level the user needs to reach by their deadline on a specific day of the week. The vehicle may, under some circumstances, charge to a higher battery level than the minimumChargeTarget. If the minimumChargeTarget is higher than the vehicle's chargeLimit, the vehicle will charge to the chargeLimit instead. Must be greater than or equal to the batteryReserve. For Mercedes-Benz vehicles, the minimumChargeTarget minimum is 50%, see batteryReserve for more details.
- schedule.saturday object
  The schedule settings for a particular day of the week.
  Show child attributes
  - schedule.saturday.deadline string
    The time of day the user wants their vehicle to be charged by on a specific day of the week.
  - schedule.saturday.minimumChargeTarget number
    The minimum acceptable battery level the user needs to reach by their deadline on a specific day of the week. The vehicle may, under some circumstances, charge to a higher battery level than the minimumChargeTarget. If the minimumChargeTarget is higher than the vehicle's chargeLimit, the vehicle will charge to the chargeLimit instead. Must be greater than or equal to the batteryReserve. For Mercedes-Benz vehicles, the minimumChargeTarget minimum is 50%, see batteryReserve for more details.
- schedule.sunday object
  The schedule settings for a particular day of the week.
  Show child attributes
  - schedule.sunday.deadline string
    The time of day the user wants their vehicle to be charged by on a specific day of the week.
  - schedule.sunday.minimumChargeTarget number
    The minimum acceptable battery level the user needs to reach by their deadline on a specific day of the week. The vehicle may, under some circumstances, charge to a higher battery level than the minimumChargeTarget. If the minimumChargeTarget is higher than the vehicle's chargeLimit, the vehicle will charge to the chargeLimit instead. Must be greater than or equal to the batteryReserve. For Mercedes-Benz vehicles, the minimumChargeTarget minimum is 50%, see batteryReserve for more details.

Response 400

Invalid policy update

Response 404

Policy not found

Delete policy

DELETE /flex/vehicle-policies/{policyId}

Deletes a Flexible EV Charging Policy. The deletion will first emit a Flex Policy DeletedAPI event, then a Flex Policy StatusAPI event as the Policy Status gets re-calculated.

Request

Path parameters

policyId string<uuid> Required

The ID of the flex policy.

Response 204

Policy deleted

Response 404

Policy not found

Get policy status

GET /flex/vehicle-policies/{policyId}/status

Read the latest status of a Policy. The Policy Status object is a realtime representation of a Policy and the associated vehicle's state. Flex Policy StatusAPI events are emitted when the status changes, which can happen at any time.

Request

Path parameters

policyId string<uuid> Required

The ID of the flex policy.

Response 200

Status retrieved

Attributes

updatedAt string<date-time>
The timestamp of the last update to the flex policy.
policyId string
The ID of the policy.
locationId string
The ID of the location.
vehicleId string
The ID of the vehicle.
state string
The state of the flex policy.
- UNAVAILABLE: The vehicle is unavailable for Flexible EV Charging for some reason, for example, because it is not plugged in, or not the Policy's location.
- IMMEDIATE:OVERRIDE: The vehicle is charging to some target battery level because of a temporary override.
- SCHEDULE:BATTERY_RESERVE: The vehicle is charging to a battery reserve level, and will stop after reaching that level.
- SCHEDULE:REGULAR: The vehicle is following the regular schedule and actively participating in Flexible EV Charging.
- SCHEDULE:OVERRIDE: The vehicle is following a schedule override, and is still actively participating in Flexible EV Charging.
- SCHEDULE:INFLEXIBLE: The vehicle doesn't have enough time to charge to the target battery level, so there isn't any opportunity to flex the charging.
Possible enum values:
batteryReserve number
Upon arrival at the location, the vehicle will immediately charge to this battery level without regard to prices or flexibility demands. This charging is reflected in the Policy Status State as SCHEDULE:BATTERY_RESERVE. Must be between 0% and 20%. Note: For Mercedes-Benz vehicles, batteryReserve must be set to 50, as these vehicles always charge to 50% SOC upon plug-in.
settings object
Show child attributes
- settings.regularSchedule object
  Today's schedule settings, resolved from the weekly schedule.
  Show child attributes
  - settings.regularSchedule.deadline string or null
    The time of day the user wants their vehicle to be charged by on a specific day of the week.
  - settings.regularSchedule.readyBy string<date-time>
    The upcoming deadline represented as a RFC3339 UTC timestamp.
  - settings.regularSchedule.minimumChargeTarget number or null
    The minimum acceptable battery level the user needs to reach by their deadline on a specific day of the week. The vehicle may, under some circumstances, charge to a higher battery level than the minimumChargeTarget. If the minimumChargeTarget is higher than the vehicle's chargeLimit, the vehicle will charge to the chargeLimit instead. Must be greater than or equal to the batteryReserve. For Mercedes-Benz vehicles, the minimumChargeTarget minimum is 50%, see batteryReserve for more details.
- settings.override
  An override applied to a Flex Policy, shown as a part of the Flex Status entity. The override is either a next-day schedule override or an immediate start override.
  Show child attributes
  settings.override.type string
  Possible enum values:
  UPCOMING_SCHEDULE
  settings.override.readyBy string<date-time>
  The timestamp at which the user wants their vehicle to be charged by. Overrides the upcoming deadline set in the Flex Policy. Must be in the future.
  settings.override.minimumChargeTarget number
  The minimum acceptable battery level the user needs to reach by their deadline on a specific day of the week. The vehicle may, under some circumstances, charge to a higher battery level than the minimumChargeTarget. If the minimumChargeTarget is higher than the vehicle's chargeLimit, the vehicle will charge to the chargeLimit instead. Must be greater than or equal to the batteryReserve. For Mercedes-Benz vehicles, the minimumChargeTarget minimum is 50%, see batteryReserve for more details.
session object
An object containing information about the vehicle's current plug session.
Show child attributes
- session.blocks array of object
  Show child attributes
  - session.blocks[].statusState string
    The state of the Policy Status during this charging block.
    Possible enum values:
    UNAVAILABLEIMMEDIATE:OVERRIDESCHEDULE:BATTERY_RESERVESCHEDULE:REGULARSCHEDULE:OVERRIDESCHEDULE:INFLEXIBLE
  - session.blocks[].estimatedStartAt string<date-time>
    The estimated start time of the charging block.
  - session.blocks[].estimatedEndAt string<date-time>
    The estimated end time of the charging block.

Response 404

Policy not found, or the status has not been computed yet.

Create policy override

POST /flex/vehicle-policies/{policyId}/overrides

Creates a new Policy Override.

Overrides are temporary, and automatically expire when the vehicle reaches the target battery level.

An immediate start override forces a car to immediately start charging to the specified target battery level.

An upcoming schedule override allows the user to set a custom ready-by time and/or target for the upcoming session. Either one or both of the fields (readyBy and minimumChargeTarget) must be set.

Flex Policy StatusAPI events are emitted upon override creation and expiry.

Request

Path parameters

policyId string<uuid> Required

The ID of the flex policy.

Attributes

type string Required
Possible enum values:
target number Required
The target batteryLevel to immediately charge up to. Must be less than or equal to the vehicle's chargeLimit. Charging sessions resulting from this override are reflected in the Policy Status State as IMMEDIATE:OVERRIDE.

Response 204

Override created

Response 400

Invalid override

Response 404

Policy not found

Response 409

An override for this policy already exists.

Get policy override

GET /flex/vehicle-policies/{policyId}/overrides

Get the active override for a Flexible EV Charging Policy.

Request

Path parameters

policyId string<uuid> Required

The ID of the flex policy.

Response 200

Override retrieved

Attributes

type string
Possible enum values:
target number
The target batteryLevel to immediately charge up to. Must be less than or equal to the vehicle's chargeLimit. Charging sessions resulting from this override are reflected in the Policy Status State as IMMEDIATE:OVERRIDE.

Response 404

Override not found

Delete policy override

DELETE /flex/vehicle-policies/{policyId}/overrides

Deletes a Policy Override. The deletion will emit a Flex Policy StatusAPI event as the Policy Status gets re-calculated.

Request

Path parameters

policyId string<uuid> Required

The ID of the flex policy.

Response 204

Override deleted

Response 404

Override not found

Get charging report

GET /flex/vehicle-policies/charging-report

Generates a report of kWh charged per Policy Status State, intended to be used for end-user invoice creation. Includes all charging sessions for policies specified by the filters.

Request

Query parameters

startDate string<date-time> Required

Start day of the report in local time, inclusive. RFC3339 timestamp. Hour, minute, and second components are ignored.

endDate string<date-time> Required

End day of the report in local time, exclusive. RFC3339 timestamp. Hour, minute, and second components are ignored.

resolution string Optional

The resolution of the report. Default is 'DAY'.

Default value: DAY

Possible enum values:

DAY

MONTH

locationId string<uuid> Required

The locationId of the policies to be included in the report.

vehicleId string Required

The vehicleId to generate the report for.

Response 200

Charging report retrieved

Attributes (list of object)

date string<date-time>
Day or month (depending on the report resolution) in local time. RFC3339 timestamp.
states object
An object describing the amount of energy consumed in each state for this day.
Show child attributes
- states.UNAVAILABLE number
- states.IMMEDIATE:OVERRIDE number
- states.SCHEDULE:BATTERY_RESERVE number
- states.SCHEDULE:REGULAR number
- states.SCHEDULE:OVERRIDE number
- states.SCHEDULE:INFLEXIBLE number

Response 400

Invalid report parameters

Response 404

No policies found matching the specified filters.

Get policy charging report

GET /flex/vehicle-policies/{policyId}/charging-report

Generates a report of kWh charged per Policy Status State, intended to be used for end-user invoice creation. Includes all charging sessions for the specified policy.

Request

Path parameters

policyId string<uuid> Required

The ID of the flex policy.

Query parameters

startDate string<date-time> Required

Start day of the report in local time, inclusive. RFC3339 timestamp. Hour, minute, and second components are ignored.

endDate string<date-time> Required

End day of the report in local time, exclusive. RFC3339 timestamp. Hour, minute, and second components are ignored.

resolution string Optional

The resolution of the report. Default is 'DAY'.

Default value: DAY

Possible enum values:

DAY

MONTH

Response 200

Charging report retrieved

Attributes (list of object)

date string<date-time>
Day or month (depending on the report resolution) in local time. RFC3339 timestamp.
states object
An object describing the amount of energy consumed in each state for this day.
Show child attributes
- states.UNAVAILABLE number
- states.IMMEDIATE:OVERRIDE number
- states.SCHEDULE:BATTERY_RESERVE number
- states.SCHEDULE:REGULAR number
- states.SCHEDULE:OVERRIDE number
- states.SCHEDULE:INFLEXIBLE number

Response 400

Invalid report parameters

Response 404

Policy not found

Flexible ev charging sessions

Flexible EV Charging Sessions provide visibility into a vehicle's charging session lifecycle, including real-time targets, outcomes, charge blocks, and energy delivery statistics.

List settled sessions

GET /flex/vehicle-policies/sessions

Lists settled Flexible EV Charging Sessions, optionally filtered by policy, location, or vehicle. When filtering by vehicleId, each real-world charging event appears once — the managed session is returned if one exists, otherwise the unmanaged session. See our Pagination documentationAPI for information on how to paginate the results.

Request

Query parameters

after string Optional

Opaque cursor used to fetch next page. Cannot be set together with before. Refer to PaginationAPI for more information.

before string Optional

Opaque cursor used to fetch previous page. Cannot be used together with after. Refer to PaginationAPI for more information.

pageSize integer Optional

Number of records to return per page. Default page size is 50.

from string<date-time> Optional

Return sessions with a pluggedInAt at or after this time.

to string<date-time> Optional

Return sessions with a pluggedOutAt at or before this time.

policyId string<uuid> Optional

Filter sessions by policy ID.

locationId string<uuid> Optional

Filter sessions by location ID.

vehicleId string<uuid> Optional

Filter sessions by vehicle ID. Each real-world charging event appears once — the managed session is returned if one exists, otherwise the unmanaged session.

Response 200

Sessions retrieved

Attributes

data array of object
Show child attributes
- data[].id string<uuid>
  The unique identifier for this session.
- data[].state string
  Possible enum values:
- data[].policyId string<uuid> or null
  The unique identifier for the policy associated with this session.
- data[].pluggedInAt string<date-time>
  The date and time when the vehicle was plugged in.
- data[].pluggedOutAt string<date-time>
  The date and time when the vehicle was unplugged.
- data[].blocks array of object
  Discrete windows of active charging that occurred during the session.
  Show child attributes
  - data[].blocks[].type string
    The type of charge block.
    Possible enum values:
    BATTERY_RESERVEREGULARIMMEDIATE_START
  - data[].blocks[].kwhSum number
    The total energy delivered during this block in kWh. For completed and in-progress blocks, this is the actual energy delivered. For future (tentative) blocks, this is the system's estimate.
  - data[].blocks[].startAt string<date-time>
    While ACTIVE, this is when the block started (if past) or is tentatively planned to start (if future). While SETTLED, this is when the block actually started.
  - data[].blocks[].endAt string<date-time>
    While ACTIVE, this is when the block ended (if past) or is tentatively planned to end (if future). While SETTLED, this is when the block actually ended.
- data[].statistics object
  Energy delivery statistics for the session.
  Show child attributes
  - data[].statistics.aggregated object
    Aggregated statistics for the session.
    Show child attributes
    data[].statistics.aggregated.kwhSum number or null
    The total amount of energy charged in kWh.
    data[].statistics.aggregated.batteryFrom number
    The battery percentage at the start of the session.
    data[].statistics.aggregated.batteryTo number
    The final battery percentage.
  - data[].statistics.timeseries array of object
    15-minute interval energy delivery data for the session.
    Show child attributes
    data[].statistics.timeseries[].startAt string<date-time>
    The start of this 15-minute interval.
    data[].statistics.timeseries[].kwh number
    The energy delivered in kWh over this 15-minute interval.
- data[].target object
  What the system is charging towards for this session.
  Show child attributes
  - data[].target.latest
    The latest target configuration. Null for unmanaged sessions (e.g. public charging) where the system did not control the charge. Use type to distinguish between REGULAR and IMMEDIATE_START targets.
    Show child attributes
    data[].target.latest.id integer
    Incrementing identifier for this target within the session.
    data[].target.latest.type string
    Possible enum values:
    REGULAR
    data[].target.latest.source string
    Whether this target follows the default policy or a user override.
    Possible enum values:
    POLICYUSER_OVERRIDE
    data[].target.latest.batteryReserve number
    The battery reserve percentage. Charging to this level is always prioritised.
    data[].target.latest.minimumChargeTarget number
    The minimum charge target as a battery percentage.
    data[].target.latest.readyBy string<date-time>
    The time by which the minimum charge target should be reached.
- data[].outcome object
  Whether the target will be met for this session.
  Show child attributes
  - data[].outcome.latest
    The final outcome assessment. Null for unmanaged sessions. Use type to distinguish between REGULAR and IMMEDIATE_START outcomes, then state to distinguish ON_TARGET from OFF_TARGET within regular outcomes.
    Show child attributes
- data[].error object
  Error state for this session.
  Show child attributes
  - data[].error.latest
    The latest error state. Null when there is no active error. Use type to identify the error kind.
    Show child attributes
    data[].error.latest.type string
    Possible enum values:
    START_FAIL
pagination object
Cursors to the pages before and after current page. See the PaginationAPI section for reference.
Show child attributes
- pagination.after string or null
- pagination.before string or null

Response 400

Invalid query parameters

Get active session

GET /flex/vehicle-policies/{policyId}/session

Get the current active or upcoming Flexible EV Charging Session for a policy. The session provides real-time visibility into what the system is charging towards (target), whether it will succeed (outcome), the actual charge windows (blocks), and energy delivery data (statistics).

Request

Path parameters

policyId string<uuid> Required

The ID of the vehicle policy.

Response 200

Session retrieved

Attributes

state string
The current state of the session.
- UPCOMING: Initial state, created shortly after the previous session has settled.
- ACTIVE:BATTERY_RESERVE: Vehicle is plugged in, charging to maintain battery reserve.
- ACTIVE:REGULAR: Vehicle is plugged in, smart charging according to schedule.
- ACTIVE:IMMEDIATE_START: Vehicle is plugged in, charging immediately.
Possible enum values:
policyId string<uuid> or null
The unique identifier for the policy associated with this session.
pluggedInAt string<date-time>
The date and time when the vehicle was plugged in.
pluggedOutAt null
Always null. The vehicle has not been unplugged yet.
blocks array of object
Discrete windows of active charging within the session. Empty while UPCOMING. While ACTIVE, blocks represent a mix of past charging and planned future charging — past blocks are final, future blocks are tentative and may shift as the schedule re-optimizes.
Show child attributes
- blocks[].type string
  The type of charge block.
  Possible enum values:
- blocks[].kwhSum number
  The total energy delivered during this block in kWh. For completed and in-progress blocks, this is the actual energy delivered. For future (tentative) blocks, this is the system's estimate.
- blocks[].startAt string<date-time>
  While ACTIVE, this is when the block started (if past) or is tentatively planned to start (if future). While SETTLED, this is when the block actually started.
- blocks[].endAt string<date-time>
  While ACTIVE, this is when the block ended (if past) or is tentatively planned to end (if future). While SETTLED, this is when the block actually ended.
statistics object
Energy delivery statistics for the session.
Show child attributes
- statistics.aggregated object or null
  Aggregated statistics for the session. Null while UPCOMING.
  Show child attributes
  - statistics.aggregated.kwhSum number or null
    The total amount of energy charged in kWh.
  - statistics.aggregated.batteryFrom number
    The battery percentage at the start of the session.
  - statistics.aggregated.batteryTo number
    The current battery percentage while ACTIVE, or the final battery percentage when SETTLED.
- statistics.timeseries array of object
  15-minute interval energy delivery data. Empty while UPCOMING.
  Show child attributes
  - statistics.timeseries[].startAt string<date-time>
    The start of this 15-minute interval.
  - statistics.timeseries[].kwh number
    The energy delivered in kWh over this 15-minute interval.
target object
What the system is charging towards for this session.
Show child attributes
- target.latest
  The latest target configuration. Null for unmanaged sessions (e.g. public charging) where the system did not control the charge. Use type to distinguish between REGULAR and IMMEDIATE_START targets.
  Show child attributes
  target.latest.id integer
  Incrementing identifier for this target within the session.
  target.latest.type string
  Possible enum values:
  REGULAR
  target.latest.source string
  Whether this target follows the default policy or a user override.
  Possible enum values:
  POLICYUSER_OVERRIDE
  target.latest.batteryReserve number
  The battery reserve percentage. Charging to this level is always prioritised.
  target.latest.minimumChargeTarget number
  The minimum charge target as a battery percentage.
  target.latest.readyBy string<date-time>
  The time by which the minimum charge target should be reached.
outcome object
Whether the target will be met for this session.
Show child attributes
- outcome.latest
  The latest outcome assessment. Null before the first estimate is available. Use type to distinguish between REGULAR and IMMEDIATE_START outcomes, then state to distinguish ON_TARGET from OFF_TARGET within regular outcomes.
  Show child attributes
error object
Error state for this session.
Show child attributes
- error.latest
  The latest error state. Null when there is no active error. Use type to identify the error kind.
  Show child attributes
  error.latest.type string
  Possible enum values:
  START_FAIL

Response 404

Session not found

Get settled session

GET /flex/vehicle-policies/{policyId}/sessions/{sessionId}

Get a settled Flexible EV Charging Session, either managed or unmanaged. The session provides the actual charge windows (blocks), energy delivery data (statistics), and final outcome.

Request

Path parameters

policyId string<uuid> Required

The ID of the vehicle policy.

sessionId string<uuid> Required

The ID of the session.

Response 200

Session retrieved

Attributes

id string<uuid>
The unique identifier for this session.
state string
Possible enum values:
policyId string<uuid> or null
The unique identifier for the policy associated with this session.
pluggedInAt string<date-time>
The date and time when the vehicle was plugged in.
pluggedOutAt string<date-time>
The date and time when the vehicle was unplugged.
blocks array of object
Discrete windows of active charging that occurred during the session.
Show child attributes
- blocks[].type string
  The type of charge block.
  Possible enum values:
- blocks[].kwhSum number
  The total energy delivered during this block in kWh. For completed and in-progress blocks, this is the actual energy delivered. For future (tentative) blocks, this is the system's estimate.
- blocks[].startAt string<date-time>
  While ACTIVE, this is when the block started (if past) or is tentatively planned to start (if future). While SETTLED, this is when the block actually started.
- blocks[].endAt string<date-time>
  While ACTIVE, this is when the block ended (if past) or is tentatively planned to end (if future). While SETTLED, this is when the block actually ended.
statistics object
Energy delivery statistics for the session.
Show child attributes
- statistics.aggregated object
  Aggregated statistics for the session.
  Show child attributes
  - statistics.aggregated.kwhSum number or null
    The total amount of energy charged in kWh.
  - statistics.aggregated.batteryFrom number
    The battery percentage at the start of the session.
  - statistics.aggregated.batteryTo number
    The final battery percentage.
- statistics.timeseries array of object
  15-minute interval energy delivery data for the session.
  Show child attributes
  - statistics.timeseries[].startAt string<date-time>
    The start of this 15-minute interval.
  - statistics.timeseries[].kwh number
    The energy delivered in kWh over this 15-minute interval.
target object
What the system is charging towards for this session.
Show child attributes
- target.latest
  The latest target configuration. Null for unmanaged sessions (e.g. public charging) where the system did not control the charge. Use type to distinguish between REGULAR and IMMEDIATE_START targets.
  Show child attributes
  target.latest.id integer
  Incrementing identifier for this target within the session.
  target.latest.type string
  Possible enum values:
  REGULAR
  target.latest.source string
  Whether this target follows the default policy or a user override.
  Possible enum values:
  POLICYUSER_OVERRIDE
  target.latest.batteryReserve number
  The battery reserve percentage. Charging to this level is always prioritised.
  target.latest.minimumChargeTarget number
  The minimum charge target as a battery percentage.
  target.latest.readyBy string<date-time>
  The time by which the minimum charge target should be reached.
outcome object
Whether the target will be met for this session.
Show child attributes
- outcome.latest
  The final outcome assessment. Null for unmanaged sessions. Use type to distinguish between REGULAR and IMMEDIATE_START outcomes, then state to distinguish ON_TARGET from OFF_TARGET within regular outcomes.
  Show child attributes
error object
Error state for this session.
Show child attributes
- error.latest
  The latest error state. Null when there is no active error. Use type to identify the error kind.
  Show child attributes
  error.latest.type string
  Possible enum values:
  START_FAIL

Response 404

Session not found

Solar configurations

Solar Configurations describe the physical characteristics of a solar installation. These characteristics are used to forecast solar generation and to enable solar charging of vehicles.

Create solar configuration

POST /solar-configurations

Create a Solar Configuration for a given location. A location may have multiple Solar Configurations to represent individual arrays of panels (for example, varying azimuths or tilt).

Request

Attributes

capacity number Required
Peak capacity in kilowatts (kWp) of the solar system
azimuth number or null Required
Compass direction the solar panels face, measured in degrees relative to true north. Valid values are 0–359, where 0 = north, 90 = east, 180 = south, and 270 = west.
tilt number or null Required
Vertical angle of the solar panels in degrees from the horizontal plane. Values range from 0–90, where 0 = horizontal and 90 = vertical.
userId string Required
The userId associated with this solar configuration
locationId string<uuid> Required
The locationId associated with this solar configuration

Response 201

Created

Attributes

capacity number
Peak capacity in kilowatts (kWp) of the solar system
azimuth number or null
Compass direction the solar panels face, measured in degrees relative to true north. Valid values are 0–359, where 0 = north, 90 = east, 180 = south, and 270 = west.
tilt number or null
Vertical angle of the solar panels in degrees from the horizontal plane. Values range from 0–90, where 0 = horizontal and 90 = vertical.
id string<uuid>
The ID of this Solar Configuration
userId string
The userId associated with this solar configuration
locationId string<uuid>
The locationId associated with this solar configuration
createdAt string<date-time>
Time when this Solar Configuration was created
updatedAt string<date-time>
Time when this Solar Configuration was last updated

Response 400

Location does not belong to user

Response 404

User or location not found

Response 409

A solar configuration with the same parameters already exists

List solar configurations

GET /solar-configurations

Returns a paginated list of all Solar Configurations.

Request

Query parameters

after string Optional

Opaque cursor used to fetch next page. Cannot be set together with before. Refer to PaginationAPI for more information.

before string Optional

Opaque cursor used to fetch previous page. Cannot be used together with after. Refer to PaginationAPI for more information.

pageSize integer Optional

Number of records to return per page. Default page size is 50.

Response 200

Attributes

data array of object
List of solar configurations
Show child attributes
- data[].capacity number
  Peak capacity in kilowatts (kWp) of the solar system
- data[].azimuth number or null
  Compass direction the solar panels face, measured in degrees relative to true north. Valid values are 0–359, where 0 = north, 90 = east, 180 = south, and 270 = west.
- data[].tilt number or null
  Vertical angle of the solar panels in degrees from the horizontal plane. Values range from 0–90, where 0 = horizontal and 90 = vertical.
- data[].id string<uuid>
  The ID of this Solar Configuration
- data[].userId string
  The userId associated with this solar configuration
- data[].locationId string<uuid>
  The locationId associated with this solar configuration
- data[].createdAt string<date-time>
  Time when this Solar Configuration was created
- data[].updatedAt string<date-time>
  Time when this Solar Configuration was last updated
pagination object
Cursors to the pages before and after current page. See the PaginationAPI section for reference.
Show child attributes
- pagination.after string or null
- pagination.before string or null

Response 400

Invalid pagination parameters

Get solar configuration

GET /solar-configurations/{solarConfigurationId}

Get a Solar Configuration by ID.

Request

Path parameters

solarConfigurationId string<uuid> Required

ID of the Solar Configuration.

Response 200

Attributes

capacity number
Peak capacity in kilowatts (kWp) of the solar system
azimuth number or null
Compass direction the solar panels face, measured in degrees relative to true north. Valid values are 0–359, where 0 = north, 90 = east, 180 = south, and 270 = west.
tilt number or null
Vertical angle of the solar panels in degrees from the horizontal plane. Values range from 0–90, where 0 = horizontal and 90 = vertical.
id string<uuid>
The ID of this Solar Configuration
userId string
The userId associated with this solar configuration
locationId string<uuid>
The locationId associated with this solar configuration
createdAt string<date-time>
Time when this Solar Configuration was created
updatedAt string<date-time>
Time when this Solar Configuration was last updated

Response 404

Solar configuration not found

Update solar configuration

PATCH /solar-configurations/{solarConfigurationId}

Update a Solar Configuration by ID.

Request

Path parameters

solarConfigurationId string<uuid> Required

ID of the Solar Configuration.

Attributes

capacity number Optional
Peak capacity in kilowatts (kWp) of the solar system
azimuth number or null Optional
Compass direction the solar panels face, measured in degrees relative to true north. Valid values are 0–359, where 0 = north, 90 = east, 180 = south, and 270 = west.
tilt number or null Optional
Vertical angle of the solar panels in degrees from the horizontal plane. Values range from 0–90, where 0 = horizontal and 90 = vertical.

Response 200

Attributes

capacity number
Peak capacity in kilowatts (kWp) of the solar system
azimuth number or null
Compass direction the solar panels face, measured in degrees relative to true north. Valid values are 0–359, where 0 = north, 90 = east, 180 = south, and 270 = west.
tilt number or null
Vertical angle of the solar panels in degrees from the horizontal plane. Values range from 0–90, where 0 = horizontal and 90 = vertical.
id string<uuid>
The ID of this Solar Configuration
userId string
The userId associated with this solar configuration
locationId string<uuid>
The locationId associated with this solar configuration
createdAt string<date-time>
Time when this Solar Configuration was created
updatedAt string<date-time>
Time when this Solar Configuration was last updated

Response 400

Invalid request

Response 404

Solar configuration not found

Delete solar configuration

DELETE /solar-configurations/{solarConfigurationId}

Delete a Solar Configuration by ID.

Request

Path parameters

solarConfigurationId string<uuid> Required

ID of the Solar Configuration.

Response 204

Successfully deleted

Response 404

Solar configuration not found

Tariffs

Tariffs combine a schedule with a set of rates to define the cost of energy usage based on the time of day and day of the week.

List tariffs

GET /flex/tariffs

List all tariffs. Supports pagination.

Request

Query parameters

after string Optional

Opaque cursor used to fetch next page. Cannot be set together with before. Refer to PaginationAPI for more information.

before string Optional

Opaque cursor used to fetch previous page. Cannot be used together with after. Refer to PaginationAPI for more information.

pageSize integer Optional

Number of records to return per page. Default page size is 50.

Response 200

Attributes

data array of object
Show child attributes
- data[].id string
  Unique identifier for the tariff.
- data[].direction string
  The direction of energy flow. 'import' is for electricity consumption costs, 'export' is for feed-in/selling electricity back to the grid.
  Possible enum values:
- data[].currency string
  ISO 4217 currency code. Present for tariffs with per 'kWh', absent for scalar tariffs.
- data[].per string
  The unit of the tariff. 'kWh' indicates a rate in currency per kilowatt-hour (e.g., 0.28 EUR/kWh). 'scalar' indicates a dimensionless multiplier used in formulas (e.g., 1.15 for a 15% markup).
  Possible enum values:
- data[].createdAt string<date-time>
  When the tariff was created.
- data[].updatedAt string<date-time>
  When the tariff was last updated.
pagination object
Cursors to the pages before and after current page. See the PaginationAPI section for reference.
Show child attributes
- pagination.after string or null
- pagination.before string or null

Create tariff

POST /flex/tariffs/{tariffId}

Create a tariff. The tariff ID is client-provided. If a tariff with the same ID and definition already exists, the existing tariff is returned. A newly created tariff is empty — push rate data separately via the timeseries endpoint.

Request

Path parameters

tariffId string Required

Unique identifier for the tariff.

Attributes

direction string Required
The direction of energy flow. 'import' is for electricity consumption costs, 'export' is for feed-in/selling electricity back to the grid.
Possible enum values:
currency string Optional
ISO 4217 currency code. Required when 'per' is 'kWh'. Omit when 'per' is 'scalar'.
per string Required
The unit of the tariff. 'kWh' indicates a rate in currency per kilowatt-hour (e.g., 0.28 EUR/kWh). 'scalar' indicates a dimensionless multiplier used in formulas (e.g., 1.15 for a 15% markup).
Possible enum values:

Response 200

A tariff with this ID and definition already exists. The existing tariff is returned.

Attributes

id string
Unique identifier for the tariff.
direction string
The direction of energy flow. 'import' is for electricity consumption costs, 'export' is for feed-in/selling electricity back to the grid.
Possible enum values:
currency string
ISO 4217 currency code. Present for tariffs with per 'kWh', absent for scalar tariffs.
per string
The unit of the tariff. 'kWh' indicates a rate in currency per kilowatt-hour (e.g., 0.28 EUR/kWh). 'scalar' indicates a dimensionless multiplier used in formulas (e.g., 1.15 for a 15% markup).
Possible enum values:
createdAt string<date-time>
When the tariff was created.
updatedAt string<date-time>
When the tariff was last updated.

Response 201

Tariff created successfully.

Attributes

id string
Unique identifier for the tariff.
direction string
The direction of energy flow. 'import' is for electricity consumption costs, 'export' is for feed-in/selling electricity back to the grid.
Possible enum values:
currency string
ISO 4217 currency code. Present for tariffs with per 'kWh', absent for scalar tariffs.
per string
The unit of the tariff. 'kWh' indicates a rate in currency per kilowatt-hour (e.g., 0.28 EUR/kWh). 'scalar' indicates a dimensionless multiplier used in formulas (e.g., 1.15 for a 15% markup).
Possible enum values:
createdAt string<date-time>
When the tariff was created.
updatedAt string<date-time>
When the tariff was last updated.

Response 409

A tariff with this ID already exists with a different definition.

Get tariff

GET /flex/tariffs/{tariffId}

Get a tariff by ID.

Request

Path parameters

tariffId string Required

Unique identifier for the tariff.

Response 200

Attributes

id string
Unique identifier for the tariff.
direction string
The direction of energy flow. 'import' is for electricity consumption costs, 'export' is for feed-in/selling electricity back to the grid.
Possible enum values:
currency string
ISO 4217 currency code. Present for tariffs with per 'kWh', absent for scalar tariffs.
per string
The unit of the tariff. 'kWh' indicates a rate in currency per kilowatt-hour (e.g., 0.28 EUR/kWh). 'scalar' indicates a dimensionless multiplier used in formulas (e.g., 1.15 for a 15% markup).
Possible enum values:
createdAt string<date-time>
When the tariff was created.
updatedAt string<date-time>
When the tariff was last updated.

Response 404

Tariff not found.

Delete tariff

DELETE /flex/tariffs/{tariffId}

Delete a tariff and all its data. A tariff cannot be deleted if it is referenced by any location's formula.

Request

Path parameters

tariffId string Required

Unique identifier for the tariff.

Response 204

Tariff deleted successfully.

Response 404

Tariff not found.

Response 409

Tariff is referenced by one or more location formulas and cannot be deleted.

Get tariff timeseries

GET /flex/tariffs/{tariffId}/timeseries

Get a tariff's rate data as a timeseries over a time range. The from and to parameters are local dates. The timezoneName parameter is required to interpret the date boundaries and annotate response values with UTC offsets.

Request

Path parameters

tariffId string Required

Unique identifier for the tariff.

Query parameters

from string<date> Required

Start of the time range (local date).

to string<date> Required

End of the time range (local date).

timezoneName string Required

IANA timezone name. Required to interpret the local time boundaries and annotate response values with UTC offsets.

Response 200

Attributes

tariffId string
Unique identifier for the tariff.
direction string
The direction of energy flow. 'import' is for electricity consumption costs, 'export' is for feed-in/selling electricity back to the grid.
Possible enum values:
currency string
ISO 4217 currency code. Present for kWh tariffs, absent for scalar tariffs.
per string
The unit of the tariff. 'kWh' indicates a rate in currency per kilowatt-hour (e.g., 0.28 EUR/kWh). 'scalar' indicates a dimensionless multiplier used in formulas (e.g., 1.15 for a 15% markup).
Possible enum values:
from string<date>
Start of the queried time range (local date).
to string<date>
End of the queried time range (local date).
timezoneName string
IANA timezone name used for the query.
values array of object
The timeseries values marking rate changes. Each value indicates the rate from that timestamp until the next value (or until 'to'). Values are ordered chronologically.
Show child attributes
- values[].at string<date-time>
  Timezone-aware timestamp when this rate becomes effective. The rate applies from this point until the next value (or until the window end).
- values[].rate number
  The rate value. For kWh tariffs, this is in currency per kilowatt-hour. For scalar tariffs, this is a dimensionless value.

Response 400

Invalid query parameters. The time range may be outside the tariff's available data range.

Response 404

Tariff not found.

Push tariff timeseries data

PUT /flex/tariffs/{tariffId}/timeseries

Push rate data to a tariff. Replaces all data in the window [firstValue.at, to) with the provided values. Each value defines a step function rate from its timestamp until the next value. The first value must start at least 1 hour in the future. Timestamps must be timezone-aware (ISO 8601 with UTC offset). An Idempotency-Key header is required to deduplicate client retries. Completed idempotency records are retained for 24 hours, while in-progress locks expire after 3 minutes.

Request

Path parameters

tariffId string Required

Unique identifier for the tariff.

Attributes

to string<date-time> Required
End of the replacement window (exclusive). All existing data in [firstValue.at, to) is replaced with the provided values. Data outside this window is untouched.
values array of object Required
The timeseries values for this window. At least one value is required. Values must be ordered chronologically. Each value defines the rate from its timestamp until the next value (or until 'to'). The first value's 'at' defines the start of the replacement window.
Show child attributes
- values[].at string<date-time> Required
  Timezone-aware timestamp when this rate becomes effective. The rate applies from this point until the next value (or until the window end).
- values[].rate number Required
  The rate value. For kWh tariffs, this is in currency per kilowatt-hour. For scalar tariffs, this is a dimensionless value.

Response 204

Timeseries data replaced successfully.

Response 400

Invalid request. Idempotency-Key may be missing/invalid, values must be ordered chronologically, at least one value is required, timestamps may be invalid, or the push window starts less than 1 hour in the future.

Response 404

Tariff not found.

Response 409

Conflict. The provided Idempotency-Key is currently in use for an in-flight request.

Response 422

Unprocessable Entity. The provided Idempotency-Key has already been used with a different payload.

Response 429

Overwrite budget exceeded. This push would overwrite more existing data points than the 24-hour budget allows.

Get location tariff formula

GET /flex/locations/{locationId}/tariff-formula

Get the tariff formula for a location and direction.

Request

Path parameters

locationId string<uuid> Required

ID of the Location.

Query parameters

direction string Required

The energy direction of the formula to retrieve.

Possible enum values:

import

export

Response 200

Attributes

locationId string<uuid>
The location this formula belongs to.
direction string
The direction of energy flow. 'import' is for electricity consumption costs, 'export' is for feed-in/selling electricity back to the grid.
Possible enum values:
variables object
Maps variable names to tariff IDs. Variables can then be referenced in the formula expression.
formula string
A formula expression that combines tariffs to compute the final rate.
Syntax:
- Variable references: use names defined in the variables mapping (e.g., spot, grid)
- Decimal literals: numbers like 0.03, 1.15
- Operators: + (add), - (subtract/negate), * (multiply), / (divide)
- Grouping: parentheses for precedence (a + b) * c
- Functions: min(a, b), max(a, b), clamp(x, lo, hi), abs(x), round(x, n)
Dimensional rules:
- The formula must evaluate to a rate (currency/kWh)
- Rate + Rate → Rate
- Rate - Rate → Rate
- Scalar × Rate → Rate
- Rate × Rate → Invalid
- Scalar + Rate → Invalid
Examples:
- spot — use spot price directly
- 1.15 * spot — 15% markup on spot
- spot / 1000 — convert from MWh to kWh
- clamp(spot, 0, 0.50) — spot price clamped between 0 and 0.50
- max(spot, 0) * markup + grid + 0.02 — floored spot with markup, grid fee, and margin
- round(spot + grid, 4) — round to 4 decimal places

Response 404

Location or formula not found.

Set location tariff formula

POST /flex/locations/{locationId}/tariff-formula

Create or replace the tariff formula for a location and direction. The formula defines how tariffs are combined to compute the final rate. The API validates formula syntax, dimensional correctness, and that all referenced tariffs exist and share the same currency and direction.

Request

Path parameters

locationId string<uuid> Required

ID of the Location.

Attributes

direction string Required
The direction of energy flow. 'import' is for electricity consumption costs, 'export' is for feed-in/selling electricity back to the grid.
Possible enum values:
variables object Required
Maps variable names to tariff IDs. Variables can then be referenced in the formula expression.
formula string Required
A formula expression that combines tariffs to compute the final rate.
Syntax:
- Variable references: use names defined in the variables mapping (e.g., spot, grid)
- Decimal literals: numbers like 0.03, 1.15
- Operators: + (add), - (subtract/negate), * (multiply), / (divide)
- Grouping: parentheses for precedence (a + b) * c
- Functions: min(a, b), max(a, b), clamp(x, lo, hi), abs(x), round(x, n)
Dimensional rules:
- The formula must evaluate to a rate (currency/kWh)
- Rate + Rate → Rate
- Rate - Rate → Rate
- Scalar × Rate → Rate
- Rate × Rate → Invalid
- Scalar + Rate → Invalid
Examples:
- spot — use spot price directly
- 1.15 * spot — 15% markup on spot
- spot / 1000 — convert from MWh to kWh
- clamp(spot, 0, 0.50) — spot price clamped between 0 and 0.50
- max(spot, 0) * markup + grid + 0.02 — floored spot with markup, grid fee, and margin
- round(spot + grid, 4) — round to 4 decimal places

Response 200

Formula set successfully.

Attributes

locationId string<uuid>
The location this formula belongs to.
direction string
The direction of energy flow. 'import' is for electricity consumption costs, 'export' is for feed-in/selling electricity back to the grid.
Possible enum values:
variables object
Maps variable names to tariff IDs. Variables can then be referenced in the formula expression.
formula string
A formula expression that combines tariffs to compute the final rate.
Syntax:
- Variable references: use names defined in the variables mapping (e.g., spot, grid)
- Decimal literals: numbers like 0.03, 1.15
- Operators: + (add), - (subtract/negate), * (multiply), / (divide)
- Grouping: parentheses for precedence (a + b) * c
- Functions: min(a, b), max(a, b), clamp(x, lo, hi), abs(x), round(x, n)
Dimensional rules:
- The formula must evaluate to a rate (currency/kWh)
- Rate + Rate → Rate
- Rate - Rate → Rate
- Scalar × Rate → Rate
- Rate × Rate → Invalid
- Scalar + Rate → Invalid
Examples:
- spot — use spot price directly
- 1.15 * spot — 15% markup on spot
- spot / 1000 — convert from MWh to kWh
- clamp(spot, 0, 0.50) — spot price clamped between 0 and 0.50
- max(spot, 0) * markup + grid + 0.02 — floored spot with markup, grid fee, and margin
- round(spot + grid, 4) — round to 4 decimal places

Response 400

Invalid formula. The formula may have syntax errors, reference non-existent tariffs, have invalid dimensional analysis (e.g., adding a scalar to a rate), or reference tariffs with mismatched currencies or directions.

Response 404

Location not found.

Delete location tariff formula

DELETE /flex/locations/{locationId}/tariff-formula

Delete the tariff formula for a location and direction.

Request

Path parameters

locationId string<uuid> Required

ID of the Location.

Query parameters

direction string Required

The direction of the formula to delete.

Possible enum values:

import

export

Response 204

Formula deleted successfully.

Response 404

Location or formula not found.

Get resolved tariffs

GET /flex/locations/{locationId}/tariffs/resolved

Evaluate the location's tariff formula over a time range and return the computed rate at each interval. Interval timestamps include UTC offsets for unambiguous DST handling. Unresolved intervals indicate where tariff data is missing. Supports cursor pagination with pageSize, after, and before.

Request

Path parameters

locationId string<uuid> Required

ID of the Location.

Query parameters

from string<date> Required

Start of the time range to resolve (local date).

to string<date> Required

End of the time range to resolve (local date).

direction string Required

The energy direction to resolve.

Possible enum values:

import

export

after string Optional

Opaque cursor used to fetch next page. Cannot be set together with before. Refer to PaginationAPI for more information.

before string Optional

Opaque cursor used to fetch previous page. Cannot be used together with after. Refer to PaginationAPI for more information.

pageSize integer Optional

Number of records to return per page. Default page size is 50.

Response 200

Attributes

locationId string<uuid>
The location these resolved tariffs are for.
direction string
The direction of energy flow. 'import' is for electricity consumption costs, 'export' is for feed-in/selling electricity back to the grid.
Possible enum values:
currency string
ISO 4217 currency code of the resolved rate.
per string
The energy unit. Resolved tariffs are always rates in currency per kWh.
Possible enum values:
from string<date>
Start of the resolved time range (local date).
to string<date>
End of the resolved time range (local date).
timezoneName string
IANA timezone name used to resolve local date boundaries and annotate interval timestamps.
intervals array
The time intervals with their rates. Intervals are contiguous and non-overlapping. Resolved intervals contain computed rates; unresolved intervals indicate missing data.
pagination object
Cursors to the pages before and after current page. See the PaginationAPI section for reference.
Show child attributes
- pagination.after string or null
- pagination.before string or null

Response 400

Invalid query parameters.

Response 404

Location not found or no formula configured for the specified direction.

Webhook events

flex:vehicle-policy:created

Occurs whenever a Flex vehicle policy is created.

Request

Attributes

createdAt string<date-time> Required
ISO8601 UTC timestamp
version string Required
API version of the payload
user object Required
Show child attributes
- user.id string Required
  User ID
event string Required
Possible enum values:
policy object Required
Flex Policy
Show child attributes
- policy.id string Required
  The ID of the flex policy.
- policy.vehicleId string Required
  The ID of the vehicle for which this policy applies.
- policy.locationId string Required
  The ID of the location at which this policy is applied. When the vehicle is not at this location, the Policy Status State will be UNAVAILABLE.
- policy.batteryReserve number Required
  Upon arrival at the location, the vehicle will immediately charge to this battery level without regard to prices or flexibility demands. This charging is reflected in the Policy Status State as SCHEDULE:BATTERY_RESERVE. Must be between 0% and 20%. Note: For Mercedes-Benz vehicles, batteryReserve must be set to 50, as these vehicles always charge to 50% SOC upon plug-in.
- policy.lastObservedLocationChargeLimit number Required
  The vehicle's charge limit as last observed at this policy's location. Defaults to 100 until first observed. Used for validating that targets do not exceed the vehicle's charge limit at this location.
- policy.schedule object Required
  The weekly schedule of Policy settings. The upcoming schedule settings should be read from the Policy Status object, under settings.regularSchedule.
  Show child attributes
  - policy.schedule.monday object Required
    The schedule settings for a particular day of the week.
    Show child attributes
    policy.schedule.monday.deadline string Required
    The time of day the user wants their vehicle to be charged by on a specific day of the week.
    policy.schedule.monday.minimumChargeTarget number Required
    The minimum acceptable battery level the user needs to reach by their deadline on a specific day of the week. The vehicle may, under some circumstances, charge to a higher battery level than the minimumChargeTarget. If the minimumChargeTarget is higher than the vehicle's chargeLimit, the vehicle will charge to the chargeLimit instead. Must be greater than or equal to the batteryReserve. For Mercedes-Benz vehicles, the minimumChargeTarget minimum is 50%, see batteryReserve for more details.
  - policy.schedule.tuesday object Required
    The schedule settings for a particular day of the week.
    Show child attributes
    policy.schedule.tuesday.deadline string Required
    The time of day the user wants their vehicle to be charged by on a specific day of the week.
    policy.schedule.tuesday.minimumChargeTarget number Required
    The minimum acceptable battery level the user needs to reach by their deadline on a specific day of the week. The vehicle may, under some circumstances, charge to a higher battery level than the minimumChargeTarget. If the minimumChargeTarget is higher than the vehicle's chargeLimit, the vehicle will charge to the chargeLimit instead. Must be greater than or equal to the batteryReserve. For Mercedes-Benz vehicles, the minimumChargeTarget minimum is 50%, see batteryReserve for more details.
  - policy.schedule.wednesday object Required
    The schedule settings for a particular day of the week.
    Show child attributes
    policy.schedule.wednesday.deadline string Required
    The time of day the user wants their vehicle to be charged by on a specific day of the week.
    policy.schedule.wednesday.minimumChargeTarget number Required
    The minimum acceptable battery level the user needs to reach by their deadline on a specific day of the week. The vehicle may, under some circumstances, charge to a higher battery level than the minimumChargeTarget. If the minimumChargeTarget is higher than the vehicle's chargeLimit, the vehicle will charge to the chargeLimit instead. Must be greater than or equal to the batteryReserve. For Mercedes-Benz vehicles, the minimumChargeTarget minimum is 50%, see batteryReserve for more details.
  - policy.schedule.thursday object Required
    The schedule settings for a particular day of the week.
    Show child attributes
    policy.schedule.thursday.deadline string Required
    The time of day the user wants their vehicle to be charged by on a specific day of the week.
    policy.schedule.thursday.minimumChargeTarget number Required
    The minimum acceptable battery level the user needs to reach by their deadline on a specific day of the week. The vehicle may, under some circumstances, charge to a higher battery level than the minimumChargeTarget. If the minimumChargeTarget is higher than the vehicle's chargeLimit, the vehicle will charge to the chargeLimit instead. Must be greater than or equal to the batteryReserve. For Mercedes-Benz vehicles, the minimumChargeTarget minimum is 50%, see batteryReserve for more details.
  - policy.schedule.friday object Required
    The schedule settings for a particular day of the week.
    Show child attributes
    policy.schedule.friday.deadline string Required
    The time of day the user wants their vehicle to be charged by on a specific day of the week.
    policy.schedule.friday.minimumChargeTarget number Required
    The minimum acceptable battery level the user needs to reach by their deadline on a specific day of the week. The vehicle may, under some circumstances, charge to a higher battery level than the minimumChargeTarget. If the minimumChargeTarget is higher than the vehicle's chargeLimit, the vehicle will charge to the chargeLimit instead. Must be greater than or equal to the batteryReserve. For Mercedes-Benz vehicles, the minimumChargeTarget minimum is 50%, see batteryReserve for more details.
  - policy.schedule.saturday object Required
    The schedule settings for a particular day of the week.
    Show child attributes
    policy.schedule.saturday.deadline string Required
    The time of day the user wants their vehicle to be charged by on a specific day of the week.
    policy.schedule.saturday.minimumChargeTarget number Required
    The minimum acceptable battery level the user needs to reach by their deadline on a specific day of the week. The vehicle may, under some circumstances, charge to a higher battery level than the minimumChargeTarget. If the minimumChargeTarget is higher than the vehicle's chargeLimit, the vehicle will charge to the chargeLimit instead. Must be greater than or equal to the batteryReserve. For Mercedes-Benz vehicles, the minimumChargeTarget minimum is 50%, see batteryReserve for more details.
  - policy.schedule.sunday object Required
    The schedule settings for a particular day of the week.
    Show child attributes
    policy.schedule.sunday.deadline string Required
    The time of day the user wants their vehicle to be charged by on a specific day of the week.
    policy.schedule.sunday.minimumChargeTarget number Required
    The minimum acceptable battery level the user needs to reach by their deadline on a specific day of the week. The vehicle may, under some circumstances, charge to a higher battery level than the minimumChargeTarget. If the minimumChargeTarget is higher than the vehicle's chargeLimit, the vehicle will charge to the chargeLimit instead. Must be greater than or equal to the batteryReserve. For Mercedes-Benz vehicles, the minimumChargeTarget minimum is 50%, see batteryReserve for more details.

Response 200

The subscriber should return 200 OK to acknowledge the webhook has been received

flex:vehicle-policy:updated

Occurs whenever a Flex vehicle policy is updated.

Request

Attributes

createdAt string<date-time> Required
ISO8601 UTC timestamp
version string Required
API version of the payload
user object Required
Show child attributes
- user.id string Required
  User ID
event string Required
Possible enum values:
policy object Required
Flex Policy
Show child attributes
- policy.id string Required
  The ID of the flex policy.
- policy.vehicleId string Required
  The ID of the vehicle for which this policy applies.
- policy.locationId string Required
  The ID of the location at which this policy is applied. When the vehicle is not at this location, the Policy Status State will be UNAVAILABLE.
- policy.batteryReserve number Required
  Upon arrival at the location, the vehicle will immediately charge to this battery level without regard to prices or flexibility demands. This charging is reflected in the Policy Status State as SCHEDULE:BATTERY_RESERVE. Must be between 0% and 20%. Note: For Mercedes-Benz vehicles, batteryReserve must be set to 50, as these vehicles always charge to 50% SOC upon plug-in.
- policy.lastObservedLocationChargeLimit number Required
  The vehicle's charge limit as last observed at this policy's location. Defaults to 100 until first observed. Used for validating that targets do not exceed the vehicle's charge limit at this location.
- policy.schedule object Required
  The weekly schedule of Policy settings. The upcoming schedule settings should be read from the Policy Status object, under settings.regularSchedule.
  Show child attributes
  - policy.schedule.monday object Required
    The schedule settings for a particular day of the week.
    Show child attributes
    policy.schedule.monday.deadline string Required
    The time of day the user wants their vehicle to be charged by on a specific day of the week.
    policy.schedule.monday.minimumChargeTarget number Required
    The minimum acceptable battery level the user needs to reach by their deadline on a specific day of the week. The vehicle may, under some circumstances, charge to a higher battery level than the minimumChargeTarget. If the minimumChargeTarget is higher than the vehicle's chargeLimit, the vehicle will charge to the chargeLimit instead. Must be greater than or equal to the batteryReserve. For Mercedes-Benz vehicles, the minimumChargeTarget minimum is 50%, see batteryReserve for more details.
  - policy.schedule.tuesday object Required
    The schedule settings for a particular day of the week.
    Show child attributes
    policy.schedule.tuesday.deadline string Required
    The time of day the user wants their vehicle to be charged by on a specific day of the week.
    policy.schedule.tuesday.minimumChargeTarget number Required
    The minimum acceptable battery level the user needs to reach by their deadline on a specific day of the week. The vehicle may, under some circumstances, charge to a higher battery level than the minimumChargeTarget. If the minimumChargeTarget is higher than the vehicle's chargeLimit, the vehicle will charge to the chargeLimit instead. Must be greater than or equal to the batteryReserve. For Mercedes-Benz vehicles, the minimumChargeTarget minimum is 50%, see batteryReserve for more details.
  - policy.schedule.wednesday object Required
    The schedule settings for a particular day of the week.
    Show child attributes
    policy.schedule.wednesday.deadline string Required
    The time of day the user wants their vehicle to be charged by on a specific day of the week.
    policy.schedule.wednesday.minimumChargeTarget number Required
    The minimum acceptable battery level the user needs to reach by their deadline on a specific day of the week. The vehicle may, under some circumstances, charge to a higher battery level than the minimumChargeTarget. If the minimumChargeTarget is higher than the vehicle's chargeLimit, the vehicle will charge to the chargeLimit instead. Must be greater than or equal to the batteryReserve. For Mercedes-Benz vehicles, the minimumChargeTarget minimum is 50%, see batteryReserve for more details.
  - policy.schedule.thursday object Required
    The schedule settings for a particular day of the week.
    Show child attributes
    policy.schedule.thursday.deadline string Required
    The time of day the user wants their vehicle to be charged by on a specific day of the week.
    policy.schedule.thursday.minimumChargeTarget number Required
    The minimum acceptable battery level the user needs to reach by their deadline on a specific day of the week. The vehicle may, under some circumstances, charge to a higher battery level than the minimumChargeTarget. If the minimumChargeTarget is higher than the vehicle's chargeLimit, the vehicle will charge to the chargeLimit instead. Must be greater than or equal to the batteryReserve. For Mercedes-Benz vehicles, the minimumChargeTarget minimum is 50%, see batteryReserve for more details.
  - policy.schedule.friday object Required
    The schedule settings for a particular day of the week.
    Show child attributes
    policy.schedule.friday.deadline string Required
    The time of day the user wants their vehicle to be charged by on a specific day of the week.
    policy.schedule.friday.minimumChargeTarget number Required
    The minimum acceptable battery level the user needs to reach by their deadline on a specific day of the week. The vehicle may, under some circumstances, charge to a higher battery level than the minimumChargeTarget. If the minimumChargeTarget is higher than the vehicle's chargeLimit, the vehicle will charge to the chargeLimit instead. Must be greater than or equal to the batteryReserve. For Mercedes-Benz vehicles, the minimumChargeTarget minimum is 50%, see batteryReserve for more details.
  - policy.schedule.saturday object Required
    The schedule settings for a particular day of the week.
    Show child attributes
    policy.schedule.saturday.deadline string Required
    The time of day the user wants their vehicle to be charged by on a specific day of the week.
    policy.schedule.saturday.minimumChargeTarget number Required
    The minimum acceptable battery level the user needs to reach by their deadline on a specific day of the week. The vehicle may, under some circumstances, charge to a higher battery level than the minimumChargeTarget. If the minimumChargeTarget is higher than the vehicle's chargeLimit, the vehicle will charge to the chargeLimit instead. Must be greater than or equal to the batteryReserve. For Mercedes-Benz vehicles, the minimumChargeTarget minimum is 50%, see batteryReserve for more details.
  - policy.schedule.sunday object Required
    The schedule settings for a particular day of the week.
    Show child attributes
    policy.schedule.sunday.deadline string Required
    The time of day the user wants their vehicle to be charged by on a specific day of the week.
    policy.schedule.sunday.minimumChargeTarget number Required
    The minimum acceptable battery level the user needs to reach by their deadline on a specific day of the week. The vehicle may, under some circumstances, charge to a higher battery level than the minimumChargeTarget. If the minimumChargeTarget is higher than the vehicle's chargeLimit, the vehicle will charge to the chargeLimit instead. Must be greater than or equal to the batteryReserve. For Mercedes-Benz vehicles, the minimumChargeTarget minimum is 50%, see batteryReserve for more details.
updatedFields array of string Required

Response 200

The subscriber should return 200 OK to acknowledge the webhook has been received

flex:vehicle-policy:deleted

Occurs whenever a Flex vehicle policy is deleted.

Request

Attributes

createdAt string<date-time> Required
ISO8601 UTC timestamp
version string Required
API version of the payload
user object Required
Show child attributes
- user.id string Required
  User ID
event string Required
Possible enum values:
policy object Required
Flex Policy
Show child attributes
- policy.id string Required
  The ID of the flex policy.
- policy.vehicleId string Required
  The ID of the vehicle for which this policy applies.
- policy.locationId string Required
  The ID of the location at which this policy is applied. When the vehicle is not at this location, the Policy Status State will be UNAVAILABLE.
- policy.batteryReserve number Required
  Upon arrival at the location, the vehicle will immediately charge to this battery level without regard to prices or flexibility demands. This charging is reflected in the Policy Status State as SCHEDULE:BATTERY_RESERVE. Must be between 0% and 20%. Note: For Mercedes-Benz vehicles, batteryReserve must be set to 50, as these vehicles always charge to 50% SOC upon plug-in.
- policy.lastObservedLocationChargeLimit number Required
  The vehicle's charge limit as last observed at this policy's location. Defaults to 100 until first observed. Used for validating that targets do not exceed the vehicle's charge limit at this location.
- policy.schedule object Required
  The weekly schedule of Policy settings. The upcoming schedule settings should be read from the Policy Status object, under settings.regularSchedule.
  Show child attributes
  - policy.schedule.monday object Required
    The schedule settings for a particular day of the week.
    Show child attributes
    policy.schedule.monday.deadline string Required
    The time of day the user wants their vehicle to be charged by on a specific day of the week.
    policy.schedule.monday.minimumChargeTarget number Required
    The minimum acceptable battery level the user needs to reach by their deadline on a specific day of the week. The vehicle may, under some circumstances, charge to a higher battery level than the minimumChargeTarget. If the minimumChargeTarget is higher than the vehicle's chargeLimit, the vehicle will charge to the chargeLimit instead. Must be greater than or equal to the batteryReserve. For Mercedes-Benz vehicles, the minimumChargeTarget minimum is 50%, see batteryReserve for more details.
  - policy.schedule.tuesday object Required
    The schedule settings for a particular day of the week.
    Show child attributes
    policy.schedule.tuesday.deadline string Required
    The time of day the user wants their vehicle to be charged by on a specific day of the week.
    policy.schedule.tuesday.minimumChargeTarget number Required
    The minimum acceptable battery level the user needs to reach by their deadline on a specific day of the week. The vehicle may, under some circumstances, charge to a higher battery level than the minimumChargeTarget. If the minimumChargeTarget is higher than the vehicle's chargeLimit, the vehicle will charge to the chargeLimit instead. Must be greater than or equal to the batteryReserve. For Mercedes-Benz vehicles, the minimumChargeTarget minimum is 50%, see batteryReserve for more details.
  - policy.schedule.wednesday object Required
    The schedule settings for a particular day of the week.
    Show child attributes
    policy.schedule.wednesday.deadline string Required
    The time of day the user wants their vehicle to be charged by on a specific day of the week.
    policy.schedule.wednesday.minimumChargeTarget number Required
    The minimum acceptable battery level the user needs to reach by their deadline on a specific day of the week. The vehicle may, under some circumstances, charge to a higher battery level than the minimumChargeTarget. If the minimumChargeTarget is higher than the vehicle's chargeLimit, the vehicle will charge to the chargeLimit instead. Must be greater than or equal to the batteryReserve. For Mercedes-Benz vehicles, the minimumChargeTarget minimum is 50%, see batteryReserve for more details.
  - policy.schedule.thursday object Required
    The schedule settings for a particular day of the week.
    Show child attributes
    policy.schedule.thursday.deadline string Required
    The time of day the user wants their vehicle to be charged by on a specific day of the week.
    policy.schedule.thursday.minimumChargeTarget number Required
    The minimum acceptable battery level the user needs to reach by their deadline on a specific day of the week. The vehicle may, under some circumstances, charge to a higher battery level than the minimumChargeTarget. If the minimumChargeTarget is higher than the vehicle's chargeLimit, the vehicle will charge to the chargeLimit instead. Must be greater than or equal to the batteryReserve. For Mercedes-Benz vehicles, the minimumChargeTarget minimum is 50%, see batteryReserve for more details.
  - policy.schedule.friday object Required
    The schedule settings for a particular day of the week.
    Show child attributes
    policy.schedule.friday.deadline string Required
    The time of day the user wants their vehicle to be charged by on a specific day of the week.
    policy.schedule.friday.minimumChargeTarget number Required
    The minimum acceptable battery level the user needs to reach by their deadline on a specific day of the week. The vehicle may, under some circumstances, charge to a higher battery level than the minimumChargeTarget. If the minimumChargeTarget is higher than the vehicle's chargeLimit, the vehicle will charge to the chargeLimit instead. Must be greater than or equal to the batteryReserve. For Mercedes-Benz vehicles, the minimumChargeTarget minimum is 50%, see batteryReserve for more details.
  - policy.schedule.saturday object Required
    The schedule settings for a particular day of the week.
    Show child attributes
    policy.schedule.saturday.deadline string Required
    The time of day the user wants their vehicle to be charged by on a specific day of the week.
    policy.schedule.saturday.minimumChargeTarget number Required
    The minimum acceptable battery level the user needs to reach by their deadline on a specific day of the week. The vehicle may, under some circumstances, charge to a higher battery level than the minimumChargeTarget. If the minimumChargeTarget is higher than the vehicle's chargeLimit, the vehicle will charge to the chargeLimit instead. Must be greater than or equal to the batteryReserve. For Mercedes-Benz vehicles, the minimumChargeTarget minimum is 50%, see batteryReserve for more details.
  - policy.schedule.sunday object Required
    The schedule settings for a particular day of the week.
    Show child attributes
    policy.schedule.sunday.deadline string Required
    The time of day the user wants their vehicle to be charged by on a specific day of the week.
    policy.schedule.sunday.minimumChargeTarget number Required
    The minimum acceptable battery level the user needs to reach by their deadline on a specific day of the week. The vehicle may, under some circumstances, charge to a higher battery level than the minimumChargeTarget. If the minimumChargeTarget is higher than the vehicle's chargeLimit, the vehicle will charge to the chargeLimit instead. Must be greater than or equal to the batteryReserve. For Mercedes-Benz vehicles, the minimumChargeTarget minimum is 50%, see batteryReserve for more details.

Response 200

The subscriber should return 200 OK to acknowledge the webhook has been received

flex:vehicle-policy:status

Occurs whenever a Flex vehicle policy's status is updated.

Request

Attributes

createdAt string<date-time> Required
ISO8601 UTC timestamp
version string Required
API version of the payload
user object Required
Show child attributes
- user.id string Required
  User ID
event string Required
Possible enum values:
policyStatus object Required
A view of the current flex policy settings, including any active overrides.
Show child attributes
- policyStatus.updatedAt string<date-time> Required
  The timestamp of the last update to the flex policy.
- policyStatus.policyId string Required
  The ID of the policy.
- policyStatus.locationId string Required
  The ID of the location.
- policyStatus.vehicleId string Required
  The ID of the vehicle.
- policyStatus.state string Required
  The state of the flex policy.
  - UNAVAILABLE: The vehicle is unavailable for Flexible EV Charging for some reason, for example, because it is not plugged in, or not the Policy's location.
  - IMMEDIATE:OVERRIDE: The vehicle is charging to some target battery level because of a temporary override.
  - SCHEDULE:BATTERY_RESERVE: The vehicle is charging to a battery reserve level, and will stop after reaching that level.
  - SCHEDULE:REGULAR: The vehicle is following the regular schedule and actively participating in Flexible EV Charging.
  - SCHEDULE:OVERRIDE: The vehicle is following a schedule override, and is still actively participating in Flexible EV Charging.
  - SCHEDULE:INFLEXIBLE: The vehicle doesn't have enough time to charge to the target battery level, so there isn't any opportunity to flex the charging.
  Possible enum values:
- policyStatus.batteryReserve number Required
  Upon arrival at the location, the vehicle will immediately charge to this battery level without regard to prices or flexibility demands. This charging is reflected in the Policy Status State as SCHEDULE:BATTERY_RESERVE. Must be between 0% and 20%. Note: For Mercedes-Benz vehicles, batteryReserve must be set to 50, as these vehicles always charge to 50% SOC upon plug-in.
- policyStatus.settings object Required
  Show child attributes
  - policyStatus.settings.regularSchedule object Required
    Today's schedule settings, resolved from the weekly schedule.
    Show child attributes
    policyStatus.settings.regularSchedule.deadline string or null Required
    The time of day the user wants their vehicle to be charged by on a specific day of the week.
    policyStatus.settings.regularSchedule.readyBy string<date-time> Required
    The upcoming deadline represented as a RFC3339 UTC timestamp.
    policyStatus.settings.regularSchedule.minimumChargeTarget number or null Required
    The minimum acceptable battery level the user needs to reach by their deadline on a specific day of the week. The vehicle may, under some circumstances, charge to a higher battery level than the minimumChargeTarget. If the minimumChargeTarget is higher than the vehicle's chargeLimit, the vehicle will charge to the chargeLimit instead. Must be greater than or equal to the batteryReserve. For Mercedes-Benz vehicles, the minimumChargeTarget minimum is 50%, see batteryReserve for more details.
  - policyStatus.settings.override Required
    An override applied to a Flex Policy, shown as a part of the Flex Status entity. The override is either a next-day schedule override or an immediate start override.
    Show child attributes
    policyStatus.settings.override.type string Required
    Possible enum values:
    UPCOMING_SCHEDULE
    policyStatus.settings.override.readyBy string<date-time> Optional
    The timestamp at which the user wants their vehicle to be charged by. Overrides the upcoming deadline set in the Flex Policy. Must be in the future.
    policyStatus.settings.override.minimumChargeTarget number Optional
    The minimum acceptable battery level the user needs to reach by their deadline on a specific day of the week. The vehicle may, under some circumstances, charge to a higher battery level than the minimumChargeTarget. If the minimumChargeTarget is higher than the vehicle's chargeLimit, the vehicle will charge to the chargeLimit instead. Must be greater than or equal to the batteryReserve. For Mercedes-Benz vehicles, the minimumChargeTarget minimum is 50%, see batteryReserve for more details.
- policyStatus.session object Required
  An object containing information about the vehicle's current plug session.
  Show child attributes
  - policyStatus.session.blocks array of object Required
    Show child attributes
    policyStatus.session.blocks[].statusState string Required
    The state of the Policy Status during this charging block.
    Possible enum values:
    UNAVAILABLEIMMEDIATE:OVERRIDESCHEDULE:BATTERY_RESERVESCHEDULE:REGULARSCHEDULE:OVERRIDESCHEDULE:INFLEXIBLE
    policyStatus.session.blocks[].estimatedStartAt string<date-time> Required
    The estimated start time of the charging block.
    policyStatus.session.blocks[].estimatedEndAt string<date-time> Required
    The estimated end time of the charging block.
updatedFields array of string Required

Response 200

The subscriber should return 200 OK to acknowledge the webhook has been received

flex:session:updated

Occurs whenever a Flex charging session is updated.

Request

Attributes

createdAt string<date-time> Required
ISO8601 UTC timestamp
version string Required
API version of the payload
user object Required
Show child attributes
- user.id string Required
  User ID
event string Required
Possible enum values:
session Required
Show child attributes
- session.state string Required
  The current state of the session.
  UPCOMING: Initial state, created shortly after the previous session has settled.
  ACTIVE:BATTERY_RESERVE: Vehicle is plugged in, charging to maintain battery reserve.
  ACTIVE:REGULAR: Vehicle is plugged in, smart charging according to schedule.
  ACTIVE:IMMEDIATE_START: Vehicle is plugged in, charging immediately.
  Possible enum values:
  UPCOMINGACTIVE:BATTERY_RESERVEACTIVE:REGULARACTIVE:IMMEDIATE_START
- session.policyId string<uuid> or null Required
  The unique identifier for the policy associated with this session.
- session.pluggedInAt string<date-time> Required
  The date and time when the vehicle was plugged in.
- session.pluggedOutAt null Required
  Always null. The vehicle has not been unplugged yet.
- session.blocks array of object Required
  Discrete windows of active charging within the session. Empty while UPCOMING. While ACTIVE, blocks represent a mix of past charging and planned future charging — past blocks are final, future blocks are tentative and may shift as the schedule re-optimizes.
  Show child attributes
  session.blocks[].type string Required
  The type of charge block.
  Possible enum values:
  BATTERY_RESERVEREGULARIMMEDIATE_START
  session.blocks[].kwhSum number Required
  The total energy delivered during this block in kWh. For completed and in-progress blocks, this is the actual energy delivered. For future (tentative) blocks, this is the system's estimate.
  session.blocks[].startAt string<date-time> Required
  While ACTIVE, this is when the block started (if past) or is tentatively planned to start (if future). While SETTLED, this is when the block actually started.
  session.blocks[].endAt string<date-time> Required
  While ACTIVE, this is when the block ended (if past) or is tentatively planned to end (if future). While SETTLED, this is when the block actually ended.
- session.statistics object Required
  Energy delivery statistics for the session.
  Show child attributes
  session.statistics.aggregated object or null Required
  Aggregated statistics for the session. Null while UPCOMING.
  Show child attributes
  session.statistics.aggregated.kwhSum number or null Required
  The total amount of energy charged in kWh.
  session.statistics.aggregated.batteryFrom number Required
  The battery percentage at the start of the session.
  session.statistics.aggregated.batteryTo number Required
  The current battery percentage while ACTIVE, or the final battery percentage when SETTLED.
  session.statistics.timeseries array of object Required
  15-minute interval energy delivery data. Empty while UPCOMING.
  Show child attributes
  session.statistics.timeseries[].startAt string<date-time> Required
  The start of this 15-minute interval.
  session.statistics.timeseries[].kwh number Required
  The energy delivered in kWh over this 15-minute interval.
- session.target object Required
  What the system is charging towards for this session.
  Show child attributes
  session.target.latest Required
  The latest target configuration. Null for unmanaged sessions (e.g. public charging) where the system did not control the charge. Use type to distinguish between REGULAR and IMMEDIATE_START targets.
  Show child attributes
  session.target.latest.id integer Required
  Incrementing identifier for this target within the session.
  session.target.latest.type string Required
  Possible enum values:
  REGULAR
  session.target.latest.source string Required
  Whether this target follows the default policy or a user override.
  Possible enum values:
  POLICYUSER_OVERRIDE
  session.target.latest.batteryReserve number Required
  The battery reserve percentage. Charging to this level is always prioritised.
  session.target.latest.minimumChargeTarget number Required
  The minimum charge target as a battery percentage.
  session.target.latest.readyBy string<date-time> Required
  The time by which the minimum charge target should be reached.
- session.outcome object Required
  Whether the target will be met for this session.
  Show child attributes
  session.outcome.latest Required
  The latest outcome assessment. Null before the first estimate is available. Use type to distinguish between REGULAR and IMMEDIATE_START outcomes, then state to distinguish ON_TARGET from OFF_TARGET within regular outcomes.
  Show child attributes
- session.error object Required
  Error state for this session.
  Show child attributes
  session.error.latest Required
  The latest error state. Null when there is no active error. Use type to identify the error kind.
  Show child attributes
  session.error.latest.type string Required
  Possible enum values:
  START_FAIL
updatedFields array of string Required

Response 200

The subscriber should return 200 OK to acknowledge the webhook has been received

Enode API 2024-10-01

Environments

Copy linkProduction

Copy linkSandbox

Authentication

Copy linkAPI credentials

Copy linkGetting an access token

Copy linkRefreshing access tokens

Copy linkAccessing the API with the access token

Copy linkAccessing user-specific endpoints

Response times

Copy linkAPI GET requests

Copy linkGet Vehicle

Copy linkLink User

Copy linkCharging commands

Copy linkWebhooks

Scopes

Copy linkOverview of scopes

Copy linkHandling excluded scopes

Copy linkThe relationship between scopes and capabilities

Copy linkResponses when the location scope is excluded

Copy linkResponses when a control scopes is excluded

Copy linkApplying new scopes to a device

Errors and problems

Copy linkErrors when accessing a User's resources

Copy linkProblems

Versioning

Copy linkBreaking changes

Copy linkVersion Lifecycle

Copy linkLabels

Copy linkBeta

Copy linkEarly Adopter

Copy linkDeprecated

Pagination

Copy linkQuerying a paginated API endpoint

Copy linkHow to navigate through paginated API responses

Copy linkFull example response

Images

Copy linkBase URL

Copy linkSupported formats

Copy linkQuery parameters

Copy linkFit modes

Copy linkExamples

Copy linkCaching

Path parameters

zoneId string Required

areaId string Required

Attributes

currency string Required

to string<date-time> Required

values array of object Required

values[].at string<date-time> Required

values[].price number Required

Path parameters

zoneId string Required

areaId string Required

Query parameters

from string<date-time> Required

to string<date-time> Required

Attributes

zoneId string

areaId string

currency string

from string<date-time>

to string<date-time>

values array of object

values[].at string<date-time>

values[].price number

Path parameters

zoneId string Required

Attributes

areas array of string Required

currency string Required

to string<date-time> Required

values array of object Required

values[].at string<date-time> Required

values[].price number Required

Attributes

name string Required

household object Required