# 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

## Description:

  - `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...`.

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

  - `200` (unknown)
    Returned only when `response_type=json` is supplied. Carries the integration provider's authorization URL plus the metadata native clients need (auth method, OAuth scopes, single-select hint) so they can either open the URL in a WebView or launch the provider's native SDK.

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

  - `302` (unknown)
    Have the user's browser follow the redirect to be prompted to connect their vehicle to the ev.energy system.

If a make, model or trim were not provided, the user will first be redirect to a screen to select these.

## Response 302 headers:

  - `Location` (string)
    The URL that the users browser will be redirected to in order to integrate their Vehicle.

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

  - `404` (unknown)
    This resource either does not exist or the client is not authorized to access it.

## 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 404 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 422:

  - `422` (unknown)
    Returned only on the `response_type=json` path when the integration provider could not produce an authorization URL — for example because the vehicle make is not supported, the provider is currently unavailable, or it returned an error code.

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

## Response 400 examples:

  - `Unsupported Version` (unknown)