Skip to content

Users

Endpoints for interacting with users.

Schemas
Operations

User

A resource that represents an individual user in the ev.energy system.

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"
]
{
  "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": {
    "redeemed_count": 3,
    "qualified_count": 2,
    "in_progress_count": 1,
    "rewarded_count": 1
  },
  "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": {
    "address_1": "string",
    "address_2": "string",
    "postal_code": "string",
    "country_code": "AD",
    "coordinates": { … },
    "tariff": "https://api.ev.energy/v2/tariffs/tari01HN2NJ9NMRZBXT1H6FT9N7735",
    "city": "string",
    "state": "string",
    "evse_site": "string"
  },
  "vehicles": [
    "https://api.ev.energy/v2/vehicles/vhcl01HRFF3SEVSCRAV9B3CHVDFN0H"
  ],
  "evses": [
    "https://api.ev.energy/v2/evses/evse01HSH04XHZCT92RN018F0236ZM"
  ]
}