# Add user to the vehicle waitlist

Captures a user who hit an `incompatible` result on the vehicle compatibility check, so we can notify them once their hardware becomes supported. Pre-account endpoint — no OAuth token required.
Driver authentication is optional. Anonymous callers must supply `email`. When called with a driver access token (authorization-code or password grant), the entry is attached to the driver's account and `email` may be omitted to use the account email. Client-credentials (organisation) tokens and operator apps (such as the B2B app) are treated as anonymous, and the `EvEnergy-User` header is ignored.
The request body must identify the device in exactly one of three modes:
- **Picker mode**
 — supply
`vehicle_model_id`
 (uid of a
`CarModel`
).
`vehicle_make_id`
,
`vehicle_make_name`
 and
`vehicle_model_name`
 must be omitted / null.
- **Known make**
 — supply
`vehicle_make_id`
 (uid of a
`CarMake`
) and
`vehicle_model_name`
 as free text.
`vehicle_model_id`
 and
`vehicle_make_name`
 must be omitted / null; the stored make name is filled in from the make.
- **Manual entry**
 — supply both
`vehicle_make_name`
 and
`vehicle_model_name`
 as free-text strings.
`vehicle_model_id`
 and
`vehicle_make_id`
 must be omitted / null.

Any other combination — including all four identifier fields null — returns `400`.
Program and country are derived server-side: an explicit `program_id` wins (country from `program.country`); otherwise, for a driver, their open program enrolment (program and its country), then their profile country; otherwise the `Accept-Language` header (defaulting to `US`).
Error responses follow RFC 9457 Problem Details. Problem types emitted by this endpoint:
- `validation-failed-vehicle-waitlist`
 — request body fails validation (missing required field, mode constraint violation, unknown
`vehicle_model_id`
 /
`vehicle_make_id`
 /
`program_id`
, or
`vehicle_make_id`
 without
`vehicle_model_name`
 or combined with
`vehicle_model_id`
 /
`vehicle_make_name`
).

Endpoint: POST /vehicle_waitlist
Version: 2.0
Security: oauth2

## Security:

  - `oauth2` (unknown)
    oauth2

## Query parameters:

  - `client_id` (string)
    OAuth `Application.client_id`. Mirrors the pre-account onboarding and compatibility-check endpoints: when supplied and the application has sandbox mode enabled, the endpoint returns a canned `201` without persisting anything.

## Header parameters:

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

  - `Accept-Language` (string)
    Indicates the natural language and locale that the client prefers.

## Request fields (application/json):

  - `email` (string | null)
    Email address to notify when the user's hardware becomes supported. Required for anonymous callers, for whom `null` and an empty string are rejected; a driver calling with their own access token may omit it, or send `null` or an empty string, to use their account email.
    Example: user@example.com

  - `program_id` (string | null)
    Optional `ProgramConfig` uid. Captured where known (web signup, whitelabel microsite) so later notification logic can scope by program.
    Example: prog01HRS4TSK26BPBV7127DH7E0HA

  - `vehicle_model_id` (string | null)
    Uid of a `CarModel`. Used when the user picked from the vehicle picker. Mutually exclusive with `vehicle_make_id`, `vehicle_make_name` and `vehicle_model_name`.
    Example: vmod01HRS4TSK26BPBV7127DH7E0HA

  - `vehicle_make_id` (string | null)
    Uid of a `CarMake`. Used when the user picked a known make but typed a model name; must be supplied with `vehicle_model_name`. The stored make name is filled in from the make. Mutually exclusive with `vehicle_model_id` and `vehicle_make_name`.
    Example: vmak01HRS4TSK26BPBV7127DH7E0HA

  - `vehicle_make_name` (string)
    Free-text make name from manual entry. Must be supplied together with `vehicle_model_name`. Mutually exclusive with `vehicle_model_id` and `vehicle_make_id`.
    Example: Tesla

  - `vehicle_model_name` (string)
    Free-text model name. Must be supplied together with `vehicle_make_name` or `vehicle_make_id`. Mutually exclusive with `vehicle_model_id`.
    Example: Model 3

  - `notify_when_supported` (boolean)
    Whether the user opts in to an email once their hardware becomes supported. Defaults to `true`.

## Response 201:

  - `201` (unknown)
    Waitlist entry created. Body echoes the new entry's uid.

## Response 201 fields (application/json):

  - `id` (string, required)
    Uid of the created waitlist entry.
    Example: vwlt01HRS4TSK26BPBV7127DH7E0HA

## Response 201 headers (application/json):

  - `EvEnergy-Version` (number)
    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.
    Enum: "2"

  - `X-RateLimit-Limit` (number)
    The maximum number of requests that can be made to this endpoint per hour. Defaults to 1000 but may vary per client.

  - `X-RateLimit-Remaining` (number)
    The number of requests remaining until this client's rate limit is reached.

  - `RetryAfter` (number)
    The number of seconds until this client's requests will not be rate limited.

## Response 400:

  - `400` (unknown)
    A problem with the request's parameters prevented it being fulfilled.

## 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 400 headers (application/problem+json):

  - `EvEnergy-Version` (number)
    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.
    Enum: "2"

  - `X-RateLimit-Limit` (number)
    The maximum number of requests that can be made to this endpoint per hour. Defaults to 1000 but may vary per client.

  - `X-RateLimit-Remaining` (number)
    The number of requests remaining until this client's rate limit is reached.

## Response 405:

  - `405` (unknown)
    Could not satisfy this HTTP method.

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

  - `status` (number)
    Example: 405

  - `title` (string, required)
    Example: Method Not Allowed

  - `detail` (string, required)
    Example: Could not satisfy this HTTP method.

## Response 405 headers (application/problem+json):

  - `EvEnergy-Version` (number)
    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.
    Enum: "2"

  - `X-RateLimit-Limit` (number)
    The maximum number of requests that can be made to this endpoint per hour. Defaults to 1000 but may vary per client.

  - `X-RateLimit-Remaining` (number)
    The number of requests remaining until this client's rate limit is reached.

  - `RetryAfter` (number)
    The number of seconds until this client's requests will not be rate limited.

## Response 406:

  - `406` (unknown)
    Could not satisfy the request Accept header.

## 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 406 headers (application/problem+json):

  - `EvEnergy-Version` (number)
    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.
    Enum: "2"

  - `X-RateLimit-Limit` (number)
    The maximum number of requests that can be made to this endpoint per hour. Defaults to 1000 but may vary per client.

  - `X-RateLimit-Remaining` (number)
    The number of requests remaining until this client's rate limit is reached.

  - `RetryAfter` (number)
    The number of seconds until this client's requests will not be rate limited.

## Response 429:

  - `429` (unknown)
    The client has exceeded its rate limit.

## 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

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

  - `EvEnergy-Version` (number)
    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.
    Enum: "2"

  - `Retry-After` (number)
    The number of seconds until this client's requests will not be rate limited.

  - `X-RateLimit-Limit` (number)
    The maximum number of requests that can be made to this endpoint per hour. Defaults to 1000 but may vary per client.

  - `X-RateLimit-Remaining` (number)
    The number of requests remaining until this client's rate limit is reached.

## Response 400 examples:

  - `Unsupported Version` (unknown)

## Response 429 examples:

  - `Example 1` (unknown)