# List users

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

Endpoint: GET /users
Version: 2.0
Security: oauth2

## Query parameters:

  - `page_before` (string)
    Return results from the page after this ID.

  - `page_after` (string)
    Return results from the page before this ID.

  - `page_size` (integer)
    Specify the number of results to return per page.

  - `expand` (array)
    Specify a url field to expand into a nested resource.

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

  - `program_id` (string)
    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.

  - `include_deleted` (boolean)
    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.

## Header parameters:

  - `EvEnergy-Version` (number)
    Specify the version of this endpoint to use.

  - `EvEnergy-User` (string)
    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.

## Response 200 fields (application/json):

  - `id` (string, required)
    Unique identifier for the given user.
    Example: user01HN2NJ9NMRZBXT1H6FT9N7735

  - `url` (string, required)
    Example: https://api.ev.energy/v2/users/user01HN2NJ9NMRZBXT1H6FT9N7735

  - `email` (string)

  - `full_name` (string)
    The user's full name.
    Example: Frodo Baggins

  - `joined_at` (string)
    The date and time when the user joined the platform.
    Example: 2023-06-15T10:00:00Z

  - `terms_consent_datetime` (string | null)
    When the user gave their terms and conditions consent, or null if they have not.
    Example: 2023-06-15T10:00:00Z

  - `deleted_at` (string | null)
    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_location` (any)
    LocationDetail is served when a single user is requested, otherwise Location is served for user lists.

  - `default_location.address_1` (string | null)
    First line of address.

  - `default_location.address_2` (string | null)
    Second line of address.

  - `default_location.postal_code` (string | null)
    Postal Code.

  - `default_location.country_code` (string)
    ISO 3166-1 2 letter Country Codes.
    Enum: "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "YE", "YT", "ZA", "ZM", "ZW"

  - `default_location.coordinates` (any)

  - `default_location.coordinates.latitude` (number, required)
    Example: 51.52576576674041

  - `default_location.coordinates.longitude` (number, required)
    Example: -0.08366433371722264

  - `default_location.tariff` (any)

  - `default_location.tariff.id` (string, required)
    Unique identifier for the given user.
    Example: tari01HN2NJ9NMRZBXT1H6FT9N7735

  - `default_location.tariff.url` (string, required)
    Example: https://api.ev.energy/v2/tariffs/tari01HN2NJ9NMRZBXT1H6FT9N7735

  - `default_location.tariff.supplier` (any, required)
    The energy company that supplies this tariff.

  - `default_location.tariff.supplier.id` (string, required)
    Unique identifier for the given user.
    Example: supl01HN2NJ9NMRZBXT1H6FT9N7735

  - `default_location.tariff.supplier.url` (string, required)
    Example: https://api.ev.energy/v2/suppliers/supl01HN2NJ9NMRZBXT1H6FT9N7735

  - `default_location.tariff.supplier.name` (string, required)
    Example: Rivendell Renewables

  - `default_location.tariff.supplier.icon` (string | null, required)
    Example: https://cdn.example.com/rivendell_renewables.jpg

  - `default_location.tariff.supplier.highlighted` (boolean)
    A highlighted supplier is one that is often selected by users.

  - `default_location.tariff.name` (string, required)
    Example: Fangorn Biomass

  - `default_location.tariff.currency` (string, required)
    Example: GBP

  - `default_location.tariff.highlighted` (boolean)
    A highlighted tariff is one that is often selected by users.

  - `default_location.tariff.type` (string)
    Enum: "FLAT_RATE", "DUAL_RATE", "THREE_RATE", "DYNAMIC", "EXTERNALLY_MANAGED", "OTHER"

  - `default_location.tariff.daily_prices` (object)
    Information about the tariff's prices for different parts of the day.

  - `default_location.tariff.daily_prices.peak` (object, required)
    A single price for a certain time range.

  - `default_location.tariff.daily_prices.peak.price` (string)
    The price is in major currency units e.g. 0.10 means £0.10.
    Example: 0.10

  - `default_location.tariff.daily_prices.peak.times` (array)

  - `default_location.tariff.daily_prices.peak.times.start` (string)
    Example: 18:00:00

  - `default_location.tariff.daily_prices.peak.times.end` (string)
    Example: 00:00:00

  - `default_location.tariff.timezone_name` (string)
    Example: Europe/London

  - `default_location.tariff.price_chart_url` (string | null)
    The url of a website which can display a chart of prices for the tariff. This website is an external resource and is not affiliated with ev.energy.
    Example: https://www.example.com/

  - `default_location.tariff.gsp_group` (string | null)
    The GB Grid Supply Point (DNO region) the tariff applies to. Suppliers publish region-specific rates, so the same named tariff can appear once per region with differing prices; this field distinguishes them. `null` for tariffs that are not region-specific.
    Example: _C

  - `default_location.tariff.valid_from` (string)
    The date from which this tariff became available to new customers.
    Example: 2026-03-17

  - `default_location.tariff.valid_until` (string | null)
    The date after which this tariff is no longer available to new customers (it has been superseded). `null` if the tariff is still open to new sign-ups. Use the `valid` query parameter to filter the list to only currently-available tariffs.
    Example: 2027-03-17

  - `default_location.tariff.scheduler_tariff` (any)
    The tariff used by the scheduler for charge optimisation, which may differ from the billing tariff. Returns a URL by default, or null if not set. Expandable with ?expand=scheduler_tariff to return a TariffBase object (additional fields may be present beyond those listed here).

  - `default_location.tariff.scheduler_tariff.id` (string, required)

  - `default_location.tariff.scheduler_tariff.url` (string, required)

  - `default_location.tariff.scheduler_tariff.supplier` (string, required)

  - `default_location.tariff.scheduler_tariff.name` (string, required)

  - `default_location.tariff.scheduler_tariff.currency` (string, required)

  - `default_location.city` (string | null)

  - `default_location.state` (string | null)

  - `default_location.evse_site` (any)
    If null, the user's location is not an EVSE Site. Otherwise, this field references the site they are a part of.

  - `default_location.evse_site.id` (string, required)

  - `default_location.evse_site.url` (string, required)
    Example: https://api.ev.energy/v2/evse_sites/site01JX2SZ0WAFTDYVYY0JRAYREY7

  - `default_location.evse_site.evses` (array, required)
    A list of all EVSEs that are currently associated with this site.

  - `default_location.evse_site.cpms_connection` (string | null, required)
    The type of ChargePoint Management System that this site is connected to, if there is one.
    Enum: null, "CHARGEPOINT", "SWTCH"

  - `default_location.evse_site.cpms_connection_display_name` (string | null)
    A human-readable name for the Chargepoint Management System that the site is connected to.
    Example: ChargePoint

  - `default_location.evse_site.user_connected` (boolean | null)
    When authenticated as a specific user (eg. via the Authorisation Code grant type) or when the EvEnergy-User header is set to a valid user ID, this field will indicate whether the user is currently connected to this EVSE Site's CPMS. If the request is not made in the context of a user, or the site does not have a CPMS connection, this field will be null.

  - `default_location.current_carbon_intensity_grams_per_kilowatt_hour` (integer | null)
    The current carbon intensity associated with the location in gCO2/kWh.
    Example: 300

  - `vehicles` (array)

  - `evses` (array)

## Response 400 fields (application/problem+json):

  - `type` (string)
    Example: https://api.ev.energy/v2/problems/example-problem/

  - `status` (number)
    Example: 400

  - `title` (string, required)
    Example: Short description

  - `detail` (string, required)
    Example: Long, more specific description.

  - `instance` (string)
    Example: https://api.ev.energy/v2/users/user01HN2P75GBNFRJPCZJXEFVXH5E

  - `notification` (object)
    Something that the user should be informed about.

  - `notification.id` (string, required)
    Unique identifier for the Notification
    Example: notf67O36PLTFDB57M0E5L33JZLGM0

  - `notification.url` (string, required)
    Example: https://api.ev.energy/notifications/notf67O36PLTFDB57M0E5L33JZLGM0

  - `notification.message_id` (string, required)
    Internal identifier for this notification type. E.g. 'ERR0023'

  - `notification.category` (string, required)
    Category of this notification type
    Enum: "ACTIONABLE", "SERVICE", "RETRY", "MARKETING", "INTERNAL"

  - `notification.event_time` (string, required)
    The timestamp of the event described by this notification

  - `notification.short_text_title` (string, required)
    Short title for the notification

  - `notification.short_text_body` (string, required)
    Short description of the event being notified

  - `notification.detail_page_title` (string, required)
    Title of a help page giving more information about this notification

  - `notification.detail_page_body` (string, required)
    Text of a help page giving more information about this notification

  - `notification.external_link` (string | null, required)
    URL of a web page giving further information about this notification

  - `notification.external_button_label` (string, required)
    Text to be displayed on a button leading to the external_link location

  - `notification.read_at` (string)
    When the user examined the contents of this notification

  - `notification.resolved_at` (string)
    When the problem associated with this notification was resolved

## Response 401 fields (application/problem+json):

  - `status` (number)
    Example: 401

  - `title` (string, required)
    Example: Unauthorized

  - `detail` (string, required)
    Example: Authentication credentials were not provided.

## Response 403 fields (application/problem+json):

  - `status` (number)
    Example: 403

  - `title` (string, required)
    Example: Forbidden

  - `detail` (string, required)
    Example: You do not have permission to perform this action.

## Response 406 fields (application/problem+json):

  - `status` (number)
    Example: 406

  - `title` (string, required)
    Example: Not Acceptable

  - `detail` (string, required)
    Example: Could not satisfy the request Accept header.

## Response 429 fields (application/problem+json):

  - `type` (string)
    Example: https://api.ev.energy/v2/problems/example-problem/

  - `status` (number)
    Example: 400

  - `title` (string, required)
    Example: Short description

  - `detail` (string, required)
    Example: Long, more specific description.

  - `instance` (string)
    Example: https://api.ev.energy/v2/users/user01HN2P75GBNFRJPCZJXEFVXH5E

  - `notification` (object)
    Something that the user should be informed about.

  - `notification.id` (string, required)
    Unique identifier for the Notification
    Example: notf67O36PLTFDB57M0E5L33JZLGM0

  - `notification.url` (string, required)
    Example: https://api.ev.energy/notifications/notf67O36PLTFDB57M0E5L33JZLGM0

  - `notification.message_id` (string, required)
    Internal identifier for this notification type. E.g. 'ERR0023'

  - `notification.category` (string, required)
    Category of this notification type
    Enum: "ACTIONABLE", "SERVICE", "RETRY", "MARKETING", "INTERNAL"

  - `notification.event_time` (string, required)
    The timestamp of the event described by this notification

  - `notification.short_text_title` (string, required)
    Short title for the notification

  - `notification.short_text_body` (string, required)
    Short description of the event being notified

  - `notification.detail_page_title` (string, required)
    Title of a help page giving more information about this notification

  - `notification.detail_page_body` (string, required)
    Text of a help page giving more information about this notification

  - `notification.external_link` (string | null, required)
    URL of a web page giving further information about this notification

  - `notification.external_button_label` (string, required)
    Text to be displayed on a button leading to the external_link location

  - `notification.read_at` (string)
    When the user examined the contents of this notification

  - `notification.resolved_at` (string)
    When the problem associated with this notification was resolved