---
title: "Action Connect"
method: POST
path: "/v1/accounts:connect"
tags: ["Accounts"]
---

# Action Connect

`POST /v1/accounts:connect`

Generate a URL to initiate the account connection flow, which allows users to connect their accounts.
The generated URL is active for a **one-hour period**. If not authenticated within this timeframe, the link will become invalid.

After the connection flow is completed, the device owner is redirected to the provided return URL with the following parameters:
- `result` indicating success or failure.
- `accountId` representing the ID of the connected account.

For further customization and integration details, consider the following resources:
- See the [Scopes documentation](/overview/scopes) for information on how to utilize scopes in your integration.
- See the [Regions documentation](/overview/regions) for guidelines on setting geographic regions.

You can also connect a single vehicle using the VIN upload flow. Pass the VIN, and (if available) the model and model year.
This will generate a consent flow link that's dedicated to uploading a single vehicle.


Possible Codes in Error Response (see [Errors](https://docs.volteras.com/api-reference/errors) for error response schema and meaning of codes):

- AUTHENTICATION_ERROR
- DEVICE_LIMIT_REACHED
- NOT_PERMITTED
- REQUEST_VALIDATION_ERROR
- SERVER_ERROR
- UNSUPPORTED_OEM

## Request body

- AccountConnectPayload
  - `returnUrl` string, uri, nullable — The url the user is redirected to at the end of the consent flow
  - `scopes` ScopeEnum[], required — List of scopes that the application requires access to
  - `locale` 'en-GB' | 'de-DE' | 'fr-FR' | 'nl-NL'
  - `integrationMethod` 'BMW_ENERGY_API'
  - `chargerLocationLatitude` union — The latitude of the charger location that the vehicle will be charging at. This is passed in specific cases to the OEM's Portal when the consent flow runs (currently only for BMW), to make it easier for the user to select their charger location, which in turn is needed (currently only for BMW) to restrict when start / stop charge commands can be sent.
    - number
    - string
  - `chargerLocationLongitude` union — The longitude of the charger location that the vehicle will be charging at. This is passed in specific cases to the OEM's Portal when the consent flow runs (currently only for BMW), to make it easier for the user to select their charger location, which in turn is needed (currently only for BMW) to restrict when start / stop charge commands can be sent.
    - number
    - string
  - `countryCode` string, nullable — The ISO 3166-1 alpha-2 country code (e.g. DE, GB, US etc.) of the account's country. This is required when it is necessary to fetch the key specifications (model, model year, trim, battery capacity etc.) for vehicles in the account.
  - `makes` MakeEnum[], nullable — Only show these makes of device in the consent flow
  - `deviceTypes` DeviceTypeEnum[], required — Only show these device types in the consent flow. If only one device is selected, the device selection page is skipped.
  - `urlExpiration` integer, nullable — Defines the validity period of the authentication URL in seconds. Defaults to `3600`, with a range between `3600` seconds (1 hour) and `1209600` seconds (2 weeks). Once expired, the URL becomes invalid and cannot be used.
  - `region` 'NORTH_AMERICA' | 'EUROPE'
  - `vin` string, nullable — The VIN to connect, if connecting via the VIN upload flow.
  - `model` string, nullable — The model to connect, if connecting via the VIN upload flow.
  - `modelYear` integer, nullable — The model year to connect, if connecting via the VIN upload flow.

## Response `200`

Successful Response

- AccountConnect
  - `authenticationUrl` string, required — The URL to redirect the user to for authentication through the connect flow.

---

[API](https://skmtc.net/volteras/apis/volteras-connect.md) · [All operations](https://skmtc.net/volteras/apis/volteras-connect/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/volteras/volteras-connect/versions/bcb08bba814d/schema)