# 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...&authorization_request_id=abc12345-...`.
Every return to `redirect_uri` (success, failure, the driver abandoning the flow, or going back) also carries `authorization_request_id`, the UUID of the onboarding attempt. With `response_type=json` the same value is returned up front, so the client can match the return to the attempt it started.

Endpoint: GET /evse_onboarding
Version: 2.0
Security: oauth2

## Description:

  - `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...&authorization_request_id=abc12345-...`. Every return to `redirect_uri` (success, failure, the driver abandoning the flow, or going back) also carries `authorization_request_id`, the UUID of the onboarding attempt. With `response_type=json` the same value is returned up front, so the client can match the return to the attempt it started.

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

  - `200` (unknown)
    Returned only when `response_type=json` is supplied. Carries an absolute URL to the EVSE onboarding wrapper that the client opens in a WebView (mobile) or redirects the browser to (web). The wrapper view either redirects to the provider (when a model was supplied) or shows the make picker.

## Response 200 fields (application/json):

  - `authorization_request_id` (string, required)
    UUID identifying this onboarding attempt. The same value is appended to the `redirect_uri` as `authorization_request_id` whenever the driver is sent back.
    Example: abc12345-def6-7890-1234-567890abcdef

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

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

If a make or model were not provided, the user will first be redirected 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 EVSE.

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

  - `Unsupported Version` (unknown)