# Onboarding vehicles, EVSEs and inverters

This article explains how to connect your users to their hardware. You will first need to create a user, which is described [here](/docs/howto/onboarding_users).

The following uses Vehicle onboarding as an example. EVSE and Inverters work the same way, except they don't have trims so the process is simpler.

## Custom onboarding selector

### Requirements

To begin you will need:

- A valid Authorization token (see [this page](/docs/auth) for instructions)
- An onboarding redirect URL configured on your account. If you're not sure if this is done, contact [developers@ev.energy](mailto:developers@ev.energy).
- An ID for a user in the system which you have access to, see [here](/docs/howto/onboarding_users).


### User header

In order for the API to automatically construct onboarding urls for the correct user, you must tell it which user you are onboarding. For each of the following requests, ensure you have set the `EvEnergy-User` header to the user ID of the correct user:


```
EvEnergy-User: user01J4459WYAFXJH187M7XJ5FY6A
```

### Select a make

Request the list of vehicle makes from `/vehicle_makes`. Show each of these to your user and have them select the right one. You can use the `icon` field to include a logo image to aid selection.

The individual resource for the make will look something like this:


```json
{
    "id": "vmak01HN2P75GBNFRJPCZJXEFVXH5E",
    "url": "https://api.ev.energy/v2/vehicle_makes/vmak01HN2P75GBNFRJPCZJXEFVXH5E",
    "name": "Volvo",
    "icon": "https://cdn.example.com/volvo.png",
    "onboarding_url": "https://api.ev.energy/v2/vehicle_onboarding?make_id=vmak01HN2P75GBNFRJPCZJXEFVXH5E&user_id=user01J4459WYAFXJH187M7XJ5FY6A",
    "models": "https://api.ev.energy/vehicle_models?make_id=vmak01HN2P75GBNFRJPCZJXEFVXH5E"
}
```

If `onboarding_url` is not `null`, then great, you've got all the information you need to initiate onboarding. Take the URL and jump to the "Initate Onboarding" section below!

If `onboarding_url` is `null`, then for that make of vehicle we need more information before we can continue. Take the url from the `models` field and go to the next step:

### Select a model

You now need to repeat the process above but for models instead of makes. The previous step will have provided you with a `models` url, which is a link to the `/vehicle_models` collection filtered to only return models for the make selected by the user.


```json
{
    "id": "vmod01HN2P436099PEQ20B7TKPGTEJ",
    "url": "https://api.ev.energy/vehicle_models/vmod01HN2P436099PEQ20B7TKPGTEJ",
    "name": "C40",
    "make": "https://api.ev.energy/v2/vehicle_makes/vmak01HN2P75GBNFRJPCZJXEFVXH5E",
    "onboarding_url": "https://api.ev.energy/v2/vehicle_onboarding?model_id=vmod01HN2P436099PEQ20B7TKPGTEJ&user_id=user01J4459WYAFXJH187M7XJ5FY6A",
    "trims": "https://api.ev.energy/vehicle_trims?model_id=vmod01HN2P436099PEQ20B7TKPGTEJ"
}
```

Request that URL and show the resulting list to your user. Once they select a model, check the `onboarding_url` field. If it is a url jump to the "Initate Onboarding" section below. If it is `null`, then we still don't have enough information. Grab the url from the `trims` field and continue.

### Select a trim

Repeat the process one last time. The link from the previous step's `trims` field is the url for the `/vehicle_trims` collection, filtered to just trims for the selected model.


```json
{
  "id": "trim01HN2NZ1040Y8E77CQGXADC2TZ",
  "url": "https://api.ev.energy/v2/vehicle_trim/trim01HN2NV5DY9C262PQKG75GHN8K",
  "name": "Recharge Core (69 kWh)",
  "model": "http://example.com",
  "onboarding_url": "https://api.ev.energy/v2/vehicle_onboarding?trim_id=trim01HN2NZ1040Y8E77CQGXADC2TZ&user_id=user01J4459WYAFXJH187M7XJ5FY6A"
}
```

Request that URL and show the resulting list to your user. Once they select their trim, check the `onboarding_url` field. If it is a url jump to the "Initate Onboarding" section below.

If it is `null`, then we are currently unable to integrate with that vehicle. Instead, we must create an "Unintegrated vehicle" in the system. This can be done by POSTing the trim and user IDs to the `/vehicles` endpoint.

### Initiate Onboarding

Send your user to the URL you got from the previous step. This could be in a web browser (which is also the easiest way for you to try it out yourself) or in an embedded web view in a mobile app. It should not be in an iframe embedded in a web page, as some of our third party providers do not function correctly within an iframe.

### Connect a vehicle

The user will be prompted to pick their vehicle manufacturer. Based on their choice and their location, we will then redirect them to the appropriate log-in service for their vehicle. They will need to enter their credentials and grant access to their account. The exact steps here vary quite a lot between manufacturers but we will guide the user through the process.

### Finishing up

Once the user's vehicle is set up in our system, we will redirect their browser (or webview) back to your onboarding redirect url. If your url was "[https://example.com/redirect](https://example.com/redirect)", we would send them to:


```
https://example.com/redirect?vehicle_id=vhcl01HN2NV5DY9C262PQKG75GHN8K
```

Your client can extract the `vehicle_id` query parameter from the URL in order to get the ID of the new Vehicle that has been updated.

## Summary

The behaviour described above can be visualised as a flowchart like this:


```mermaid
graph TD
  make[Select make] --> check1{onboarding_url is null?}
  check1 -- Yes --> model[Select model]
  check1 -- No --> onboard[Initiate onboarding]
  model --> check2{onboarding_url is null?}
  check2 -- Yes --> trim[Select trim]
  check2 -- No --> onboard[Initiate onboarding]
  trim --> check3{onboarding_url is null?}
  check3 -- Yes --> unintegrated[Create unintegrated vehicle]
  check3 -- No --> onboard[Initiate onboarding]
  onboard --> stop[User has a vehicle]
  unintegrated --> stop
```