Skip to content
/
List users

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""program""tier"
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. Send true or false; an empty value counts as absent. Other spellings, such as 1 or 0, will be rejected with an invalid-query-parameter-value problem.

Default:false
Example:include_deleted=true
orderingstring

Order the list by ID. id, the default, lists the oldest users first; -id lists the newest first. IDs sort by when the account was created. An empty value is treated as absent and uses the default order. Page links keep the ordering. Any other value will be rejected with an invalid-query-parameter-value problem.

Default:"id"
Enum:"id""-id"
Example:ordering=-id
enrollment_statusstring

Filter users by their enrollment_status in your programs. ENROLLED lists users with an open enrollment in one of them; LEFT lists users whose latest enrollment in them has ended. Users who have never enrolled in one of your programs match neither. Any other value will be rejected with an invalid-query-parameter-value problem.

Enum:"ENROLLED""LEFT"
Example:enrollment_status=LEFT
tier_idstringtier[A-Z\d]{26}

Filter users by their tier in your programs, given as a Program Tier ID. Matches users whose tier link points at that tier, which is their open enrollment if they have one and otherwise their latest ended one; a user who has moved on from the tier does not match. An unknown Program Tier ID, or a tier outside your programs, yields an empty page, and an empty value leaves the list unfiltered.

Example:tier_id=tier01JCK1HPNAANB8WN253G27SFPC
searchstring, >= 3 characters^\s*\S[\s\S]+\S\s*$

Filter users whose name, first name, last name or email contains this text, ignoring case. The four fields are searched as one space-separated string, so text containing a space can also match across two adjacent fields (for example smith john matches a user named John Smith). Leading and trailing whitespace is trimmed, and the trimmed text must be at least 3 characters or the request is rejected with an invalid-query-parameter-value problem; a value that is only whitespace leaves the list unfiltered. % and _ match themselves. Deleting a user erases their name and email, so a deleted user never matches, even with include_deleted=true.

Example:search=smith
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&ordering=-id&enrollment_status=LEFT&tier_id=tier01JCK1HPNAANB8WN253G27SFPC&search=smith' \
  -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, except enrollment_status, tier_enrolled_at and left_at, which keep their real enrollment history. Reaching a deleted user requires include_deleted=true.

Example:"2024-08-01T12:00:00Z"
referral_codestring or nullread-only

This user's personal referral code.

Example:"FRODO1"
referral_performanceobject(UserReferralPerformance)read-only

How the users who signed up with this user's referral code have progressed, broken down by stage like a promo code's performance. rewarded_count counts referrals this user has been credited for, whether or not the credit has been paid out yet. qualified_count ignores the referral scheme's membership, region and active-window rules and any cap on the referrer's rewards, so it can be higher than rewarded_count.

deletedbooleanread-only

Whether the user's account has been deleted. True exactly when deleted_at is set.

Example:false
enrollment_statusstring or nullread-only

The user's standing in your programs: ENROLLED while they hold an open enrollment in one of them, LEFT once their latest enrollment has ended, or null if they have never enrolled in any of them.

Enum:"ENROLLED""LEFT"null
Example:"ENROLLED"
tier_enrolled_atstring or null, (date-time)read-only

When the enrollment behind enrollment_status began, or null if the user has never enrolled in one of your programs.

Example:"2024-01-10T14:30:00Z"
left_atstring or null, (date-time)read-only

When the enrollment behind enrollment_status ended, or null while it is open or if the user has never enrolled in one of your programs.

Example:null
program(string or null) or Program (object)read-only
One of:

The program of the enrollment behind enrollment_status, or null if the user has never enrolled in one of your programs. Defaults to a url, but can be expanded to the full Program resource via the expand query parameter.

string or null (uri)read-only
tier(string or null) or ProgramTier (object)read-only
One of:

The tier of the enrollment behind enrollment_status, or null if the user has never enrolled in one of your programs. Defaults to a url, but can be expanded to the full ProgramTier resource via the expand query parameter. A hidden tier is still linked, and still embedded when expanded, but its url returns 404. An expanded tier's eligible describes the requesting user (or the driver acted as via EvEnergy-User), not necessarily this user.

string or null (uri)read-only
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",
    "referral_code": "FRODO1",
    "referral_performance": { … },
    "deleted": false,
    "enrollment_status": "ENROLLED",
    "tier_enrolled_at": "2024-01-10T14:30:00Z",
    "left_at": null,
    "program": "https://api.ev.energy/v2/programs/prog01JCDYNYDWHS7VN72SJ05X0NFR",
    "tier": "https://api.ev.energy/v2/programs/prog01JCDYNYDWHS7VN72SJ05X0NFR/tiers/tier01JCDYQR1S6V7HZWX3PA5B0NF1",
    "default_location": { … },
    "vehicles": [ … ],
    "evses": [ … ]
  }
]