Skip to content
/
Initiate EVSE onboarding

ev.energy v2 API (2.0)

The official API for ev.energy, version 2.

Download OpenAPI description
ev.energy-API-v2.json
ev.energy-API-v2.yaml
Overview
URL
developers.ev.energy
ev.energy developers
developers@ev.energy
License
Proprietary
Languages
Servers
Mock server
https://developers.ev.energy/_mock/ev.energy-api-v2
Live API for both production and sandbox requests.
https://api.ev.energy/v2
Staging server for internal testing only.
https://api-staging.ev.energy/v2

Carbon

Endpoints for interacting with carbon intensity data.

Schemas
Operations

Charging Sessions

Endpoints related to records of charging.

Schemas
Operations
Webhooks

CSV

Endpoints that return CSV responses only and are not linkable to other endpoint data.

EVSEs

Endpoints for interacting with EVSEs.

Schemas
Operations

Retrieve a command log for an EVSE

Request

An EVSE command log is uniquely identified by the combination of EVSE ID and the time it was logged at.

Security
oauth2(Required scopes:
debug:read
)
Path
evse_idstringevse[A-Z\d]{26}required

The ID of the specific EVSE to retrieve.

Example: evse01HSH04KDEWF6Z4DB2J77J74K5
logged_atstring(date-time)required

The time the command was logged.

Example: 2024-04-17T09:39:45.984584Z
Query
expandArray of strings

Specify a url field to expand into a nested resource.

Items Enum"evse""evse.model""evse.model.make""evse.user"
Headers
EvEnergy-Versionnumber

Specify the version of this endpoint to use.

Value2
curl -i -X GET \
  'https://developers.ev.energy/_mock/ev.energy-api-v2/evses/evse01HSH04KDEWF6Z4DB2J77J74K5/command_logs/2024-04-17T09:39:45.984584Z?expand=evse' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'EvEnergy-Version: 2'

Responses

Retrieve a single command log for a specific EVSE.

Headers
EvEnergy-Versionnumber

Indicates the version of the API that generated this response. If EvEnergy-Version was not specified in the request, this will be your OAuth application's default version.

Value2
X-RateLimit-Limitnumber

The maximum number of requests that can be made to this endpoint per hour. Defaults to 1000 but may vary per client.

Default 1000
X-RateLimit-Remainingnumber

The number of requests remaining until this client's rate limit is reached.

Default 999
RetryAfternumber

The number of seconds until this client's requests will not be rate limited.

Default 3600
Bodyapplication/json
urlstring(uri)read-only
Example: "https://api.ev.energy/v2/evses/evse01HSH04KDEWF6Z4DB2J77J74K5/command_logs/2024-04-17T09:39:45.984584Z/"
logged_atstring(date-time)read-only

The date and time when this command was logged by the ev.energy system.

evsestring or EVSE (object)
One of:
string(uri)
max_load_target_milliampsinteger or nullread-only

The target maximum load sent to the EVSE, in milliamps.

Example: 32000
is_enabled_targetboolean or nullread-only

The target state sent for is_enabled (i.e. free-vend mode).

Example: true
always_enabledboolean or nullread-only

Whether the EVSE should always be in is_enabled (i.e. free-vend) mode.

Example: false
reasonstring or nullread-only

The reason the command was sent to the EVSE.

Enum"SCHEDULED_CHARGING""REFRESH_SCHEDULES""STOP_CHARGE""START_CHARGE""SOLAR_CHARGE_NIGHTTIME_CHARGE_RATE""API_TRIGGERED_COMMAND""COMMISSIONING""CHARGING_SESSION""VEHICLE_TO_HOME""FREE_VEND"
Example: "SCHEDULED_CHARGING"
internal_command_idstring or null(uuid)read-only

Internal UUID to track this command dispatch. This links with device command logs.

Example: "d4e5f6a7-b8c9-0123-def0-123456789abc"
Response
application/json
{
  "url": "https://api.ev.energy/v2/evses/evse01HSH04KDEWF6Z4DB2J77J74K5/command_logs/2024-04-17T09:39:45.984584Z/",
  "logged_at": "2019-08-24T14:15:22Z",
  "evse": "https://api.ev.energy/v2/evses/evse01HSH04KDEWF6Z4DB2J77J74K5",
  "max_load_target_milliamps": 32000,
  "is_enabled_target": true,
  "always_enabled": false,
  "reason": "SCHEDULED_CHARGING",
  "internal_command_id": "d4e5f6a7-b8c9-0123-def0-123456789abc"
}

Initiate EVSE onboarding

Request

Initiate the onboarding process for a new EVSE in your user's browser (or an embedded web view in an app).

If neither make_id or model_id are passed as query parameters, the user will be shown a user interface to pick their EVSE make.

Query
user_idstringuser[A-Z\d]{26}required

The ID of a user to onboard a device for.

Example: user_id=user01HN2NJ9NMRZBXT1H6FT9N7735
make_idstring

Specify the make of EVSE to be onboarded.

Example: make_id=emak01HN2NJQRGDQP0GBE1F7R6PB3D
model_idstring

Specify the model of EVSE to be onboarded.

Example: model_id=emod01HN2NJHAJJAQD32QJ4QXTDSGW
client_idstringnon-emptyrequired

Your client ID, used to identify GET requests made in a user's browser.

Example: client_id=sandbox-cc-id
curl -i -X GET \
  'https://developers.ev.energy/_mock/ev.energy-api-v2/evse_onboarding?user_id=user01HN2NJ9NMRZBXT1H6FT9N7735&make_id=emak01HN2NJQRGDQP0GBE1F7R6PB3D&model_id=emod01HN2NJHAJJAQD32QJ4QXTDSGW&client_id=sandbox-cc-id'

Responses

Have the user's browser follow the redirect to be prompted to connect their EVSE to the ev.energy system.

If a make or model were not provided, the user will first be redirected to a screen to select these.

Headers
Locationstring

The URL that the users browser will be redirected to in order to integrate their EVSE.

Response
No content

Notifications

Endpoints for communicating notifications.

Operations

Programs

Endpoints related to incentivised charging programs.

Operations

Rebates

Endpoints for interacting with rebates.

Schemas
Operations

Root

The root endpoint which lists all the top-level collections.

Operations

Schedules

Schema definitions for charging schedules.

Schemas

Sites

Endpoints for interacting with sites containing multiple EVSEs.

Operations

Solar

Endpoints for interacting with solar arrays and inverters.

Operations

Subscriptions

Endpoints for interacting with user subscriptions.

Operations

Support Tickets

Endpoints for interacting with customer support tickets.

Schemas
Operations

Tariffs

Endpoints related to energy suppliers and their tariffs.

Schemas
Operations

Users

Endpoints for interacting with users.

Schemas
Operations

Vehicles

Endpoints for interacting with vehicles.

Schemas

Webhooks

Endpoints for configuring and managing webhooks.

Operations