Skip to content

Users

Endpoints for interacting with users.

Schemas
Operations

List users

Request

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

Security
oauth2(Required scopes: user: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:"default_location.tariff""default_location.tariff.supplier""default_location.evse_site"
emailstring, (email)

Filter users by email address (case-insensitive exact match).

Example:email=user@example.com
program_idstringprog[A-Z\d]{26}

Filter users by the program they are currently enrolled in, given as a Program ID from /programs. Matches members of any of the program's tiers, and excludes users who have since left it. An unknown Program ID yields an empty page, and an empty value leaves the list unfiltered.

Example:program_id=prog01JCDYNYDWHS7VN72SJ05X0NFR
include_deletedboolean

Include users whose account has been deleted. Deleted users are omitted by default, and addressing one by ID returns 404 unless this is set. Has no effect on the me alias, which always resolves to the caller's own user.

Default:false
Example:include_deleted=true
Headers
EvEnergy-Versionnumber

Specify the version of this endpoint to use.

Value:2
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/users?page_before=xmpl01HNFZM7Q8FXASZXYZ6XM3TQRR&page_after=xmpl01HNFZM7Q8FXASZXYZ6XM3TQRR&page_size=10&expand=default_location.tariff&email=user%40example.com&program_id=prog01JCDYNYDWHS7VN72SJ05X0NFR&include_deleted=true' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'EvEnergy-User: user01HN2NJ9NMRZBXT1H6FT9N7735' \
  -H 'EvEnergy-Version: 2'

Responses

Returns a list of Users.

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.

Value:2
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
Array [
idstringuser[A-Z\d]{26}read-onlyrequired

Unique identifier for the given user.

Example:"user01HN2NJ9NMRZBXT1H6FT9N7735"
urlstring, (uri)read-onlyrequired
Example:"https://api.ev.energy/v2/users/user01HN2NJ9NMRZBXT1H6FT9N7735"
emailstring, (email)
full_namestringread-only

The user's full name.

Example:"Frodo Baggins"
joined_atstring, (date-time)read-only

The date and time when the user joined the platform.

Example:"2023-06-15T10:00:00Z"
deleted_atstring or null, (date-time)read-only

When the user's account was deleted, or null if it is still live. Deleted accounts are anonymised, so the remaining fields hold placeholder values rather than the user's data. Reaching a deleted user requires include_deleted=true.

Example:"2024-08-01T12:00:00Z"
default_locationLocation (object)
Any of:

Location model for charging locations.

Address validation: Address fields are optional as a group, but each field independently triggers the requirement. If any of address_1, address_2, city, state, postal_code, country_code, or coordinates is provided with a non-null value, then address_1, city, postal_code, and country_code must all be provided as non-null values. Sending the keys with explicit null values is allowed and does not trigger the requirement (this is how addresses are cleared via PATCH). Partial addresses are rejected with a 400.

vehiclesArray of strings, (uri)read-only
Example:
[
  "https://api.ev.energy/v2/vehicles/vhcl01HRFF3SEVSCRAV9B3CHVDFN0H"
]
evsesArray of strings, (uri)read-only
Example:
[
  "https://api.ev.energy/v2/evses/evse01HSH04XHZCT92RN018F0236ZM"
]
]
Response
[
  {
    "id": "user01HN2NJ9NMRZBXT1H6FT9N7735",
    "url": "https://api.ev.energy/v2/users/user01HN2NJ9NMRZBXT1H6FT9N7735",
    "email": "user@example.com",
    "full_name": "Frodo Baggins",
    "joined_at": "2023-06-15T10:00:00Z",
    "terms_consent_datetime": "2023-06-15T10:00:00Z",
    "deleted_at": "2024-08-01T12:00:00Z",
    "default_location": { … },
    "vehicles": [ … ],
    "evses": [ … ]
  }
]