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

List notifications

Request

Lists notifications for the user making the request. For each notification it returns a category (INFO, ERROR etc) and a title (in the user's language) for display in their inbox.

Security
oauth2
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
Headers
EvEnergy-Versionnumber

Specify the version of this endpoint to use.

Value2
Accept-Languagestring

Indicates the natural language and locale that the client prefers.

curl -i -X GET \
  'https://developers.ev.energy/_mock/ev.energy-api-v2/notifications?page_before=xmpl01HNFZM7Q8FXASZXYZ6XM3TQRR&page_after=xmpl01HNFZM7Q8FXASZXYZ6XM3TQRR&page_size=10' \
  -H 'Accept-Language: string' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'EvEnergy-Version: 2'

Responses

Retrieve all current notifications.

Headers
Linkstring

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

Example: "<about:blank>; rel=\"previous\", <https://api.ev.energy/v2/examples/?page=2&page_size=25>; 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 [
idstringnotf[A-Z\d]{26}required

Unique identifier for the Notification

Example: "notf67O36PLTFDB57M0E5L33JZLGM0"
urlstring(uri)required
Example: "https://api.ev.energy/notifications/notf67O36PLTFDB57M0E5L33JZLGM0"
message_idstringrequired

Internal identifier for this notification type. E.g. 'ERR0023'

categoryanyrequired

Category of this notification type

Enum"ACTIONABLE""SERVICE""RETRY""MARKETING""INTERNAL"
event_timestring(date-time)required

The timestamp of the event described by this notification

short_text_titlestring<= 33 charactersrequired

Short title for the notification

short_text_bodystring<= 49 charactersrequired

Short description of the event being notified

detail_page_titlestring

Title of a help page giving more information about this notification

detail_page_bodystring

Text of a help page giving more information about this notification

external_linkstring or null(uri)

URL of a web page giving further information about this notification

external_button_labelstring

Text to be displayed on a button leading to the external_link location

read_atstring(date-time)

When the user examined the contents of this notification

resolved_atstring(date-time)

When the problem associated with this notification was resolved

]
Response
application/json
[
  {
    "id": "notf67O36PLTFDB57M0E5L33JZLGM0",
    "url": "https://api.ev.energy/notifications/notf67O36PLTFDB57M0E5L33JZLGM0",
    "message_id": "ERR0123",
    "category": "ACTIONABLE",
    "event_time": "2019-08-24T14:15:22Z",
    "short_text_title": "Your car is disconnected",
    "short_text_body": "We need to reconnect to keep smart charging",
    "detail_page_title": "Your car is disconnected",
    "detail_page_body": "Your car has been disconnected. This happens when your password is reset.\nWe need you to re-authorise ev.energy to access your account in order for us to keep managing your charging.\nBlah blah blah.",
    "external_link": "https://example.com",
    "external_button_label": "More info"
  }
]

Update a notification

Request

Update a notification.

Security
oauth2
Path
notification_idstringnotf[A-Z\d]{26}required

The ID of the specific notification to retrieve.

Example: notf67O36PLTFDB57M0E5L33JZLGM0
Bodyapplication/json

Details of Notification to be updated.

read_atstring(date-time)
curl -i -X PATCH \
  https://developers.ev.energy/_mock/ev.energy-api-v2/notifications/notf67O36PLTFDB57M0E5L33JZLGM0 \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "read_at": "2019-08-24T14:15:22Z"
  }'

Responses

Notification updated successfully.

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
Notificationobject(Notification)

Something that the user should be informed about.

Response
application/json
{
  "Notification": {
    "id": "notf67O36PLTFDB57M0E5L33JZLGM0",
    "url": "https://api.ev.energy/notifications/notf67O36PLTFDB57M0E5L33JZLGM0",
    "message_id": "ERR0123",
    "category": "ACTIONABLE",
    "event_time": "2019-08-24T14:15:22Z",
    "short_text_title": "Your car is disconnected",
    "short_text_body": "We need to reconnect to keep smart charging your car",
    "detail_page_title": "Your car is disconnected",
    "detail_page_body": "Your car has been disconnected. This happens when your password is reset. We need you to re-authorise ev.energy to access your account in order for us to keep managing your charging. Blah blah blah.",
    "external_link": "http://example.com",
    "external_button_label": "More info",
    "read_at": "2019-08-24T14:20:22Z",
    "resolved_at": "2019-08-25T14:15:22Z"
  }
}

Retrieve a notification

Request

Retrieves the full details of a specified notification. The title, short_text and long_text fields will be translated into the user's language.

Security
oauth2
Path
notification_idstringnotf[A-Z\d]{26}required

The ID of the specific notification to retrieve.

Example: notf67O36PLTFDB57M0E5L33JZLGM0
Headers
EvEnergy-Versionnumber

Specify the version of this endpoint to use.

Value2
Accept-Languagestring

Indicates the natural language and locale that the client prefers.

curl -i -X GET \
  https://developers.ev.energy/_mock/ev.energy-api-v2/notifications/notf67O36PLTFDB57M0E5L33JZLGM0 \
  -H 'Accept-Language: string' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'EvEnergy-Version: 2'

Responses

Retrieve a specific notification.

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
idstringnotf[A-Z\d]{26}required

Unique identifier for the Notification

Example: "notf67O36PLTFDB57M0E5L33JZLGM0"
urlstring(uri)required
Example: "https://api.ev.energy/notifications/notf67O36PLTFDB57M0E5L33JZLGM0"
message_idstringrequired

Internal identifier for this notification type. E.g. 'ERR0023'

categoryanyrequired

Category of this notification type

Enum"ACTIONABLE""SERVICE""RETRY""MARKETING""INTERNAL"
event_timestring(date-time)required

The timestamp of the event described by this notification

short_text_titlestring<= 33 charactersrequired

Short title for the notification

short_text_bodystring<= 49 charactersrequired

Short description of the event being notified

detail_page_titlestring

Title of a help page giving more information about this notification

detail_page_bodystring

Text of a help page giving more information about this notification

external_linkstring or null(uri)

URL of a web page giving further information about this notification

external_button_labelstring

Text to be displayed on a button leading to the external_link location

read_atstring(date-time)

When the user examined the contents of this notification

resolved_atstring(date-time)

When the problem associated with this notification was resolved

Response
application/json
{
  "id": "notf67O36PLTFDB57M0E5L33JZLGM0",
  "url": "https://api.ev.energy/notifications/notf67O36PLTFDB57M0E5L33JZLGM0",
  "message_id": "ERR0123",
  "category": "ACTIONABLE",
  "event_time": "2019-08-24T14:15:22Z",
  "short_text_title": "Your car is disconnected",
  "short_text_body": "We need to reconnect to keep smart charging",
  "detail_page_title": "Your car is disconnected",
  "detail_page_body": "Your car has been disconnected. This happens when your password is reset.\nWe need you to re-authorise ev.energy to access your account in order for us to keep managing your charging.\nBlah blah blah.",
  "external_link": "https://example.com",
  "external_button_label": "More info"
}

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