Skip to content
/
Retrieve a vehicle trim

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

Create a custom vehicle trim

Request

Creates a new trim for the specified model that can be used if we are missing a trim. These trims will not be available in the list trims api call

Security
oauth2(Required scopes:
vehicle:write
)
Headers
EvEnergy-Versionnumber

Specify the version of this endpoint to use.

Value2
Bodyapplication/json
namestringrequired

The name of the vehicle trim.

Example: "Custom Trim"
modelstring(uri)required

URL reference to the vehicle model this trim belongs to.

Example: "https://api.ev.energy/v2/vehicle_models/vmod01HSBR8Z36GD7A46K7M4R12VG0"
battery_size_watt_hoursinteger[ 1000 .. 300000 ]required

Battery size in watt hours. Must be between 1000 and 300000.

Example: 75500
curl -i -X POST \
  https://developers.ev.energy/_mock/ev.energy-api-v2/vehicle_trims \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'EvEnergy-Version: 2' \
  -d '{
    "name": "Custom Trim",
    "model": "https://api.ev.energy/v2/vehicle_models/vmod01HSBR8Z36GD7A46K7M4R12VG0",
    "battery_size_watt_hours": 75500
  }'

Responses

Returns the newly created vehicle trim 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
idstringtrim[A-Z\d]{26}read-only

Unique identifier for the given Vehicle Trim.

Example: "trim01HRFHBCM7VBSWRPVYFBQMH2BR"
urlstring(uri)read-only
Example: "https://api.ev.energy/v2/vehicle_trim/trim01HRFHBCM7VBSWRPVYFBQMH2BR"
namestringread-only
Example: "Recharge Core (69 kWh)"
modelstring or VehicleModel (object)
One of:
string(uri)
onboarding_urlstring or null(uri)read-only

A pre-constructed link to initiate onboarding for a vehicle with this trim. If it is null, then we do not support intergrating with this vehicle and you should POST the trim to /vehicles to create an unintegrated vehicle.

Note: if you are using client credentials authentication, the user ID will not be automatically included unless you set the EvEnergy-User header on your request.

Example: "https://api.ev.energy/v2/vehicle_onboarding?trim_id=trim01HN2NZ1040Y8E77CQGXADC2TZ&user_id=user01HN2NJ9NMRZBXT1H6FT9N7735"
Response
application/json
{
  "id": "trim01HRFHBCM7VBSWRPVYFBQMH2BR",
  "url": "https://api.ev.energy/v2/vehicle_trim/trim01HRFHBCM7VBSWRPVYFBQMH2BR",
  "name": "Recharge Core (69 kWh)",
  "model": "http://example.com",
  "onboarding_url": "https://api.ev.energy/v2/vehicle_onboarding?trim_id=trim01HN2NZ1040Y8E77CQGXADC2TZ&user_id=user01HN2NJ9NMRZBXT1H6FT9N7735"
}

Retrieve a vehicle trim

Request

Retrieve details for a single, specific vehicle trim.

Trim refers to a set of features that can be applied to a particular model of vehicle: https://en.wikipedia.org/wiki/Car_model#Trim_level.

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

The ID of the specific vehicle trim to retrieve.

Example: trim01HRFHBCM7VBSWRPVYFBQMH2BR
Query
expandArray of strings

Specify a url field to expand into a nested resource.

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

Responses

Return a single vehicle trim.

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

Unique identifier for the given Vehicle Trim.

Example: "trim01HRFHBCM7VBSWRPVYFBQMH2BR"
urlstring(uri)read-only
Example: "https://api.ev.energy/v2/vehicle_trim/trim01HRFHBCM7VBSWRPVYFBQMH2BR"
namestringread-only
Example: "Recharge Core (69 kWh)"
modelstring or VehicleModel (object)
One of:
string(uri)
onboarding_urlstring or null(uri)read-only

A pre-constructed link to initiate onboarding for a vehicle with this trim. If it is null, then we do not support intergrating with this vehicle and you should POST the trim to /vehicles to create an unintegrated vehicle.

Note: if you are using client credentials authentication, the user ID will not be automatically included unless you set the EvEnergy-User header on your request.

Example: "https://api.ev.energy/v2/vehicle_onboarding?trim_id=trim01HN2NZ1040Y8E77CQGXADC2TZ&user_id=user01HN2NJ9NMRZBXT1H6FT9N7735"
Response
application/json
{
  "id": "trim01HRFHBCM7VBSWRPVYFBQMH2BR",
  "url": "https://api.ev.energy/v2/vehicle_trim/trim01HRFHBCM7VBSWRPVYFBQMH2BR",
  "name": "Recharge Core (69 kWh)",
  "model": "http://example.com",
  "onboarding_url": "https://api.ev.energy/v2/vehicle_onboarding?trim_id=trim01HN2NZ1040Y8E77CQGXADC2TZ&user_id=user01HN2NJ9NMRZBXT1H6FT9N7735"
}

List vehicle models

Request

List all the vehicle models known by the ev.energy system.

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 Value"make"
make_idstring

The ID of a Vehicle Make to filter by

Example: make_id=vmak01HN2NV5DY9C262PQKG75GHN8K
Headers
EvEnergy-Versionnumber

Specify the version of this endpoint to use.

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

If the client is authenticated using Client Credentials, setting EvEnergy-User to a valid user ID allows requests to be made as if you were directly authenticated as that user.

Example: user01HN2NJ9NMRZBXT1H6FT9N7735
curl -i -X GET \
  'https://developers.ev.energy/_mock/ev.energy-api-v2/vehicle_models?page_before=xmpl01HNFZM7Q8FXASZXYZ6XM3TQRR&page_after=xmpl01HNFZM7Q8FXASZXYZ6XM3TQRR&page_size=10&expand=make&make_id=vmak01HN2NV5DY9C262PQKG75GHN8K' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'EvEnergy-User: user01HN2NJ9NMRZBXT1H6FT9N7735' \
  -H 'EvEnergy-Version: 2'

Responses

Return a list of vehicle models.

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

Unique identifier for the given Vehicle Model.

Example: "vmod01HSBR8Z36GD7A46K7M4R12VG0"
urlstring(uri)read-only
Example: "https://api.ev.energy/vehicle_models/vmod01HSBR8Z36GD7A46K7M4R12VG0"
namestringread-only
Example: "C40"
makestring or VehicleMake (object)
One of:
string(uri)
onboarding_urlstring or null(uri)

A pre-constructed link to initiate onboarding for a vehicle of this model. If it is null, then it cannot be onboarded with model alone. You should filter the list of vehicle trims by this model and then have the user select their trim.

Note: if you are using client credentials authentication, the user ID will not be automatically included unless you set the EvEnergy-User header on your request.

Example: "https://api.ev.energy/v2/vehicle_onboarding?model_id=vmod01HN2P436099PEQ20B7TKPGTEJ&user_id=user01HN2NJ9NMRZBXT1H6FT9N7735"
trimsstring(uri)

A pre-constructed link to a list of vehicle trims filtered for this model.

Example: "https://api.ev.energy/vehicle_trims?model_id=vmod01HN2P436099PEQ20B7TKPGTEJ"
]
Response
application/json
[
  {
    "id": "vmod01HSBR8Z36GD7A46K7M4R12VG0",
    "url": "https://api.ev.energy/vehicle_models/vmod01HSBR8Z36GD7A46K7M4R12VG0",
    "name": "C40",
    "make": "https://api.ev.energy/v2/vehicle_makes/vmak01HRFHBCM7VBSWRPVYFBQMH2BR",
    "onboarding_url": "https://api.ev.energy/v2/vehicle_onboarding?model_id=vmod01HN2P436099PEQ20B7TKPGTEJ&user_id=user01HN2NJ9NMRZBXT1H6FT9N7735",
    "trims": "https://api.ev.energy/vehicle_trims?model_id=vmod01HN2P436099PEQ20B7TKPGTEJ"
  }
]

Webhooks

Endpoints for configuring and managing webhooks.

Operations