> ## Documentation Index
> Fetch the complete documentation index at: https://docs.der-connect.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect to an electric vehicle

> Get access to vehicle readings, control charging, and list charge sessions.

## What you'll need

* A valid access (bearer) token
* The vehicle's identification number (VIN) and its brand
* A way to reach out to the vehicle's owner for consent

### Locating the VIN

<Frame>
  <img alt="Illustration detailing how to find the VIN" noZoom src="https://mintcdn.com/realto/EG-Ok6q3nUjGJxIo/images/locate-vin.png?fit=max&auto=format&n=EG-Ok6q3nUjGJxIo&q=85&s=5f4f19219cb20dfafdda3632212f28e7" width="1740" height="1005" data-path="images/locate-vin.png" />
</Frame>

## Let's get started

<Steps>
  <Step title="Start the onboarding process">
    Create an [Entity Onboarding Request](/api-reference/endpoint/onboarding-api/onboard-entities/create-an-entity-onboarding-request), setting the <Tooltip tip="Specify the type of device or vehicle that you want to connect with.">type</Tooltip> to `EV`.\
    You'll need to specify a supported <Tooltip tip="Specify the brand (for example: “Audi” or “Tesla”) of the device or vehicle you want to connect with.">brand</Tooltip> and the VIN as a unique device <Tooltip tip="A unique identifier asigned by the vehicle or device manufacturer.">identifier</Tooltip>.

    <ParamField body="type" type="enum<string>" required />

    <ParamField body="brand" type="string" required>
      [List all available brands Entity types](/api-reference/endpoint/onboarding-api/onboard-entities/retrieve-available-entity-brands-and-types) to learn about the available options.
    </ParamField>

    <ParamField body="identifier" type="string" required>
      EVs are identified by their VIN (Vehicle Identification Number).
    </ParamField>
  </Step>

  <Step title="Check for required actions">
    In most cases, the onboarding request will have the <Tooltip tip="Available options: Canceled, Failed, InProgress, Pending, and Succeeded">status</Tooltip> `Pending` until a required <Tooltip tip="Represents a required action before the request can be completed.">action</Tooltip> is completed.

    How an action should be completed, depends on its <Tooltip tip="Available options: Consent and Redirect">type</Tooltip>.

    * Actions of type `Redirect` (most common) contain a <Tooltip tip="A URL where the user can complete the onboarding action.">redirectLink</Tooltip>. You can redirect your user here or share this link directly with the vehicle's owner to complete the action.
    * Actions of type `Consent` have to be completed through the vehicle manufacturer's app or by responding to a notification. They also contain a <Tooltip tip="Link to instructions for completing the action manually.">documentationLink</Tooltip> for more information on how to complete the action.

    ```json Response (Body) [expandable] {3, 5-8} theme={null}
    {
        "id": "3c90c3cc-[....]-8dd25736052a",
        "status": "Pending",
        "requestType": "Entity",
        "action": {
            "type": "Redirect",
            "redirectLink": "<string>"
        },
        "data": {
            ...
        }, ...
    }
    ```

    <ResponseField name="action" type="object">
      <Expandable title="properties">
        <ResponseField name="type" type="enum<string>">
          Available options: `Consent`, `Redirect`
        </ResponseField>

        <ResponseField name="redirectLink" type="string">
          A link to redirect the user to complete the action.
        </ResponseField>

        <ResponseField name="documentationLink" type="string">
          A link to our documentation, explaining the user how to proceed.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Step>

  <Step title="Track the onboarding status">
    Periodically poll the Onboarding API to check if the status of your request has updated to `Succeeded`. Once it's complete, you'll find the newly created Entity and its ID in the <Tooltip tip="An object containing the newly created Entity.">data</Tooltip> object.

    You can reference the <Tooltip tip="The ID of the Entity">entityId</Tooltip> when using our Readings API, Commands API, and our Charge Sessions API.

    ```json {3, 6} theme={null}
    {
       "id": "3c90c3cc-[....]-8dd25736052a",
       "status": "Succeeded",
       "data": {
           "entity": {
               "id": "3c90c3cc-[...]-8dd25736052a",
               ...
           },
       }, ...
    }
    ```
  </Step>
</Steps>

## Work with your newly created Entity

**Tip:** Take note of your Entity ID before you get started with our APIs.

<CardGroup cols={2}>
  <Card title="Readings API" icon="gauge" href="/guides/readings">
    Observe the state of the vehicle.
  </Card>

  <Card title="Commands API" icon="square-terminal" href="/guides/commands">
    Send charging instructions.
  </Card>

  <Card title="Charge Sessions API" icon="battery-bolt" href="/guides/charge-sessions">
    See when the vehicle charged.
  </Card>
</CardGroup>

<RequestExample>
  ```json Onboarding Request (Body)  {4} theme={null}
  {
      "type": "EV",
      "brand": "Tesla",
      "identifier": "1ABC36600TL029015",
  }
  ```
</RequestExample>