Skip to content
/
Create unintegrated vehic...

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

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

List vehicles

Request

List all the vehicles that the authorization token has access to.

Security
oauth2(Required scopes:
vehicle:read
)
Query
page_beforestring[a-z]{4}[A-Z\d]{26}

Return results from the page after this ID.

Example: page_before=xmpl01HNFZM7Q8FXASZXYZ6XM3TQRR
page_afterstring[a-z]{4}[A-Z\d]{26}

Return results from the page before this ID.

Example: page_after=xmpl01HNFZM7Q8FXASZXYZ6XM3TQRR
page_sizeinteger[ 1 .. 100 ]

Specify the number of results to return per page.

Default 25
Example: page_size=10
expandArray of strings

Specify a url field to expand into a nested resource.

Items Enum"user""trim""trim.model""trim.model.make""latest_status_log"
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/vehicles?page_before=xmpl01HNFZM7Q8FXASZXYZ6XM3TQRR&page_after=xmpl01HNFZM7Q8FXASZXYZ6XM3TQRR&page_size=10&expand=user' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'EvEnergy-Version: 2'

Responses

Return a list of vehicles.

Headers
Linkstring

Provides links to the previous and next pages of data, if they exist.

Example: "<https://api.ev.energy/v2/vehicles?page_size=25&page_before=vhcl01HRFF3SEVSCRAV9B3CHVDFN0H>; rel=\"previous\", <https://api.ev.energy/v2/vehicles?page_size=25&page_after=vhcl01HRFF3SEVSCRAV9B3CHVDFN0H>; rel=\"next\""
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/jsonArray [
idstringvhcl[A-Z\d]{26}read-only

Unique identifier for the given Vehicle.

Example: "vhcl01HRFF3SEVSCRAV9B3CHVDFN0H"
urlstring(uri)read-only
Example: "https://api.ev.energy/v2/vehicles/vhcl01HRFF3SEVSCRAV9B3CHVDFN0H"
trimstring or VehicleTrim (object)read-only

Defaults to a url, but can be expanded to the full Trim resource via the expand query parameter.

One of:

Defaults to a url, but can be expanded to the full Trim resource via the expand query parameter.

string(uri)read-only
userstring or User (object)

Defaults to a url, but can be expanded to the full User resource via the expand query parameter.

Example: "https://api.ev.energy/v2/users/user01HN2NJ9NMRZBXT1H6FT9N7735"
One of:

Defaults to a url, but can be expanded to the full User resource via the expand query parameter.

string(uri)
latest_status_log(string or null) or VehicleStatusLog (object)

An expandable reference to the most recent status log for this Vehicle. This can be requested or expanded to get the most accurate information we have on the device's current status.

Example: "https://api.ev.energy/v2/vehicles/vhcl01HRFF3SEVSCRAV9B3CHVDFN0H/status_logs/2024-04-17T09:39:45.994584Z/"
One of:

An expandable reference to the most recent status log for this Vehicle. This can be requested or expanded to get the most accurate information we have on the device's current status.

string or null(uri)
charging_sub_sessionsstring(uri)

Provides a pre-constructed URL to list charging sub-sessions involving this Vehicle.

Example: "https://api.ev.energy/charging_sub_sessions/?vehicle_id=vhcl01HRFF3SEVSCRAV9B3CHVDFN0H"
integratedanyread-only

Whether we have an integration with this vehicle.

  • UNINTEGRATED: This vehicle is not integrated
  • ACTIVE: This vehicle is integrated and the connection is working.
  • INACTIVE: This vehicle has been integrated but the connection has been severed, usually because the user needs to reconnect it.
Enum"UNINTEGRATED""ACTIVE""INACTIVE"
maximum_charge_limit_percentageinteger[ 50 .. 100 ]

The target state of charge of the car as a percentage between 50 and 100. The car will not be smart charged above this value. Can be null if target charge level has not been set or we don't know the car's battery size.

Default 100
]
Response
application/json
[
  {
    "id": "vhcl01HRFF3SEVSCRAV9B3CHVDFN0H",
    "url": "https://api.ev.energy/v2/vehicles/vhcl01HRFF3SEVSCRAV9B3CHVDFN0H",
    "trim": "https://api.ev.energy/v2/trim/vehicle_trim01HRFHBCM7VBSWRPVYFBQMH2BR",
    "user": "https://api.ev.energy/v2/users/user01HN2NJ9NMRZBXT1H6FT9N7735",
    "latest_status_log": "https://api.ev.energy/v2/vehicles/vhcl01HRFF3SEVSCRAV9B3CHVDFN0H/status_logs/2024-04-17T09:39:45.994584Z/",
    "charging_sub_sessions": "https://api.ev.energy/charging_sub_sessions/?vehicle_id=vhcl01HRFF3SEVSCRAV9B3CHVDFN0H",
    "integrated": "UNINTEGRATED",
    "maximum_charge_limit_percentage": 100
  }
]

Create unintegrated vehicle

Request

If a vehicle cannot be integrated with our system, an "unintegrated" vehicle must be created instead to represent it and record important details like battery size.

To add a vehicle that can be integrated, see the Onboarding documentation.

Security
oauth2(Required scopes:
vehicle:write
)
Query
expandstring

Specify a url field to expand into a nested resource.

Example: expand=user
Headers
EvEnergy-Versionnumber

Specify the version of this endpoint to use.

Value2
EvEnergy-Userstringuser[A-Z\d]{26}

This endpoints requires a user ID to be specified via this header when using Client Credentials authentication.

Example: user01HN2NJ9NMRZBXT1H6FT9N7735
Bodyapplication/json
trimstring(uri)required
Example: "https://api.ev.energy/v2/trim/vehicle_trim01HRFHBCM7VBSWRPVYFBQMH2BR"
userstring(uri)

Required if using Client Credentials authentication.

Example: "https://api.ev.energy/v2/users/user01HN2NJ9NMRZBXT1H6FT9N7735"
curl -i -X POST \
  'https://developers.ev.energy/_mock/ev.energy-api-v2/vehicles?expand=user' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'EvEnergy-User: user01HN2NJ9NMRZBXT1H6FT9N7735' \
  -H 'EvEnergy-Version: 2' \
  -d '{
    "trim": "https://api.ev.energy/v2/trim/vehicle_trim01HRFHBCM7VBSWRPVYFBQMH2BR",
    "user": "https://api.ev.energy/v2/users/user01HN2NJ9NMRZBXT1H6FT9N7735"
  }'

Responses

Returns the newly created vehicle resource.

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
idstringvhcl[A-Z\d]{26}read-only

Unique identifier for the given Vehicle.

Example: "vhcl01HRFF3SEVSCRAV9B3CHVDFN0H"
urlstring(uri)read-only
Example: "https://api.ev.energy/v2/vehicles/vhcl01HRFF3SEVSCRAV9B3CHVDFN0H"
trimstring or VehicleTrim (object)read-only

Defaults to a url, but can be expanded to the full Trim resource via the expand query parameter.

One of:

Defaults to a url, but can be expanded to the full Trim resource via the expand query parameter.

string(uri)read-only
userstring or User (object)

Defaults to a url, but can be expanded to the full User resource via the expand query parameter.

Example: "https://api.ev.energy/v2/users/user01HN2NJ9NMRZBXT1H6FT9N7735"
One of:

Defaults to a url, but can be expanded to the full User resource via the expand query parameter.

string(uri)
latest_status_log(string or null) or VehicleStatusLog (object)

An expandable reference to the most recent status log for this Vehicle. This can be requested or expanded to get the most accurate information we have on the device's current status.

Example: "https://api.ev.energy/v2/vehicles/vhcl01HRFF3SEVSCRAV9B3CHVDFN0H/status_logs/2024-04-17T09:39:45.994584Z/"
One of:

An expandable reference to the most recent status log for this Vehicle. This can be requested or expanded to get the most accurate information we have on the device's current status.

string or null(uri)
charging_sub_sessionsstring(uri)

Provides a pre-constructed URL to list charging sub-sessions involving this Vehicle.

Example: "https://api.ev.energy/charging_sub_sessions/?vehicle_id=vhcl01HRFF3SEVSCRAV9B3CHVDFN0H"
integratedanyread-only

Whether we have an integration with this vehicle.

  • UNINTEGRATED: This vehicle is not integrated
  • ACTIVE: This vehicle is integrated and the connection is working.
  • INACTIVE: This vehicle has been integrated but the connection has been severed, usually because the user needs to reconnect it.
Enum"UNINTEGRATED""ACTIVE""INACTIVE"
maximum_charge_limit_percentageinteger[ 50 .. 100 ]

The target state of charge of the car as a percentage between 50 and 100. The car will not be smart charged above this value. Can be null if target charge level has not been set or we don't know the car's battery size.

Default 100
Response
application/json
{
  "id": "vhcl01HRFF3SEVSCRAV9B3CHVDFN0H",
  "url": "https://api.ev.energy/v2/vehicles/vhcl01HRFF3SEVSCRAV9B3CHVDFN0H",
  "trim": "https://api.ev.energy/v2/trim/vehicle_trim01HRFHBCM7VBSWRPVYFBQMH2BR",
  "user": "https://api.ev.energy/v2/users/user01HN2NJ9NMRZBXT1H6FT9N7735",
  "latest_status_log": "https://api.ev.energy/v2/vehicles/vhcl01HRFF3SEVSCRAV9B3CHVDFN0H/status_logs/2024-04-17T09:39:45.994584Z/",
  "charging_sub_sessions": "https://api.ev.energy/charging_sub_sessions/?vehicle_id=vhcl01HRFF3SEVSCRAV9B3CHVDFN0H",
  "integrated": "UNINTEGRATED",
  "maximum_charge_limit_percentage": 100
}

Retrieve a vehicle

Request

Retrieve a single, specific vehicle's details.

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

The ID of the specific vehicle to retrieve.

Example: vhcl01HRFF3SEVSCRAV9B3CHVDFN0H
Query
expandArray of strings

Specify a url field to expand into a nested resource.

Items Enum"user""trim""trim.model""trim.model.make""latest_status_log"
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/vehicles/vhcl01HRFF3SEVSCRAV9B3CHVDFN0H?expand=user' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'EvEnergy-Version: 2'

Responses

Return a single vehicle.

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
idstringvhcl[A-Z\d]{26}read-only

Unique identifier for the given Vehicle.

Example: "vhcl01HRFF3SEVSCRAV9B3CHVDFN0H"
urlstring(uri)read-only
Example: "https://api.ev.energy/v2/vehicles/vhcl01HRFF3SEVSCRAV9B3CHVDFN0H"
trimstring or VehicleTrim (object)read-only

Defaults to a url, but can be expanded to the full Trim resource via the expand query parameter.

One of:

Defaults to a url, but can be expanded to the full Trim resource via the expand query parameter.

string(uri)read-only
userstring or User (object)

Defaults to a url, but can be expanded to the full User resource via the expand query parameter.

Example: "https://api.ev.energy/v2/users/user01HN2NJ9NMRZBXT1H6FT9N7735"
One of:

Defaults to a url, but can be expanded to the full User resource via the expand query parameter.

string(uri)
latest_status_log(string or null) or VehicleStatusLog (object)

An expandable reference to the most recent status log for this Vehicle. This can be requested or expanded to get the most accurate information we have on the device's current status.

Example: "https://api.ev.energy/v2/vehicles/vhcl01HRFF3SEVSCRAV9B3CHVDFN0H/status_logs/2024-04-17T09:39:45.994584Z/"
One of:

An expandable reference to the most recent status log for this Vehicle. This can be requested or expanded to get the most accurate information we have on the device's current status.

string or null(uri)
charging_sub_sessionsstring(uri)

Provides a pre-constructed URL to list charging sub-sessions involving this Vehicle.

Example: "https://api.ev.energy/charging_sub_sessions/?vehicle_id=vhcl01HRFF3SEVSCRAV9B3CHVDFN0H"
integratedanyread-only

Whether we have an integration with this vehicle.

  • UNINTEGRATED: This vehicle is not integrated
  • ACTIVE: This vehicle is integrated and the connection is working.
  • INACTIVE: This vehicle has been integrated but the connection has been severed, usually because the user needs to reconnect it.
Enum"UNINTEGRATED""ACTIVE""INACTIVE"
maximum_charge_limit_percentageinteger[ 50 .. 100 ]

The target state of charge of the car as a percentage between 50 and 100. The car will not be smart charged above this value. Can be null if target charge level has not been set or we don't know the car's battery size.

Default 100
Response
application/json
{
  "id": "vhcl01HRFF3SEVSCRAV9B3CHVDFN0H",
  "url": "https://api.ev.energy/v2/vehicles/vhcl01HRFF3SEVSCRAV9B3CHVDFN0H",
  "trim": "https://api.ev.energy/v2/trim/vehicle_trim01HRFHBCM7VBSWRPVYFBQMH2BR",
  "user": "https://api.ev.energy/v2/users/user01HN2NJ9NMRZBXT1H6FT9N7735",
  "latest_status_log": "https://api.ev.energy/v2/vehicles/vhcl01HRFF3SEVSCRAV9B3CHVDFN0H/status_logs/2024-04-17T09:39:45.994584Z/",
  "charging_sub_sessions": "https://api.ev.energy/charging_sub_sessions/?vehicle_id=vhcl01HRFF3SEVSCRAV9B3CHVDFN0H",
  "integrated": "UNINTEGRATED",
  "maximum_charge_limit_percentage": 100
}

Webhooks

Endpoints for configuring and managing webhooks.

Operations