# Initiate EVSE onboarding

Initiate the onboarding process for a new EVSE in your user's browser (or an embedded web view in an app).
If neither `make_id` or `model_id` are passed as query parameters, the user will be shown a user interface to pick their EVSE make.
## Native clients (`response_type=json`)
Native mobile clients that need to open the onboarding URL in a WebView (rather than follow a 302 redirect) can pass `response_type=json` to receive a JSON payload instead. In that case at least one of `make_id` or `model_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 two query parameters identifying the onboarded EVSE:
- `evse_uid` — the v2 UID of the onboarded EVSE (preferred). Use this to call `GET /v2/evses/{evse_uid}` for further details.
- `evse_id` — the legacy integer primary key. Prefer `evse_uid`.

Example: `https://your-redirect/?evse_id=123&evse_uid=evse01...`.

Endpoint: GET /evse_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 EVSE to be onboarded.

  - `model_id` (string)
    Specify the model of EVSE 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 that prefer to open the onboarding URL in a WebView. Requires at least one of `make_id` or `model_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):

  - `url` (string, required)
    Absolute URL to the EVSE onboarding wrapper. Open it in a WebView (mobile) or redirect the browser to it (web). The wrapper view either redirects to the provider (when a model was supplied) or shows the make picker.
    Example: https://api.ev.energy/evse-onboarding/start/abc12345-def6-7890-1234-567890abcdef/

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