openapi: 3.2.0 info: title: ev.energy v2 Users API version: '2.0' contact: email: developers@ev.energy url: developers.ev.energy name: ev.energy developers description: The official API for ev.energy, version 2. license: name: Proprietary url: https://ev.energy termsOfService: '' servers: - url: https://api.ev.energy/v2 description: Live API for both production and sandbox requests. x-internal: false - description: Staging server for internal testing only. url: https://api-staging.ev.energy/v2 x-internal: true security: - oauth2: [] tags: - name: Users description: Endpoints for interacting with users. paths: /users: get: summary: List users tags: - Users responses: '200': description: Returns a list of Users. content: application/json: schema: type: array items: $ref: '#/components/schemas/User' headers: Link: $ref: '#/components/headers/link' EvEnergy-Version: $ref: '#/components/headers/version-2' X-RateLimit-Limit: $ref: '#/components/headers/x-ratelimit-limit' X-RateLimit-Remaining: $ref: '#/components/headers/x-ratelimit-remaining' RetryAfter: $ref: '#/components/headers/retry-after' '400': $ref: '#/components/responses/Problem400BadRequestList' '401': $ref: '#/components/responses/Problem401Unauthorized' '403': $ref: '#/components/responses/Problem403Forbidden' '406': $ref: '#/components/responses/Problem406NotAcceptable' '429': $ref: '#/components/responses/Problem429TooManyRequests' operationId: get-users description: List all the users that the authorization token has access to. parameters: - $ref: '#/components/parameters/previous' - $ref: '#/components/parameters/next' - $ref: '#/components/parameters/page_size' - $ref: '#/components/parameters/expand-on-user' - $ref: '#/components/parameters/email' - $ref: '#/components/parameters/version-2' - $ref: '#/components/parameters/user' security: - oauth2: - user:read post: summary: Create user tags: - Users responses: '201': description: User Created Successfully. content: application/json: schema: $ref: '#/components/schemas/User' '400': $ref: '#/components/responses/Problem400BadRequestRetrieve' '401': $ref: '#/components/responses/Problem401Unauthorized' '403': $ref: '#/components/responses/Problem403Forbidden' '404': $ref: '#/components/responses/Problem404NotFound' '406': $ref: '#/components/responses/Problem406NotAcceptable' '429': $ref: '#/components/responses/Problem429TooManyRequests' operationId: post-users security: - oauth2: - user:write description: Create an individual user in the ev.energy system. parameters: - $ref: '#/components/parameters/version-2' requestBody: content: application/json: schema: $ref: '#/components/schemas/User' multipart/form-data: schema: $ref: '#/components/schemas/User' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/User' /users/{user_id}: parameters: - $ref: '#/components/parameters/user_id' get: summary: Retrieve user description: Retrieve information about a single, specific user. tags: - Users responses: '200': description: Returns a single User. content: application/json: schema: $ref: '#/components/schemas/User' headers: EvEnergy-Version: $ref: '#/components/headers/version-2' X-RateLimit-Limit: $ref: '#/components/headers/x-ratelimit-limit' X-RateLimit-Remaining: $ref: '#/components/headers/x-ratelimit-remaining' RetryAfter: $ref: '#/components/headers/retry-after' '400': $ref: '#/components/responses/Problem400BadRequestRetrieve' '401': $ref: '#/components/responses/Problem401Unauthorized' '403': $ref: '#/components/responses/Problem403Forbidden' '404': $ref: '#/components/responses/Problem404NotFound' '406': $ref: '#/components/responses/Problem406NotAcceptable' '429': $ref: '#/components/responses/Problem429TooManyRequests' operationId: get-users-user_id parameters: - $ref: '#/components/parameters/expand-on-user' - $ref: '#/components/parameters/version-2' security: - oauth2: - user:read patch: summary: Update User tags: - Users responses: '200': description: User updated successfully. headers: EvEnergy-Version: $ref: '#/components/headers/version-2' X-RateLimit-Limit: $ref: '#/components/headers/x-ratelimit-limit' X-RateLimit-Remaining: $ref: '#/components/headers/x-ratelimit-remaining' content: application/json: schema: $ref: '#/components/schemas/User' '400': $ref: '#/components/responses/Problem400BadRequestRetrieve' '401': $ref: '#/components/responses/Problem401Unauthorized' '403': $ref: '#/components/responses/Problem403Forbidden' '404': $ref: '#/components/responses/Problem404NotFound' '406': $ref: '#/components/responses/Problem406NotAcceptable' '429': $ref: '#/components/responses/Problem429TooManyRequests' operationId: patch-users-user_id security: - oauth2: - user:write description: Update user information. requestBody: content: application/json: schema: $ref: '#/components/schemas/User' multipart/form-data: schema: $ref: '#/components/schemas/User' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/User' parameters: - $ref: '#/components/parameters/version-2' - $ref: '#/components/parameters/expand-on-user' /users/{user_id}/notification_preferences: parameters: - $ref: '#/components/parameters/user_id' get: summary: Retrieve user notification preferences description: Retrieve the set of notification groups the user is currently subscribed to. tags: - Users responses: '200': description: Returns the user's notification preferences. content: application/json: schema: $ref: '#/components/schemas/UserNotificationPreferences' headers: EvEnergy-Version: $ref: '#/components/headers/version-2' X-RateLimit-Limit: $ref: '#/components/headers/x-ratelimit-limit' X-RateLimit-Remaining: $ref: '#/components/headers/x-ratelimit-remaining' RetryAfter: $ref: '#/components/headers/retry-after' '400': $ref: '#/components/responses/Problem400BadRequestRetrieve' '401': $ref: '#/components/responses/Problem401Unauthorized' '403': $ref: '#/components/responses/Problem403Forbidden' '404': $ref: '#/components/responses/Problem404NotFound' '405': $ref: '#/components/responses/Problem405MethodNotAllowed' '406': $ref: '#/components/responses/Problem406NotAcceptable' '429': $ref: '#/components/responses/Problem429TooManyRequests' operationId: get-users-user_id-notification_preferences parameters: - $ref: '#/components/parameters/version-2' security: - oauth2: - notification_preferences:read patch: summary: Update user notification preferences description: 'Update the user''s notification group opt-in state. The `groups` object is treated as a partial map: only the keys you include are modified. Keys you omit are left untouched. This means clients only need to send the groups they want to change, and adding new groups to the API in the future cannot accidentally clobber an old client''s silence on them. `PATCH {}` and `PATCH {"groups": {}}` are valid no-ops. Unknown group names produce a `400`.' tags: - Users responses: '200': description: Notification preferences updated successfully. content: application/json: schema: $ref: '#/components/schemas/UserNotificationPreferences' headers: EvEnergy-Version: $ref: '#/components/headers/version-2' X-RateLimit-Limit: $ref: '#/components/headers/x-ratelimit-limit' X-RateLimit-Remaining: $ref: '#/components/headers/x-ratelimit-remaining' '400': $ref: '#/components/responses/Problem400UpdateNotificationPreferencesValidationFailed' '401': $ref: '#/components/responses/Problem401Unauthorized' '403': $ref: '#/components/responses/Problem403Forbidden' '404': $ref: '#/components/responses/Problem404NotFound' '405': $ref: '#/components/responses/Problem405MethodNotAllowed' '406': $ref: '#/components/responses/Problem406NotAcceptable' '429': $ref: '#/components/responses/Problem429TooManyRequests' operationId: patch-users-user_id-notification_preferences security: - oauth2: - notification_preferences:write requestBody: content: application/json: schema: $ref: '#/components/schemas/UserNotificationPreferences' parameters: - $ref: '#/components/parameters/version-2' /users/{user_id}/route_planner_preferences: parameters: - $ref: '#/components/parameters/user_id' get: summary: Retrieve route planner preferences description: 'Retrieve the user''s EV Route Planner preferences (default vehicle, en-route minimum charger power, and default arrival battery floor). A preferences row is created with defaults on first access, so this never 404s for an existing, accessible user.' tags: - Users operationId: get-users-user_id-route_planner_preferences responses: '200': description: Returns the user's route planner preferences. content: application/json: schema: $ref: '#/components/schemas/RoutePlannerPreferences' headers: EvEnergy-Version: $ref: '#/components/headers/version-2' X-RateLimit-Limit: $ref: '#/components/headers/x-ratelimit-limit' X-RateLimit-Remaining: $ref: '#/components/headers/x-ratelimit-remaining' RetryAfter: $ref: '#/components/headers/retry-after' '400': $ref: '#/components/responses/Problem400BadRequestRetrieve' '401': $ref: '#/components/responses/Problem401Unauthorized' '403': $ref: '#/components/responses/Problem403Forbidden' '404': $ref: '#/components/responses/Problem404NotFound' '405': $ref: '#/components/responses/Problem405MethodNotAllowed' '406': $ref: '#/components/responses/Problem406NotAcceptable' '429': $ref: '#/components/responses/Problem429TooManyRequests' parameters: - $ref: '#/components/parameters/version-2' security: - oauth2: - route_planner_preferences:read patch: summary: Update route planner preferences description: 'Update the user''s EV Route Planner preferences. The body is treated as a partial map: only the keys you include are modified, omitted keys are left untouched. `PATCH {}` is a valid no-op. `preferred_vehicle` accepts a vehicle URL or `null`; `min_charger_power_watts` accepts one of `22000, 50000, 100000, 150000, 250000` or `null`.' tags: - Users operationId: patch-users-user_id-route_planner_preferences responses: '200': description: Route planner preferences updated successfully. content: application/json: schema: $ref: '#/components/schemas/RoutePlannerPreferences' headers: EvEnergy-Version: $ref: '#/components/headers/version-2' X-RateLimit-Limit: $ref: '#/components/headers/x-ratelimit-limit' X-RateLimit-Remaining: $ref: '#/components/headers/x-ratelimit-remaining' '400': $ref: '#/components/responses/Problem400UpdateRoutePlannerPreferencesValidationFailed' '401': $ref: '#/components/responses/Problem401Unauthorized' '403': $ref: '#/components/responses/Problem403Forbidden' '404': $ref: '#/components/responses/Problem404NotFound' '405': $ref: '#/components/responses/Problem405MethodNotAllowed' '406': $ref: '#/components/responses/Problem406NotAcceptable' '429': $ref: '#/components/responses/Problem429TooManyRequests' security: - oauth2: - route_planner_preferences:write requestBody: content: application/json: schema: $ref: '#/components/schemas/RoutePlannerPreferencesUpdate' parameters: - $ref: '#/components/parameters/version-2' /users/{user_id}/payout_method: parameters: - $ref: '#/components/parameters/user_id' get: summary: Retrieve payout method description: 'Retrieve the user''s preferred payout method. Returns null fields when the user has not set up a payout method. ' tags: - Users operationId: get-users-user_id-payout-method responses: '200': description: Returns the user's payout method. content: application/json: schema: $ref: '#/components/schemas/PayoutMethod' headers: EvEnergy-Version: $ref: '#/components/headers/version-2' X-RateLimit-Limit: $ref: '#/components/headers/x-ratelimit-limit' X-RateLimit-Remaining: $ref: '#/components/headers/x-ratelimit-remaining' RetryAfter: $ref: '#/components/headers/retry-after' '400': $ref: '#/components/responses/Problem400BadRequestRetrieve' '401': $ref: '#/components/responses/Problem401Unauthorized' '403': $ref: '#/components/responses/Problem403Forbidden' '404': $ref: '#/components/responses/Problem404NotFound' '405': $ref: '#/components/responses/Problem405MethodNotAllowed' '406': $ref: '#/components/responses/Problem406NotAcceptable' '429': $ref: '#/components/responses/Problem429TooManyRequests' parameters: - $ref: '#/components/parameters/version-2' security: - oauth2: - payout_method:read patch: summary: Update payout method description: 'Create or update the user''s preferred payout method. The request must always include `receiver_wallet`. For `PAYPAL` and `VENMO` the client must also supply `receiver` (an email or phone respectively). For `BILL_CREDITS` the `receiver` must not be supplied — it is derived server-side from the user''s linked billing account. ' tags: - Users operationId: patch-users-user_id-payout-method responses: '200': description: Payout method updated successfully. content: application/json: schema: $ref: '#/components/schemas/PayoutMethod' headers: EvEnergy-Version: $ref: '#/components/headers/version-2' X-RateLimit-Limit: $ref: '#/components/headers/x-ratelimit-limit' X-RateLimit-Remaining: $ref: '#/components/headers/x-ratelimit-remaining' '400': $ref: '#/components/responses/Problem400UpdatePayoutMethodValidationFailed' '401': $ref: '#/components/responses/Problem401Unauthorized' '403': $ref: '#/components/responses/Problem403Forbidden' '404': $ref: '#/components/responses/Problem404NotFound' '405': $ref: '#/components/responses/Problem405MethodNotAllowed' '406': $ref: '#/components/responses/Problem406NotAcceptable' '429': $ref: '#/components/responses/Problem429TooManyRequests' parameters: - $ref: '#/components/parameters/version-2' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PayoutMethodUpdate' security: - oauth2: - payout_method:write delete: summary: Delete payout method description: 'Clear the user''s preferred payout method. The user''s stored ``UserPayoutMethod`` records are not removed; only the ``preferred_payout_method`` link on the user is cleared. Returns 204 even when the user already has no payout method set (no-op). ' tags: - Users operationId: delete-users-user_id-payout-method responses: '204': description: Payout method cleared. headers: EvEnergy-Version: $ref: '#/components/headers/version-2' X-RateLimit-Limit: $ref: '#/components/headers/x-ratelimit-limit' X-RateLimit-Remaining: $ref: '#/components/headers/x-ratelimit-remaining' '400': $ref: '#/components/responses/Problem400BadRequestRetrieve' '401': $ref: '#/components/responses/Problem401Unauthorized' '403': $ref: '#/components/responses/Problem403Forbidden' '404': $ref: '#/components/responses/Problem404NotFound' '405': $ref: '#/components/responses/Problem405MethodNotAllowed' '406': $ref: '#/components/responses/Problem406NotAcceptable' '429': $ref: '#/components/responses/Problem429TooManyRequests' parameters: - $ref: '#/components/parameters/version-2' security: - oauth2: - payout_method:write /users/{user_id}/saved_routes: parameters: - $ref: '#/components/parameters/user_id' get: summary: List saved routes description: 'List the user''s saved route-planner routes. A saved route is a reusable "recipe" — origin, destination, waypoints and planning preferences — not a stored charging plan; the plan is recalculated on each re-plan. ' tags: - Users operationId: get-users-user_id-saved_routes responses: '200': description: Returns the user's saved routes. content: application/json: schema: type: array items: $ref: '#/components/schemas/SavedRoute' headers: Link: $ref: '#/components/headers/link' EvEnergy-Version: $ref: '#/components/headers/version-2' X-RateLimit-Limit: $ref: '#/components/headers/x-ratelimit-limit' X-RateLimit-Remaining: $ref: '#/components/headers/x-ratelimit-remaining' RetryAfter: $ref: '#/components/headers/retry-after' '400': $ref: '#/components/responses/Problem400BadRequestList' '401': $ref: '#/components/responses/Problem401Unauthorized' '403': $ref: '#/components/responses/Problem403Forbidden' '404': $ref: '#/components/responses/Problem404NotFound' '405': $ref: '#/components/responses/Problem405MethodNotAllowed' '406': $ref: '#/components/responses/Problem406NotAcceptable' '429': $ref: '#/components/responses/Problem429TooManyRequests' parameters: - $ref: '#/components/parameters/version-2' - $ref: '#/components/parameters/previous' - $ref: '#/components/parameters/next' - $ref: '#/components/parameters/page_size' security: - oauth2: - saved_routes:read post: summary: Create a saved route description: 'Create a new saved route for the user. The route is owned by the user named in the path; `id`, `url`, `user` and `created_at` are assigned by the server. `last_used_at` defaults to now when omitted. A user may save at most 50 routes; exceeding this returns a `400`. ' tags: - Users operationId: post-users-user_id-saved_routes requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SavedRouteCreate' responses: '201': description: The saved route was created. content: application/json: schema: $ref: '#/components/schemas/SavedRoute' headers: EvEnergy-Version: $ref: '#/components/headers/version-2' X-RateLimit-Limit: $ref: '#/components/headers/x-ratelimit-limit' X-RateLimit-Remaining: $ref: '#/components/headers/x-ratelimit-remaining' '400': $ref: '#/components/responses/Problem400SavedRouteValidationFailed' '401': $ref: '#/components/responses/Problem401Unauthorized' '403': $ref: '#/components/responses/Problem403Forbidden' '404': $ref: '#/components/responses/Problem404NotFound' '405': $ref: '#/components/responses/Problem405MethodNotAllowed' '406': $ref: '#/components/responses/Problem406NotAcceptable' '429': $ref: '#/components/responses/Problem429TooManyRequests' parameters: - $ref: '#/components/parameters/version-2' security: - oauth2: - saved_routes:write /users/{user_id}/saved_routes/{saved_route_id}: parameters: - $ref: '#/components/parameters/user_id' - $ref: '#/components/parameters/saved_route_id' get: summary: Retrieve a saved route tags: - Users operationId: get-users-user_id-saved_routes-saved_route_id responses: '200': description: Returns the saved route. content: application/json: schema: $ref: '#/components/schemas/SavedRoute' headers: EvEnergy-Version: $ref: '#/components/headers/version-2' X-RateLimit-Limit: $ref: '#/components/headers/x-ratelimit-limit' X-RateLimit-Remaining: $ref: '#/components/headers/x-ratelimit-remaining' RetryAfter: $ref: '#/components/headers/retry-after' '400': $ref: '#/components/responses/Problem400BadRequestRetrieve' '401': $ref: '#/components/responses/Problem401Unauthorized' '403': $ref: '#/components/responses/Problem403Forbidden' '404': $ref: '#/components/responses/Problem404NotFound' '405': $ref: '#/components/responses/Problem405MethodNotAllowed' '406': $ref: '#/components/responses/Problem406NotAcceptable' '429': $ref: '#/components/responses/Problem429TooManyRequests' parameters: - $ref: '#/components/parameters/version-2' security: - oauth2: - saved_routes:read patch: summary: Update a saved route description: 'Partially update a saved route: rename it, toggle `favourite`, bump `last_used_at` after a re-plan, or edit the endpoints. Only the fields supplied are changed. ' tags: - Users operationId: patch-users-user_id-saved_routes-saved_route_id requestBody: content: application/json: schema: $ref: '#/components/schemas/SavedRoutePatch' responses: '200': description: The saved route was updated. content: application/json: schema: $ref: '#/components/schemas/SavedRoute' headers: EvEnergy-Version: $ref: '#/components/headers/version-2' X-RateLimit-Limit: $ref: '#/components/headers/x-ratelimit-limit' X-RateLimit-Remaining: $ref: '#/components/headers/x-ratelimit-remaining' '400': $ref: '#/components/responses/Problem400SavedRouteValidationFailed' '401': $ref: '#/components/responses/Problem401Unauthorized' '403': $ref: '#/components/responses/Problem403Forbidden' '404': $ref: '#/components/responses/Problem404NotFound' '405': $ref: '#/components/responses/Problem405MethodNotAllowed' '406': $ref: '#/components/responses/Problem406NotAcceptable' '429': $ref: '#/components/responses/Problem429TooManyRequests' parameters: - $ref: '#/components/parameters/version-2' security: - oauth2: - saved_routes:write delete: summary: Delete a saved route tags: - Users operationId: delete-users-user_id-saved_routes-saved_route_id responses: '204': description: The saved route was deleted. headers: EvEnergy-Version: $ref: '#/components/headers/version-2' X-RateLimit-Limit: $ref: '#/components/headers/x-ratelimit-limit' X-RateLimit-Remaining: $ref: '#/components/headers/x-ratelimit-remaining' '400': $ref: '#/components/responses/Problem400BadRequestRetrieve' '401': $ref: '#/components/responses/Problem401Unauthorized' '403': $ref: '#/components/responses/Problem403Forbidden' '404': $ref: '#/components/responses/Problem404NotFound' '405': $ref: '#/components/responses/Problem405MethodNotAllowed' '406': $ref: '#/components/responses/Problem406NotAcceptable' '429': $ref: '#/components/responses/Problem429TooManyRequests' parameters: - $ref: '#/components/parameters/version-2' security: - oauth2: - saved_routes:write components: responses: Problem405MethodNotAllowed: description: Could not satisfy this HTTP method. content: application/problem+json: schema: type: object required: - title - detail properties: status: type: number example: 405 title: type: string example: Method Not Allowed detail: type: string example: Could not satisfy this HTTP method. headers: EvEnergy-Version: $ref: '#/components/headers/version-2' X-RateLimit-Limit: $ref: '#/components/headers/x-ratelimit-limit' X-RateLimit-Remaining: $ref: '#/components/headers/x-ratelimit-remaining' RetryAfter: $ref: '#/components/headers/retry-after' Problem404NotFound: description: This resource either does not exist or the client is not authorized to access it. content: application/problem+json: schema: type: object required: - title - detail properties: status: type: number example: 404 title: type: string example: Not found detail: type: string example: Resource does not exist or cannot be accessed. headers: EvEnergy-Version: $ref: '#/components/headers/version-2' X-RateLimit-Limit: $ref: '#/components/headers/x-ratelimit-limit' X-RateLimit-Remaining: $ref: '#/components/headers/x-ratelimit-remaining' RetryAfter: $ref: '#/components/headers/retry-after' Problem400UpdatePayoutMethodValidationFailed: content: application/problem+json: schema: $ref: '#/components/schemas/RFC9457ProblemDetail' examples: Request failed validation: value: type: https://api.ev.energy/v2/problems/validation-failed-update-payout-method/ status: 400 title: Request failed validation. detail: 'Error on fields: receiver' field_errors: receiver: - Required when receiver_wallet is PAYPAL. description: The payout method update request body failed validation. headers: EvEnergy-Version: $ref: '#/components/headers/version-2' X-RateLimit-Limit: $ref: '#/components/headers/x-ratelimit-limit' X-RateLimit-Remaining: $ref: '#/components/headers/x-ratelimit-remaining' Problem400BadRequestRetrieve: content: application/problem+json: schema: $ref: '#/components/schemas/RFC9457ProblemDetail' examples: Unsupported Version: $ref: '#/components/examples/ProblemUnsupportedVersion' description: A problem with the request's parameters prevented it being fulfilled. headers: EvEnergy-Version: $ref: '#/components/headers/version-2' X-RateLimit-Limit: $ref: '#/components/headers/x-ratelimit-limit' X-RateLimit-Remaining: $ref: '#/components/headers/x-ratelimit-remaining' Problem400UpdateNotificationPreferencesValidationFailed: content: application/problem+json: schema: $ref: '#/components/schemas/RFC9457ProblemDetail' examples: Request failed validation: value: type: https://api.ev.energy/v2/problems/validation-failed-update-notification-preferences/ status: 400 title: Request failed validation. detail: 'Error on fields: groups' field_errors: groups: - 'Unknown notification group: ''charging_flower''.' description: The notification preferences update request body failed validation. headers: EvEnergy-Version: $ref: '#/components/headers/version-2' X-RateLimit-Limit: $ref: '#/components/headers/x-ratelimit-limit' X-RateLimit-Remaining: $ref: '#/components/headers/x-ratelimit-remaining' Problem429TooManyRequests: content: application/problem+json: schema: $ref: '#/components/schemas/RFC9457ProblemDetail' examples: Example 1: value: type: https://api.ev.energy/v2/problems/rate-limit-exceeded/ status: 429 title: Too Many Requests detail: Request was rate limited. Try again in 42 seconds description: The client has exceeded its rate limit. headers: EvEnergy-Version: $ref: '#/components/headers/version-2' Retry-After: $ref: '#/components/headers/retry-after' X-RateLimit-Limit: $ref: '#/components/headers/x-ratelimit-limit' X-RateLimit-Remaining: $ref: '#/components/headers/x-ratelimit-remaining' Problem401Unauthorized: description: You need to authorise requests to access this resource. content: application/problem+json: schema: type: object required: - title - detail properties: status: type: number example: 401 title: type: string example: Unauthorized detail: type: string example: Authentication credentials were not provided. headers: EvEnergy-Version: $ref: '#/components/headers/version-2' X-RateLimit-Limit: $ref: '#/components/headers/x-ratelimit-limit' X-RateLimit-Remaining: $ref: '#/components/headers/x-ratelimit-remaining' RetryAfter: $ref: '#/components/headers/retry-after' Problem400BadRequestList: content: application/problem+json: schema: $ref: '#/components/schemas/RFC9457ProblemDetail' examples: Invalid Pagination Parameter: $ref: '#/components/examples/ProblemInvalidPaginationParameter' Unsupported Version: $ref: '#/components/examples/ProblemUnsupportedVersion' description: A problem with the request's parameters prevented it being fulfilled. headers: EvEnergy-Version: $ref: '#/components/headers/version-2' X-RateLimit-Limit: $ref: '#/components/headers/x-ratelimit-limit' X-RateLimit-Remaining: $ref: '#/components/headers/x-ratelimit-remaining' RetryAfter: $ref: '#/components/headers/retry-after' Problem403Forbidden: description: You do not have permission to perform this action. content: application/problem+json: schema: type: object required: - title - detail properties: status: type: number example: 403 title: type: string example: Forbidden detail: type: string example: You do not have permission to perform this action. headers: EvEnergy-Version: $ref: '#/components/headers/version-2' X-RateLimit-Limit: $ref: '#/components/headers/x-ratelimit-limit' X-RateLimit-Remaining: $ref: '#/components/headers/x-ratelimit-remaining' RetryAfter: $ref: '#/components/headers/retry-after' Problem400SavedRouteValidationFailed: content: application/problem+json: schema: $ref: '#/components/schemas/RFC9457ProblemDetail' examples: Request failed validation: value: type: https://api.ev.energy/v2/problems/validation-failed-saved-route/ status: 400 title: Request failed validation. detail: 'Error on fields: arrive_with_min_percent' field_errors: arrive_with_min_percent: - Ensure this value is less than or equal to 100. description: The saved route request body failed validation. headers: EvEnergy-Version: $ref: '#/components/headers/version-2' X-RateLimit-Limit: $ref: '#/components/headers/x-ratelimit-limit' X-RateLimit-Remaining: $ref: '#/components/headers/x-ratelimit-remaining' Problem400UpdateRoutePlannerPreferencesValidationFailed: content: application/problem+json: schema: $ref: '#/components/schemas/RFC9457ProblemDetail' examples: Request failed validation: value: type: https://api.ev.energy/v2/problems/validation-failed-update-route-planner-preferences/ status: 400 title: Request failed validation. detail: 'Error on fields: min_charger_power_watts' field_errors: min_charger_power_watts: - 'Must be null or one of: 22000, 50000, 100000, 150000, 250000.' description: The route planner preferences update request body failed validation. headers: EvEnergy-Version: $ref: '#/components/headers/version-2' X-RateLimit-Limit: $ref: '#/components/headers/x-ratelimit-limit' X-RateLimit-Remaining: $ref: '#/components/headers/x-ratelimit-remaining' Problem406NotAcceptable: description: Could not satisfy the request Accept header. content: application/problem+json: schema: type: object required: - title - detail properties: status: type: number example: 406 title: type: string example: Not Acceptable detail: type: string example: Could not satisfy the request Accept header. headers: EvEnergy-Version: $ref: '#/components/headers/version-2' X-RateLimit-Limit: $ref: '#/components/headers/x-ratelimit-limit' X-RateLimit-Remaining: $ref: '#/components/headers/x-ratelimit-remaining' RetryAfter: $ref: '#/components/headers/retry-after' parameters: user: name: EvEnergy-User description: 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. in: header required: false schema: type: string pattern: user[A-Z\d]{26} example: user01HN2NJ9NMRZBXT1H6FT9N7735 saved_route_id: name: saved_route_id in: path required: true schema: type: string pattern: savr[A-Z\d]{26} example: savr01HRFF3SEVSCRAV9B3CHVDFN0H description: The ID of the specific saved route. version-2: name: EvEnergy-Version description: Specify the version of this endpoint to use. required: false in: header schema: type: number enum: - 2 page_size: name: page_size description: Specify the number of results to return per page. in: query required: false schema: type: integer default: 25 minimum: 1 maximum: 100 example: 10 previous: name: page_before description: Return results from the page after this ID. in: query required: false schema: type: string pattern: '[a-z]{4}[A-Z\d]{26}' example: xmpl01HNFZM7Q8FXASZXYZ6XM3TQRR next: name: page_after description: Return results from the page before this ID. in: query required: false schema: type: string pattern: '[a-z]{4}[A-Z\d]{26}' example: xmpl01HNFZM7Q8FXASZXYZ6XM3TQRR expand-on-user: name: expand in: query schema: type: array items: type: string enum: - default_location.tariff - default_location.tariff.supplier - default_location.evse_site explode: true description: Specify a url field to expand into a nested resource. user_id: name: user_id in: path required: true schema: type: string pattern: ^(user[A-Z\d]{26})$ examples: - user01HN2NJ9NMRZBXT1H6FT9N7735 - me description: The ID of the specific user to retrieve. email: name: email in: query required: false schema: type: string format: email example: user@example.com description: Filter users by email address (case-insensitive exact match). schemas: RFC9457ProblemDetail: title: RFC 9457 Problem Detail x-tags: - problems type: object required: - title - detail properties: type: type: string format: uri example: https://api.ev.energy/v2/problems/example-problem/ status: type: number example: 400 title: type: string example: Short description detail: type: string example: Long, more specific description. instance: type: string format: uri example: https://api.ev.energy/v2/users/user01HN2P75GBNFRJPCZJXEFVXH5E notification: $ref: '#/components/schemas/Notification' examples: - type: https://api.ev.energy/v2/problems/example-problem/ status: 400 title: Short description detail: Long, more specific description. instance: https://api.ev.energy/v2/users/user01HN2P75GBNFRJPCZJXEFVXH5E notification: id: notf01HTHKTXVB77901324BCQPF1RB url: https://api.ev.energy/notifications/notf01HTHKTXVB77901324BCQPF1RB 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' Supplier: title: Supplier type: object description: An energy company who supplies electricity tariffs. required: - id - url - name - icon properties: id: type: string description: Unique identifier for the given user. pattern: supl[A-Z\d]{26} example: supl01HN2NJ9NMRZBXT1H6FT9N7735 readOnly: true url: type: string format: uri example: https://api.ev.energy/v2/suppliers/supl01HN2NJ9NMRZBXT1H6FT9N7735 name: type: string example: Rivendell Renewables icon: type: - string - 'null' format: uri example: https://cdn.example.com/rivendell_renewables.jpg highlighted: type: boolean description: A highlighted supplier is one that is often selected by users. x-tags: - Tariffs DailyPrices: title: DailyPrices description: Information about the tariff's prices for different parts of the day. type: object additionalProperties: false minProperties: 1 maxProperties: 3 required: - peak properties: peak: $ref: '#/components/schemas/PriceSummary' mid_peak: $ref: '#/components/schemas/PriceSummary' off_peak: $ref: '#/components/schemas/PriceSummary' x-tags: - Tariffs Notification: title: Notification description: Something that the user should be informed about. type: object examples: - 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' required: - id - url - message_id - category - event_time - short_text_title - short_text_body - detail_page_title - detail_page_body - external_link - external_button_label properties: id: type: string pattern: notf[A-Z\d]{26} example: notf67O36PLTFDB57M0E5L33JZLGM0 description: Unique identifier for the Notification url: type: string format: uri example: https://api.ev.energy/notifications/notf67O36PLTFDB57M0E5L33JZLGM0 message_id: type: string description: Internal identifier for this notification type. E.g. 'ERR0023' category: description: Category of this notification type enum: - ACTIONABLE - SERVICE - RETRY - MARKETING - INTERNAL event_time: type: string format: date-time description: The timestamp of the event described by this notification short_text_title: type: string description: Short title for the notification maxLength: 33 short_text_body: type: string description: Short description of the event being notified maxLength: 49 detail_page_title: type: string description: Title of a help page giving more information about this notification detail_page_body: type: string description: Text of a help page giving more information about this notification external_link: type: - string - 'null' description: URL of a web page giving further information about this notification format: uri external_button_label: type: string description: Text to be displayed on a button leading to the external_link location read_at: type: string format: date-time description: When the user examined the contents of this notification resolved_at: type: string format: date-time description: When the problem associated with this notification was resolved Tariff: title: Tariff examples: - id: tari01HN2NJ9NMRZBXT1H6FT9N7735 url: https://api.ev.energy/v2/tariffs/tari01HN2NJ9NMRZBXT1H6FT9N7735 supplier: https://api.ev.energy/v2/suppliers/supl01HN2NJ9NMRZBXT1H6FT9N7735 name: Fangorn Biomass currency: GBP gsp_group: _C valid_from: '2026-03-17' valid_until: '2027-03-17' daily_prices: peak: price: '0.30' times: - start: '18:00:00' end: 00:00:00 mid_peak: price: '0.20' times: - start: '10:00:00' end: 08:00:00 off_peak: price: '0.10' times: - start: 08:00:00 end: '18:00:00' scheduler_tariff: https://api.ev.energy/v2/tariffs/tari01HN2NJ9NMRZBXT1H6FT9N7835 description: 'Note: daily_prices and type are only available under contract. Please reach out to your account manager to find out more.' x-tags: - Tariffs allOf: - $ref: '#/components/schemas/TariffBase' - type: object properties: scheduler_tariff: oneOf: - type: string format: uri example: https://api.ev.energy/v2/tariffs/tari01HN2NJ9NMRZBXT1H6FT9N7835 - type: object required: - id - url - supplier - name - currency properties: id: type: string pattern: tari[A-Z\d]{26} url: type: string format: uri supplier: type: string format: uri name: type: string currency: type: string additionalProperties: true - type: 'null' description: 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). EVSESite: title: EVSESite type: object description: Represents a place with one or more EVSEs installed which can be accessed by multiple users. required: - id - url - evses - cpms_connection properties: id: type: string pattern: site[A-Z\d]{26} examples: - site01JX2SZ0WAFTDYVYY0JRAYREY7 readOnly: true url: type: string format: uri example: https://api.ev.energy/v2/evse_sites/site01JX2SZ0WAFTDYVYY0JRAYREY7 readOnly: true evses: type: array description: A list of all EVSEs that are currently associated with this site. items: type: string format: uri examples: - https://api.ev.energy/v2/evses/evse01HSH04KDEWF6Z4DB2J77J74K5 readOnly: true cpms_connection: type: - string - 'null' description: The type of ChargePoint Management System that this site is connected to, if there is one. enum: - null - CHARGEPOINT - SWTCH readOnly: true cpms_connection_display_name: type: - string - 'null' description: A human-readable name for the Chargepoint Management System that the site is connected to. example: ChargePoint user_connected: type: - boolean - 'null' description: 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. readOnly: true RoutePlannerPreferencesUpdate: title: RoutePlannerPreferencesUpdate description: 'Request body for `PATCH /users/{user_id}/route_planner_preferences`. All fields are optional; only those supplied are changed.' type: object properties: preferred_vehicle: type: - string - 'null' format: uri description: Vehicle URL to set as default, or null to clear. min_charger_power_watts: type: - integer - 'null' enum: - 22000 - 50000 - 100000 - 150000 - 250000 - null arrive_with_min_percent: type: integer minimum: 0 maximum: 100 SavedRoute: title: SavedRoute description: 'A user''s saved route-planner route — a reusable origin/destination/ waypoints "recipe" plus planning preferences. It deliberately does not store the resulting charging plan, projected state of charge, or weather snapshots; those are recalculated on each re-plan. ' type: object x-tags: - Users required: - id - url - user - name - favourite - origin - destination - waypoints - arrive_with_min_percent - preferred_departure_minutes - created_at - last_used_at properties: id: type: string pattern: savr[A-Z\d]{26} readOnly: true example: savr01HRFF3SEVSCRAV9B3CHVDFN0H url: type: string format: uri readOnly: true example: https://api.ev.energy/v2/users/user01HN2NJ9NMRZBXT1H6FT9N7735/saved_routes/savr01HRFF3SEVSCRAV9B3CHVDFN0H user: type: string format: uri readOnly: true example: https://api.ev.energy/v2/users/user01HN2NJ9NMRZBXT1H6FT9N7735 description: Link to the user who owns this route. name: type: string maxLength: 200 description: User-supplied name for the route. favourite: type: boolean origin: $ref: '#/components/schemas/RoutePoint' destination: $ref: '#/components/schemas/RoutePoint' waypoints: type: array maxItems: 25 description: Ordered intermediate stops. Empty when the route is direct. items: $ref: '#/components/schemas/RoutePoint' arrive_with_min_percent: type: integer minimum: 0 maximum: 100 description: Target battery floor on arrival. preferred_departure_minutes: type: - integer - 'null' minimum: 0 maximum: 1439 description: 'Preferred departure hint as an offset in minutes from midnight of the day the route is re-planned. Null means "leave now". ' created_at: type: string format: date-time readOnly: true last_used_at: type: string format: date-time description: Bumped each time the route is re-planned. PayoutMethodUpdate: title: PayoutMethodUpdate description: 'Request body for `PATCH /users/{user_id}/payout_method`. `receiver_wallet` is always required. For `PAYPAL` and `VENMO` the client must also supply `receiver` (an email or phone respectively). For `BILL_CREDITS`, `receiver` must not be supplied — it is derived server-side from the user''s linked billing account. ' type: object required: - receiver_wallet properties: receiver: type: - string - 'null' maxLength: 254 description: 'Email when `receiver_wallet` is `PAYPAL`, phone when `VENMO`. Must not be supplied when `receiver_wallet` is `BILL_CREDITS`. ' example: alice@example.com receiver_wallet: type: string enum: - PAYPAL - VENMO - BILL_CREDITS CountryCode: description: ISO 3166-1 2 letter Country Codes. type: string 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 LocationDetail: title: Location description: Extra fields only included when a single location is requested but omitted when locations are listed. allOf: - type: object properties: current_carbon_intensity_grams_per_kilowatt_hour: type: - integer - 'null' example: 300 description: The current carbon intensity associated with the location in gCO2/kWh. - $ref: '#/components/schemas/Location' UserNotificationPreferences: title: UserNotificationPreferences description: 'The user''s notification group opt-in state. On `GET`, every known group is returned with its current boolean state. On `PATCH`, only the keys you include are modified; omitted keys are left untouched. `PATCH {}` and `PATCH {"groups": {}}` are valid no-ops. Unknown group names produce a `400`.' type: object x-tags: - Users properties: url: type: string format: uri readOnly: true example: https://api.ev.energy/v2/users/user01HN2NJ9NMRZBXT1H6FT9N7735/notification_preferences groups: type: object description: 'Map of notification group name to opt-in state. Each group corresponds to a category of push/email notifications: - `charging_flow` — session lifecycle updates (plug-in, schedule, complete). - `charging_issues` — errors and failures during a charging session. - `charging_optimisation` — smart-charging schedule and savings updates. - `deals_and_offers` — marketing offers (subject to the user''s marketing consent). - `power_supply_notifications` — grid / power-supply events (feature-flagged).' additionalProperties: false properties: charging_flow: type: boolean charging_issues: type: boolean charging_optimisation: type: boolean deals_and_offers: type: boolean power_supply_notifications: type: boolean example: charging_flow: true charging_issues: true charging_optimisation: false deals_and_offers: false power_supply_notifications: false PriceSummary: title: PriceSummary description: A single price for a certain time range. type: object examples: - price: '0.10' times: - start: '18:00:00' end: 00:00:00 x-tags: - Tariffs properties: price: type: string example: '0.10' description: The price is in major currency units e.g. 0.10 means £0.10. times: type: array items: $ref: '#/components/schemas/Times' RoutePlannerPreferences: title: RoutePlannerPreferences description: 'A user''s sticky EV Route Planner preferences, created with defaults on first access. `PATCH` treats the body as a partial map — only the keys you include are changed.' type: object x-tags: - Users required: - url - preferred_vehicle - min_charger_power_watts - arrive_with_min_percent - updated_at properties: url: type: string format: uri readOnly: true example: https://api.ev.energy/v2/users/user01HN2NJ9NMRZBXT1H6FT9N7735/route_planner_preferences preferred_vehicle: type: - string - 'null' format: uri description: Link to the vehicle selected by default, or null if none is set. example: https://api.ev.energy/v2/vehicles/vhcl01HRFF3SEVSCRAV9B3CHVDFN0H min_charger_power_watts: type: - integer - 'null' enum: - 22000 - 50000 - 100000 - 150000 - 250000 - null description: 'Soft minimum charger power (watts) for en-route charger search. Null means all chargers.' arrive_with_min_percent: type: integer minimum: 0 maximum: 100 description: Default arrival battery floor seeded into new route plans. updated_at: type: string format: date-time readOnly: true SavedRouteCreate: title: SavedRouteCreate description: Request body for `POST /users/{user_id}/saved_routes`. type: object required: - name - origin - destination - arrive_with_min_percent properties: name: type: string maxLength: 200 favourite: type: boolean default: false origin: $ref: '#/components/schemas/RoutePoint' destination: $ref: '#/components/schemas/RoutePoint' waypoints: type: array maxItems: 25 items: $ref: '#/components/schemas/RoutePoint' arrive_with_min_percent: type: integer minimum: 0 maximum: 100 preferred_departure_minutes: type: - integer - 'null' minimum: 0 maximum: 1439 last_used_at: type: string format: date-time Location: title: Location type: object description: '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. ' properties: address_1: type: - string - 'null' description: First line of address. address_2: type: - string - 'null' description: Second line of address. postal_code: type: - string - 'null' description: Postal Code. country_code: anyOf: - $ref: '#/components/schemas/CountryCode' - type: 'null' $ref: '#/components/schemas/CountryCode' coordinates: anyOf: - $ref: '#/components/schemas/LatLong' - type: 'null' tariff: oneOf: - format: uri type: - string - 'null' example: https://api.ev.energy/v2/tariffs/tari01HN2NJ9NMRZBXT1H6FT9N7735 - $ref: '#/components/schemas/Tariff' city: type: - string - 'null' state: type: - string - 'null' evse_site: oneOf: - type: - string - 'null' - $ref: '#/components/schemas/EVSESite' description: If null, the user's location is not an EVSE Site. Otherwise, this field references the site they are a part of. dependentSchemas: address_1: if: properties: address_1: not: type: 'null' then: required: - city - postal_code - country_code properties: city: not: type: 'null' postal_code: not: type: 'null' country_code: not: type: 'null' address_2: if: properties: address_2: not: type: 'null' then: required: - address_1 - city - postal_code - country_code properties: address_1: not: type: 'null' city: not: type: 'null' postal_code: not: type: 'null' country_code: not: type: 'null' city: if: properties: city: not: type: 'null' then: required: - address_1 - postal_code - country_code properties: address_1: not: type: 'null' postal_code: not: type: 'null' country_code: not: type: 'null' state: if: properties: state: not: type: 'null' then: required: - address_1 - city - postal_code - country_code properties: address_1: not: type: 'null' city: not: type: 'null' postal_code: not: type: 'null' country_code: not: type: 'null' postal_code: if: properties: postal_code: not: type: 'null' then: required: - address_1 - city - country_code properties: address_1: not: type: 'null' city: not: type: 'null' country_code: not: type: 'null' country_code: if: properties: country_code: not: type: 'null' then: required: - address_1 - city - postal_code properties: address_1: not: type: 'null' city: not: type: 'null' postal_code: not: type: 'null' coordinates: if: properties: coordinates: not: type: 'null' then: required: - address_1 - city - postal_code - country_code properties: address_1: not: type: 'null' city: not: type: 'null' postal_code: not: type: 'null' country_code: not: type: 'null' SavedRoutePatch: title: SavedRoutePatch description: 'Request body for `PATCH /users/{user_id}/saved_routes/{saved_route_id}`. All fields are optional; only those supplied are changed. ' type: object properties: name: type: string maxLength: 200 favourite: type: boolean origin: $ref: '#/components/schemas/RoutePoint' destination: $ref: '#/components/schemas/RoutePoint' waypoints: type: array maxItems: 25 items: $ref: '#/components/schemas/RoutePoint' arrive_with_min_percent: type: integer minimum: 0 maximum: 100 preferred_departure_minutes: type: - integer - 'null' minimum: 0 maximum: 1439 last_used_at: type: string format: date-time TariffBase: title: TariffBase type: object description: 'Core tariff properties shared by Tariff and expanded scheduler_tariff. Note: daily_prices and type are only available under contract. Please reach out to your account manager to find out more.' x-tags: - Tariffs required: - id - url - supplier - name - currency properties: id: type: string description: Unique identifier for the given user. pattern: tari[A-Z\d]{26} example: tari01HN2NJ9NMRZBXT1H6FT9N7735 readOnly: true url: type: string format: uri example: https://api.ev.energy/v2/tariffs/tari01HN2NJ9NMRZBXT1H6FT9N7735 supplier: oneOf: - type: string format: uri example: https://api.ev.energy/v2/suppliers/supl01HN2NJ9NMRZBXT1H6FT9N7735 - $ref: '#/components/schemas/Supplier' description: The energy company that supplies this tariff. name: type: string example: Fangorn Biomass currency: type: string example: GBP highlighted: type: boolean description: A highlighted tariff is one that is often selected by users. type: enum: - FLAT_RATE - DUAL_RATE - THREE_RATE - DYNAMIC - EXTERNALLY_MANAGED - OTHER daily_prices: $ref: '#/components/schemas/DailyPrices' description: 'The times returned here are localised to the timezone the tariff is in. The timezone is returned in `timezone_name`.' timezone_name: type: string example: Europe/London price_chart_url: type: - string - 'null' description: 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/ gsp_group: type: - string - 'null' description: 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 valid_from: type: string format: date description: The date from which this tariff became available to new customers. example: '2026-03-17' valid_until: type: - string - 'null' format: date description: 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' Times: title: Times description: Defines a period of time. type: object x-tags: - Tariffs properties: start: type: string example: '18:00:00' pattern: \d\d:\d\d:\d\d end: type: string example: 00:00:00 pattern: \d\d:\d\d:\d\d User: title: User description: A resource that represents an individual user in the ev.energy system. type: object x-tags: - Users required: - id - url properties: id: type: string description: Unique identifier for the given user. pattern: user[A-Z\d]{26} example: user01HN2NJ9NMRZBXT1H6FT9N7735 readOnly: true url: type: string example: https://api.ev.energy/v2/users/user01HN2NJ9NMRZBXT1H6FT9N7735 format: uri readOnly: true email: type: string format: email full_name: type: string readOnly: true description: The user's full name. example: Frodo Baggins joined_at: type: string format: date-time readOnly: true description: The date and time when the user joined the platform. example: '2023-06-15T10:00:00Z' terms_consent_datetime: type: - string - 'null' format: date-time readOnly: true description: When the user gave their terms and conditions consent, or null if they have not. example: '2023-06-15T10:00:00Z' default_location: anyOf: - $ref: '#/components/schemas/Location' - $ref: '#/components/schemas/LocationDetail' description: LocationDetail is served when a single user is requested, otherwise Location is served for user lists. vehicles: type: array items: type: string format: uri example: https://api.ev.energy/v2/vehicles/vhcl01HRFF3SEVSCRAV9B3CHVDFN0H readOnly: true readOnly: true evses: type: array items: type: string format: uri example: https://api.ev.energy/v2/evses/evse01HSH04XHZCT92RN018F0236ZM readOnly: true readOnly: true PayoutMethod: title: PayoutMethod description: "The user's preferred payout method. All three fields are nullable when\nno payout method has been set up. `receiver_type` and the format of\n`receiver` are determined by `receiver_wallet`:\n\n- `PAYPAL` → `receiver` is an email, `receiver_type` is `EMAIL`\n- `VENMO` → `receiver` is a phone number, `receiver_type` is `PHONE`\n- `BILL_CREDITS` → `receiver` is the user's billing account number\n (may be empty), `receiver_type` is `ACCOUNT_NUMBER`\n" type: object x-tags: - Users required: - url - receiver - receiver_type - receiver_wallet properties: url: type: string format: uri readOnly: true example: https://api.ev.energy/v2/users/user01HN2NJ9NMRZBXT1H6FT9N7735/payout_method receiver: type: - string - 'null' description: 'The destination identifier for the payout (email for `PAYPAL`, phone for `VENMO`, billing account number for `BILL_CREDITS`). Null when no payout method has been set up. ' example: alice@example.com receiver_type: type: - string - 'null' enum: - EMAIL - PHONE - ACCOUNT_NUMBER - null description: The semantic type of the `receiver` field. Server-derived. readOnly: true receiver_wallet: type: - string - 'null' enum: - PAYPAL - VENMO - BILL_CREDITS - null description: Which payout wallet the user has selected. Null when none is set. LatLong: title: LatLong type: object description: Coordinates model used for locations. required: - latitude - longitude properties: latitude: type: number format: float example: 51.52576576674041 longitude: type: number format: float example: -0.08366433371722264 RoutePoint: title: RoutePoint type: object description: A single geographic point on a saved route. required: - latitude - longitude - name properties: latitude: type: number format: float minimum: -90 maximum: 90 longitude: type: number format: float minimum: -180 maximum: 180 name: type: string maxLength: 100 examples: ProblemInvalidPaginationParameter: value: type: https://api.ev.energy/v2/problems/pagination-parameters/ status: 400 title: Invalid pagination parameter detail: 'Invalid value for pagination parameter: page_size' ProblemUnsupportedVersion: value: type: https://api.ev.energy/v2/problems/pagination-parameters/ status: 400 title: Unsupported version detail: 'Unsupported version requested: 3.0' headers: link: description: Provides links to the previous and next pages of data, if they exist. example: ; rel="previous", ; rel="next" schema: type: string x-ratelimit-remaining: description: The number of requests remaining until this client's rate limit is reached. schema: type: number default: 999 version-2: description: 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. schema: type: number enum: - 2 retry-after: description: The number of seconds until this client's requests will not be rate limited. schema: type: number default: 3600 x-ratelimit-limit: description: The maximum number of requests that can be made to this endpoint per hour. Defaults to 1000 but may vary per client. schema: type: number default: 1000 securitySchemes: oauth2: type: oauth2 flows: clientCredentials: tokenUrl: https://api.ev.energy/o/token/ refreshUrl: https://api.ev.energy/o/token/ scopes: carbon:read: '' grid:read: '' evse:read: '' evse:write: '' vehicle:read: '' user:read: '' charging_session:read: '' tariff:read: '' tariff:prices:read: '' user:write: '' inverter:read: '' inverter:write: '' home_battery:read: '' home_energy:read: '' boundary_meter:read: '' vehicle:write: '' vehicle_catalogue:write: Update shared vehicle-catalogue reference data (e.g. a model's default connector type) charging_session:write: '' solar:write: '' solar:read: '' subscription:read: '' debug:read: '' dispatch_coordinator:read: '' dispatch_event:write: '' solar_forecast:read: '' payout_method:read: Read a user's preferred payout method payout_method:write: Set, update, or clear a user's preferred payout method notification_preferences:read: Read a user's notification group opt-in state notification_preferences:write: Update a user's notification group opt-in state route_planner_preferences:read: Read a user's EV Route Planner preferences route_planner_preferences:write: Update a user's EV Route Planner preferences saved_routes:read: Read a user's saved route-planner routes saved_routes:write: Create, update, or delete a user's saved routes region:read: Read region and region group boundary data region:write: Create regions and region groups authorizationCode: authorizationUrl: https://api.ev.energy/o/authorize/ tokenUrl: https://api.ev.energy/o/token/ refreshUrl: https://api.ev.energy/o/token/ scopes: {} x-redocly: openapi: hideSchemaTitles: true x-internal: false