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

# Interactions Overview

> Create URLs that send a vehicle owner through a Smartcar-hosted flow, such as selecting their vehicle's battery capacity.

An interaction is a URL that sends a person, usually the vehicle owner, through a flow hosted by Smartcar. Use interactions when your application needs the vehicle owner to make a choice that only they can make.

Your application creates the interaction server-side, then delivers the URL to the owner however you like: in your app, by email, or by push notification.

## Available Interactions

| Interaction | Endpoint | Result |
| - | - | - |
| `select-battery-capacity` | [`POST /interactions/select-battery-capacity`](https://smartcar.com/docs/api-reference/create-a-select-battery-capacity-interaction) | The owner selects the vehicle's nominal battery capacity. |

## Select Battery Capacity

For some vehicles, Smartcar can't determine the nominal battery capacity on its own. The [`TractionBattery.NominalCapacity`](https://smartcar.com/docs/api-reference/signals/tractionbattery#nominalcapacity) signal then lists several options in `availableCapacities`. This interaction lets the vehicle owner choose one.

If your application already knows the capacity, set it directly with [Set nominal battery capacity](https://smartcar.com/docs/api-reference/set-nominal-battery-capacity.md) instead. See [Vehicle Settings](https://smartcar.com/docs/api-reference/settings/overview.md) to compare the two options.

**1. Create the interaction**

```bash theme={null}
curl https://vehicle.api.smartcar.com/v3/interactions/select-battery-capacity \
  -X POST \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "data": { "attributes": { "vehicleId": "{vehicleId}", "userId": "{userId}", "redirectUri": "https://example.com/callback" } } }'
```

`userId` identifies the user the vehicle is connected through. See [User ID](#user-id).

`redirectUri` is optional. If you send it, it must exactly match a redirect URI registered for your application in the Smartcar Dashboard. If you leave it out, Smartcar uses your application's default redirect URI.

**2. Send the URL to the vehicle owner**

The response includes `url` and `expiresAt`. Deliver the URL to the vehicle owner before it expires.

**3. Read the selected capacity**

After the owner selects a capacity, the signal returns it with `source` set to `USER_SELECTED`.

### URL lifetime

While the URL is valid, the owner can select a capacity without logging in to their connected services account again. The URL stays valid for up to 30 days, until `expiresAt`. It stops being valid earlier when:

* The owner completes a selection.
* Your application creates a newer URL for the same vehicle.

After that, the URL still opens the flow, but the owner has to log in first.

The flow always shows the available capacities, even if the vehicle already has a capacity. The owner's selection replaces any existing value.

## Key Concepts

### User ID

Interaction endpoints take the user in the request body as `userId`. It identifies the user whose connection to the vehicle your application acts through. Smartcar returns `404` if the vehicle isn't connected to your application through that user.

`userId` is required with an application token. With a vehicle user token, Smartcar uses the token's user and ignores `userId`.

### Errors

| Status | `code` | When |
| - | - | - |
| 400 | `INVALID_INPUT_FORMAT` | A value has the wrong format, or the request includes an unknown attribute. |
| 400 | `MISSING_PARAMETER` | `vehicleId` or `userId` is missing. |
| 400 | `INVALID_REDIRECT_URI` | `redirectUri` isn't registered for your application. |
| 404 | `NOT_FOUND` | The vehicle isn't connected to your application through this user. |
| 422 | [`INTERACTION_NOT_APPLICABLE`](https://smartcar.com/docs/errors/api-errors/v3/validation-errors#interaction-not-applicable) | The vehicle has fewer than two available capacities, so the owner has nothing to choose. Read the capacity from the signal instead. |