Skip to content

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

List programs

Request

By default, this endpoint returns all programs in our system and does not require authentication. The coordinates, postal_code and country_code query parameters can be used to narrow the list down to just programs eligible for particular locations. Coordinates and postal code searching are mutually exclusive and mixing the query parameters will result in a 400 error response.

If the client is authenticated as a specific user (either via Authorisation Code grant type or the EvEnergy-User header) it will return only programs that user is possibly eligible for, based on the location information we have for them.

Query
coordinatesstring^[-+]?([1-8]?\d(\.\d+)?|90(\.0+)?),\s*[-+]?(1...

Filter the returned programs to only those available to someone who primarily charges their vehicles at these coordinates.

Example: coordinates=50.896453,-1.4037239
postal_codestring

Filter the returned programs to only those available to someone someone who primarily charges their vehicles in this postal code area. The postal code needs to be in the correct format for the country specified by country_code.

Example: postal_code=SW1 1AA
country_codestring(CountryCode)

Specify the country the postal code is within. Required if postal_code is used.

Enum"AD""AE""AF""AG""AI""AL""AM""AO""AQ""AR"
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/programs?coordinates=50.896453%2C-1.4037239&postal_code=SW1+1AA&country_code=AD' \
  -H 'EvEnergy-User: user01HN2NJ9NMRZBXT1H6FT9N7735' \
  -H 'EvEnergy-Version: 2'

Responses

Returns 0 or more Programs.

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 [
idstringprog[A-Z\d]{26}read-only
Example: "prog01JCK1HPNAANB8WN253G27SFPC"
urlstring(uri)read-only
Example: "https://api.ev.energy/v2/programs/prog01JCK1HPNAANB8WN253G27SFPC"
namestringread-only

A human-friendly name for the Program.

Example: "CoolCharge"
descriptionstringread-only

A plain text description of the program's incentives and requirements.

Example: "A program which incentivises charging when it's coolest to charge your EV"
logostring or null(uri)read-only

URL to download a logo image for the Program.

sponsor_namestringread-only

The name of the organisation which sponsors the program. Often, but not always, a utility company.

Example: "Cool Power"
external_urlstring(uri)read-only

A publicly accessible URL where individuals can enroll in the program.

Example: "https://www.example.com/coolcharge"
]
Response
application/json
[
  {
    "id": "prog01JCK1HPNAANB8WN253G27SFPC",
    "url": "https://api.ev.energy/v2/programs/prog01JCK1HPNAANB8WN253G27SFPC",
    "name": "CoolCharge",
    "description": "A program which incentivises charging when it's coolest to charge your EV",
    "logo": "http://example.com",
    "sponsor_name": "Cool Power",
    "external_url": "https://www.example.com/coolcharge"
  }
]

Retrieve a program

Request

Retrieve details for a single, specific program.

Path
program_idstringrequired

The ID of the specific Program to retrieve.

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/programs/{program_id}' \
  -H 'EvEnergy-Version: 2'

Responses

OK

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
idstringprog[A-Z\d]{26}read-only
Example: "prog01JCK1HPNAANB8WN253G27SFPC"
urlstring(uri)read-only
Example: "https://api.ev.energy/v2/programs/prog01JCK1HPNAANB8WN253G27SFPC"
namestringread-only

A human-friendly name for the Program.

Example: "CoolCharge"
descriptionstringread-only

A plain text description of the program's incentives and requirements.

Example: "A program which incentivises charging when it's coolest to charge your EV"
logostring or null(uri)read-only

URL to download a logo image for the Program.

sponsor_namestringread-only

The name of the organisation which sponsors the program. Often, but not always, a utility company.

Example: "Cool Power"
external_urlstring(uri)read-only

A publicly accessible URL where individuals can enroll in the program.

Example: "https://www.example.com/coolcharge"
Response
application/json
{
  "id": "prog01JCK1HPNAANB8WN253G27SFPC",
  "url": "https://api.ev.energy/v2/programs/prog01JCK1HPNAANB8WN253G27SFPC",
  "name": "CoolCharge",
  "description": "A program which incentivises charging when it's coolest to charge your EV",
  "logo": "http://example.com",
  "sponsor_name": "Cool Power",
  "external_url": "https://www.example.com/coolcharge"
}

List incentive schemes

Request

Returns a list of Incentive Schemes that the authenticated User is eligble for.

Security
oauth2
Headers
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
curl -i -X GET \
  https://developers.ev.energy/_mock/ev.energy-api-v2/incentive_schemes \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'EvEnergy-User: user01HN2NJ9NMRZBXT1H6FT9N7735'

Responses

OK

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

Prefix: "incs"

namestring

Name to be displayed to the User.

descriptionstring

Describes the rules of how the User earns this Incentive.

visibleboolean

Should this Incentive Scheme be visible to the User in the App.

Default false
availableboolean

Is this Incentive available for the User to earn. Some Incentive Schemes can only be earned a limitted number of times per User or Device. E.g. A Sign Up Incentive that can only be earned once per Device. This will also be False if it is outside the active period of the Incentive Scheme.

Default true
]
Response
application/json
[
  {
    "id": "incs01JE3ZY9Z2C0E087C942B9WKBC",
    "name": "Off-Peak Charging Incentives",
    "description": "Earn $0.10 per kWh when charging off-peak",
    "visible": false,
    "available": true
  }
]

Verify user

Request

Upload a user's utility account information for verification and account matching against the utility's customer data.

An endpoint to serve this data will be added in future.

Security
oauth2
Path
program_idstringrequired

The ID of the specific Program to retrieve.

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
Bodyapplication/json

The body must be a JSON object containing data required for user verification. The exact dat requirements differ by program and will be validated against a dynamic JSON schema, so no specific type is defined here.

The examples are not exhaustive.

object
curl -i -X POST \
  'https://developers.ev.energy/_mock/ev.energy-api-v2/programs/{program_id}/user_verification' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'EvEnergy-User: user01HN2NJ9NMRZBXT1H6FT9N7735' \
  -H 'EvEnergy-Version: 2' \
  -d '{
    "account_number": "12345678-A"
  }'

Responses

Created

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
Response
No content

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