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	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 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 instead. See Vehicle Settings to compare the two options.

1. Create the interaction

   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.

   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	The vehicle has fewer than two available capacities, so the owner has nothing to choose. Read the capacity from the signal instead.