# Initiate vehicle onboarding

Initiate the onboarding process for a new vehicle in your user's browser (or an embedded web view in an app).
If none of `make_id`, `model_id` or `trim_id` are passed as query parameters, the user will be shown a user interface to pick their vehicle make.
## Native clients (`response_type=json`)
Native mobile clients that need to launch a provider SDK (e.g. Smartcar Connect for BMW/MINI) instead of opening a WebView can pass `response_type=json` to receive a JSON payload instead of a 302 redirect. In that case at least one of `make_id`, `model_id` or `trim_id` is required (otherwise the endpoint responds with `400`).
## Final redirect
After the user completes the web flow, the browser is redirected to the `redirect_uri` query parameter (when supplied and valid) or otherwise the `onboarding_redirect_url` configured on your application. The redirect URL will carry one or more query parameters identifying the onboarded vehicles:
- `vehicle_uid` — the v2 UID of each onboarded vehicle (preferred). Use this to call `GET /v2/vehicles/{vehicle_uid}` for further details.
- `vehicle_id` — the legacy integer primary key of each onboarded vehicle. Prefer `vehicle_uid`.

When multiple vehicles are onboarded in a single flow, both query parameters appear once per vehicle in matching order. For example: `https://your-redirect/?vehicle_id=1&vehicle_id=2&vehicle_uid=vhcl01...&vehicle_uid=vhcl02...`.

Endpoint: GET /vehicle_onboarding
Version: 2.0
Security: oauth2

## Query parameters:

  - `user_id` (string, required)
    The ID of a user to onboard a device for.

  - `make_id` (string)
    Specify the make of vehicle to be onboarded.

  - `model_id` (string)
    Specify the model of vehicle to be onboarded.

  - `trim_id` (string)
    Specify the trim of vehicle to be onboarded.

  - `client_id` (string, required)
    Your OAuth2 application client_id, issued when your ev.energy API integration was provisioned. This is the same value used when obtaining tokens via the Authorization Code or Client Credentials flows — not a user-created value. Passing an unrecognised string will result in an error. The onboarding endpoints redirect the user's browser through an OAuth flow to connect their device; the client_id determines which registered application is initiating the flow, so the correct branding, redirect URIs, and scopes are applied.

  - `response_type` (string)
    When set to `json`, the endpoint returns a JSON payload (200) instead of a 302 redirect. Used by native mobile clients to choose between launching a provider SDK and opening a WebView. Requires at least one of `make_id`, `model_id` or `trim_id`.

  - `redirect_uri` (string)
    Optional URL to return the user to after onboarding completes. Its scheme and host must match one of the application's registered `redirect_uris` or its `onboarding_redirect_url`, otherwise the endpoint responds with `400`. When omitted, the application's static `onboarding_redirect_url` is used.

## Response 200 fields (application/json):

  - `authorization_request_id` (string, required)
    UUID identifying the in-flight onboarding request. Echo it back to `POST /vehicle_onboarding/complete` (as `authorization_request_uid`) to finish onboarding.

  - `url` (string, required)
    The integration provider's authorization URL the client should navigate to (or pass to the native SDK).
    Example: https://connect.smartcar.com/oauth/authorize?response_type=code&client_id=...

  - `auth_method` (string, required)
    Whether the client should open `url` in a WebView (`api`) or launch the provider's native SDK with the supplied scopes (`native`). `native` is currently used for Smartcar BMW/MINI when the `smartcar_native_sdk` waffle flag is enabled.
    Enum: "api", "native"

  - `scopes` (array | null)
    OAuth scopes that the SDK should request when `auth_method=native`. Null when the field does not apply (for example for `auth_method=api` providers that do not surface scopes here).
    Example: ["read_vehicle_info","read_charge","control_charge"]

  - `single_select` (boolean | null)
    Whether the SDK should restrict the user to picking a single vehicle. Null when the field does not apply.

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

  - `status` (number)
    Example: 404

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

  - `detail` (string, required)
    Example: Resource does not exist or cannot be accessed.

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