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.

NameURL
APIhttps://enode-api.production.enode.io
OAuth Tokenhttps://oauth.production.enode.io/oauth2/token
Link UIhttps://link.production.enode.io

Copy linkSandbox

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

NameURL
APIhttps://enode-api.sandbox.enode.io
OAuth Tokenhttps://oauth.sandbox.enode.io/oauth2/token
Link UIhttps://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 IDThe identifier for your client, referred to as the client_id.
Client secretThe 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"

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"
}

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
HeaderAuthorization: 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" \

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
HeaderEnode-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}" \

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 contextTypical 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
Batterybattery:control:operation_modeControls the operation mode of the battery
battery:read:locationReads the GPS coordinates of the battery
battery:read:dataReads the battery data, such as the charge state, configuration and general information
Chargercharger:control:chargingControls the max current configuration and/or charging of the charger
charger:read:dataReads the charger data, such as the charge state and general information
HVAChvac:control:modeControls the mode (permanent hold or follow schedule) of the HVAC unit
hvac:read:dataReads the HVAC data, such as the information, thermostat state and temperature state
Inverterinverter:read:dataReads the inverter data, such as the production state and general information
inverter:read:locationReads the GPS coordinates of the inverter
Metermeter:read:locationReads the GPS coordinates of the meter
meter:read:dataReads the meter data, such as energy state and general information
Vehiclevehicle:control:chargingControls the charging of the vehicle
vehicle:read:dataReads the vehicle data, such as charge state, odometer and general information
vehicle:read:locationReads 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": []
    }
  }
}

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 CodeExplanation
400 Bad RequestThe request payload failed schema validation or parsing
401 UnauthorizedMissing or invalid authentication details
403 ForbiddenAuthentication succeeded, but the user lacks access to the resource due to a missing control scope.
404 Not FoundRequested resource doesn't exist
405 Method Not AllowedVendor unavailability prevented request completion
408 Request TimeoutVendor timeout prevented request completion
409 ConflictVendor rejection prevented request completion
424 Failed DependencyFailed vendor requests prevented request completion
429 Too Many RequestsVendor 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",
}

Copy linkProblems

TitleDescription
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 linkExperimental

This product or endpoint is being released in an early stage to get feedback. There are likely bugs or other issues that may not necessarily be prioritized. The whole implementation may be completely changed or 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"
}

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"
}

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"
    }
}

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.

Flex shape

The Flex Shape API is the highest abstraction in the Enode flex architecture, and exposes an aggregated controllable energy load. It outputs projections of future load, and allows control/alteration of that load.

Get flex shape

GET /flex/shape

Read a window of time from the forecast load curves.

  • Each chunk has a standard control parameter, unset by default, that guides the shape of the load.
  • The size of the window available into the future is variable based on data availability and prediction confidence, typically 24-36 hours.
  • Chunk size is a static deployment-level configuration, but is typically ~15 minutes.
  • Although the shape structure (and many primitives under the hood) are quantized to the chunk size, execution is continuous/realtime.
  • A chunk will be re-computed/updated many times as its distance from the present moment decreases. Once it becomes the present, it will not change any further.
  • You can monitor execution by monitoring the shape’s expected load for the present moment’s chunk

Request

Query parameters
startAt string<date-time> Optional

Start of shape window (inclusive). Optional, defaults to start of most recent chunk. RFC3339 timestamp

endAt string<date-time> Optional

End of shape window (exclusive). Optional, defaults to maximum available date. RFC3339 timestamp

Response 200

Shape retrieved

Attributes
  • startAt string<date-time>

    The timestamp of the start of the first chunk in the shape.

  • endAt string<date-time>

    The timestamp of the start of the last chunk in the shape.

  • chunkSizeMinutes number

    The size of the chunks in minutes.

  • computedAt string<date-time>

    The timestamp at which the shape was computed.

  • assetCount integer

    The number of assets included in the shape.

  • chunks array of object

    The chunks of the flex shape, with the expected, minimum and maximum consumption for each chunk.

    Show child attributes
    • chunks[].timestamp string<date-time>

      The start timestamp of the chunk.

    • chunks[].forecast object

      A collection of forecast attributes for a specific 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)

    • chunks[].relativeSetpoint number

      The setpoint of the chunk in kW, relative to the forecast expectedKw.

  • revisionId string

    The revision ID of the flex shape.

Was this section helpful?

Update flex shape

PATCH /flex/shape

Performs a partial update of the Flex Shape by setting control parameters such as relativeSetpoint

  • Explicitly submitting a null control parameter unsets that parameter for the chunk. Chunks not included in the update remain unchanged.
  • Control parameter can naturally only affect the future, and can thus only be submitted for future chunks.
  • It is expected that control inputs are, allowing uncontrolled chunks to freely follow the globally optimized behavior of the system.

Request

Attributes
  • chunks array of object Required

    The chunks to update in the flex shape. Any chunks may be updated, there is no requirement to update chunks sequentially.

    Show child attributes
    • chunks[].timestamp string<date-time> Required

      The timestamp of the chunk at which the setpoint will be applied.

    • chunks[].relativeSetpoint number or null Required

      The relative adjustment to the expectedKw setpoint of the chunk in kW.

Response 204

Shape updated

Was this section helpful?

Preview flex shape update

POST /flex/shape/preview

Before committing a shape update, preview it to:

  1. Check the validity of the update
  2. Evaluate the cost of the update
  3. Evaluate the resultant shape

The cost components are a collection of costing metadata such as solar "wastage" or user interruption risk, for use in calculating a marginal cost delta. The exact metadata available is deployment-specific.

Request

Attributes
  • chunks array of object Required

    The chunks to update in the flex shape. Any chunks may be updated, there is no requirement to update chunks sequentially.

    Show child attributes
    • chunks[].timestamp string<date-time> Required

      The timestamp of the chunk at which the setpoint will be applied.

    • chunks[].relativeSetpoint number or null Required

      The relative adjustment to the expectedKw setpoint of the chunk in kW.

Response 200

Preview updated

Attributes
  • isValid boolean

    Whether the resulting shape is valid.

  • errors array of string

    The errors that occurred while previewing the update.

  • resultantShape object

    The preview of the resulting flex shape after applying the update.

    Show child attributes
    • resultantShape.startAt string<date-time>

      The timestamp of the start of the first chunk in the shape.

    • resultantShape.endAt string<date-time>

      The timestamp of the start of the last chunk in the shape.

    • resultantShape.chunkSizeMinutes number

      The size of the chunks in minutes.

    • resultantShape.computedAt string<date-time>

      The timestamp at which the shape was computed.

    • resultantShape.assetCount integer

      The number of assets included in the shape.

    • resultantShape.chunks array of object

      The chunks of the flex shape, with the expected, minimum and maximum consumption for each chunk.

      Show child attributes
      • resultantShape.chunks[].timestamp string<date-time>

        The start timestamp of the chunk.

      • resultantShape.chunks[].forecast object

        A collection of forecast attributes for a specific chunk, with a confidence score.

        Show child attributes
        • resultantShape.chunks[].forecast.expectedKw number

          The expected mean load in kW.

        • resultantShape.chunks[].forecast.minimumKw number

          The achievable minimum mean load in kW.

        • resultantShape.chunks[].forecast.maximumKw number

          The achievable maximum mean load in kW.

        • resultantShape.chunks[].forecast.confidence number

          Probability that the expectedKw forecast is within a small (configurable) margin of the realized load (0.0-1.0)

      • resultantShape.chunks[].relativeSetpoint number

        The setpoint of the chunk in kW, relative to the forecast expectedKw.

  • costComponents array of object

    The cost components that would be incurred by committing the shape update.

    Show child attributes
    • costComponents[].denomination string

      The denomination of the cost components.

    • costComponents[].amount number

      The amount of the cost component.

Was this section helpful?

Get flex status

GET /flex/status

Configurable built-in alarms and status properties give leading indicators that the system is headed into unusual or unpredictable behavior. Particularly in algorithmic trading cases, the values are useful to trip circuit-breakers or activate alternate operating modes.

Response 200

Status retrieved

Attributes
  • computedAt string<date-time>

    The timestamp at which the Flex Status was computed.

  • isForecastStable boolean

    Indicates whether the forecast revision variance of near-term horizons is within configured bounds (ie. accurate and stable).

  • isSolvent boolean

    The execution engine has sufficient inventory of asset flexibility to fulfill its plans

  • isControlNominal boolean

    Success rate of individual asset control actions within a rolling window of 1 chunk size is within typical expectations.

  • statusMessage string

    A message describing the status of the flex shape.

Was this section helpful?

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.

  • 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

Was this section helpful?

List policies

GET /flex/vehicle-policies

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

Request

Query parameters
after string Optional
before string Optional
pageSize integer Optional
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[].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
Was this section helpful?

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.

  • 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

Was this section helpful?

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
  • id string Optional

    The ID of the flex policy.

  • vehicleId string Optional

    The ID of the vehicle for which this policy applies.

  • locationId string Optional

    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 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

    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 Optional

      The schedule settings for a particular day of the week.

      Show child attributes
      • schedule.monday.deadline string Optional

        The time of day the user wants their vehicle to be charged by on a specific day of the week.

      • schedule.monday.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.

    • schedule.tuesday object Optional

      The schedule settings for a particular day of the week.

      Show child attributes
      • schedule.tuesday.deadline string Optional

        The time of day the user wants their vehicle to be charged by on a specific day of the week.

      • schedule.tuesday.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.

    • schedule.wednesday object Optional

      The schedule settings for a particular day of the week.

      Show child attributes
      • schedule.wednesday.deadline string Optional

        The time of day the user wants their vehicle to be charged by on a specific day of the week.

      • schedule.wednesday.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.

    • schedule.thursday object Optional

      The schedule settings for a particular day of the week.

      Show child attributes
      • schedule.thursday.deadline string Optional

        The time of day the user wants their vehicle to be charged by on a specific day of the week.

      • schedule.thursday.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.

    • schedule.friday object Optional

      The schedule settings for a particular day of the week.

      Show child attributes
      • schedule.friday.deadline string Optional

        The time of day the user wants their vehicle to be charged by on a specific day of the week.

      • schedule.friday.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.

    • schedule.saturday object Optional

      The schedule settings for a particular day of the week.

      Show child attributes
      • schedule.saturday.deadline string Optional

        The time of day the user wants their vehicle to be charged by on a specific day of the week.

      • schedule.saturday.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.

    • schedule.sunday object Optional

      The schedule settings for a particular day of the week.

      Show child attributes
      • schedule.sunday.deadline string Optional

        The time of day the user wants their vehicle to be charged by on a specific day of the week.

      • schedule.sunday.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.

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.

  • 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

Was this section helpful?

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

Attributes

    Response 404

    Policy not found

    Was this section helpful?

    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:

        UNAVAILABLEIMMEDIATE:OVERRIDESCHEDULE:BATTERY_RESERVESCHEDULE:REGULARSCHEDULE:OVERRIDESCHEDULE:INFLEXIBLE
    • 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

    Was this section helpful?

    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:

        IMMEDIATE_START
    • 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

    Was this section helpful?

    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

    Was this section helpful?

    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:

      DAYMONTH
    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

    Was this section helpful?

    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:

      DAYMONTH

    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

    Was this section helpful?

    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:

        flex:vehicle-policy:created
    • 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.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

    Was this section helpful?

    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:

        flex:vehicle-policy:updated
    • 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.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

    Was this section helpful?

    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:

        flex:vehicle-policy:deleted
    • 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.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

    Was this section helpful?

    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:

        flex:vehicle-policy:status
    • 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:

          UNAVAILABLEIMMEDIATE:OVERRIDESCHEDULE:BATTERY_RESERVESCHEDULE:REGULARSCHEDULE:OVERRIDESCHEDULE:INFLEXIBLE
      • 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

    Was this section helpful?