Vehicle Simulator

Before launching your integration, we recommend using Smartcar’s Vehicle Simulator to test your application on a simulated vehicle. With the Simulator, you can choose the vehicle’s powertrain type and then configure its state to simulate any real-world situation you would like to test. Subscribe the vehicle to a webhook integration to rapidly test realistic vehicle state change events in your application.

​

1. Create a simulated vehicle

​

Choose a powertrain type

Select from BEV, ICE, HEV, or PHEV. The available vehicle data signals you can configure will vary based on the powertrain type you choose.

​

Give it a name

The name you provide will also be reflected in the vehicle’s state within the VehicleIdentification.Nickname signal.

​

Optional: create without connection

Optionally create the simulated vehicle in a disconnected state. Learn more about simulated vehicle connections.

​

Your simulated vehicle is now connected

Once created, the vehicle is fully connected to your Smartcar application. You can immediately begin making API requests and commands to the vehicle, or continue on to subscribing the vehicle to an integration. See Accessing a simulated vehicle for how to authenticate your requests.

• All compatible permissions are granted by default
• You can edit granted permissions later in the vehicle configuration
• Simulated vehicles will appear in your connections and logs with Simulated as the make and the chosen powertrain type as the model, eg: 2023 Simulated BEV.

​

Accessing a simulated vehicle

Simulated vehicles are accessed through the Smartcar API exactly like live vehicles.

• Application-level (M2M) tokens (recommended): Query and send commands to your simulated vehicles using your application’s access tokens, the same way you access live vehicles. See API Authentication Setup to get started.
• Per-vehicle (opaque) tokens: If your integration uses the OAuth 2.0 authorization code flow, connect the simulated vehicle with response_type=code and a configured redirect URI to receive an authorization code you can exchange for a per-vehicle access token. See How to Get an API Access Token.

​

2. Subscribe the vehicle to a webhook

​

Choose a webhook

Subscribe the simulated vehicle to one of your existing webhook integrations. If you don’t have a webhook integration yet, create your first integration.

​

Receive the first delivery

After subscribing the vehicle to a verified and enabled webhook integration, you will receive your first payload within a few minutes.

​

3. Configure the vehicle state

You control the current state of each vehicle data signal. Simulated vehicle state changes are entirely user-driven. All powertrain-type compatible signals are enabled for configuration by default.

​

Vehicle signals

Control the state of each vehicle data signal in the simulated vehicle’s configuration tab. You can edit one or many signals at a time. Click Publish to store the vehicle’s updated state. This state will be used in subsequent webhook payloads or API requests. If the published changes include a signal that is set as a trigger in your webhook integration, a new vehicle state or error event will be delivered to your application.

​

Vehicle commands

Simulated vehicles support the following API commands:

• Set charge limit
• Start and stop charge
• Lock and unlock
• Send destination

You can control access to these commands by editing the vehicle’s permissions. If you are testing commands while monitoring the vehicle’s state in the Simulator dashboard, click Refresh to view the vehicle’s updated state after the command request.

​

Permissions

Simulated vehicles are granted all compatible permissions by default based on the chosen powertrain type. You can edit granted permissions under the VehicleUserAccount.Permissions signal in the Vehicle State panel. To test permission errors in your webhooks, uncheck certain permissions while still requesting those signals in your webhook vehicle state payload. Learn more about permissions.

​

4. Test you webhook integrations

Test your webhook integrations by configuring and publishing the vehicle state in different scenarios. Each set of published changes that includes a webhook trigger signal will deliver a webhook payload to your integration.

​

5. Test error states

You can configure your simulated vehicle’s state to recreate error scenarios for testing. Examples:

• Uncheck a permission in VehicleUserAccount.Permissions before triggering a webhook payload to receive a PERMISSIONS error
• Set the simulated vehicle’s Transmission.GearState to DRIVE before making a POST /security lock request to receive a VEHICLE_STATE:IN_MOTION error

​

6. Test simulated vehicle connections

Use the Simulator to test vehicle connection and disconnection scenarios. By default, simulated vehicles are fully connected to your application upon creation. However, you can opt to create a simulated vehicle in a disconnected state and connect it later.

​

Connect a simulated vehicle

When connecting a simulated vehicle, you have two options depending on your testing needs; connecting automatically or simulating the vehicle owner experience using Smartcar Connect. Option 1: Connect automatically Instantly connect the simulated vehicle to your application. Once connected, access it with your application-level (M2M) tokens — see Accessing a simulated vehicle. Option 2: Connect via Smartcar Connect simulation Test the vehicle owner’s connection flow by simulating the Smartcar Connect authorization process. You’ll receive a Connect URL with the mode parameter set to “simulated” and authentication credentials to use in the Connect flow. This simulated flow uses response_type=none, so it does not issue a per-vehicle access token; access the connected vehicle with your application-level (M2M) tokens. If you specifically need per-vehicle tokens, use response_type=code with a configured redirect URI. After connecting through Smartcar Connect, the vehicle will display the selected brand in the dashboard and in all webhook payloads and API responses (in the vehicle.make field).

​

Disconnect a simulated vehicle

You can disconnect a simulated vehicle from any of these locations:

1. In the Vehicle Connections table
2. In the Simulated Vehicles table
3. Via the delete vehicle connection endpoint

Disconnecting removes the vehicle connection but preserves the simulated vehicle. Any active webhook subscriptions will be removed and must be reconfigured if you reconnect the vehicle.

​

Managing simulated vehicle connections

Manage simulated vehicle connections in the Vehicle Connections dashboard alongside live vehicles. Filter the table by mode to show simulated vehicles only. Vehicles from the legacy Simulator are marked with a ‘Legacy’ chip.

​

Test additional Connect flows

Depending on your use case, some vehicles prompt the user for additional input during the Smartcar Connect authorization flow. Use the Simulator to test these scenarios.

​

Test the VIN and odometer verification flow

In parts of Europe, some Volkswagen Group vehicle owners authenticate using their VIN and current odometer reading as an alternate to signing in with their connected services account.

1. Create a BEV or PHEV simulated vehicle and disable Connect automatically (or disconnect the vehicle once it’s been created).
2. Open the Connect modal for the vehicle and select Connect manually via Smartcar Connect.
3. Launch the Connect flow.
4. In the Connect flow, select a European country.
5. On the brand select screen, select one of the following brands: Audi, Cupra, Škoda, SEAT, or Volkswagen.
6. Enter the VIN and odometer reading from the simulated vehicle’s Configuration screen in the dashboard.

7. Finish connecting the vehicle.

Learn more about the VIN and odometer verification flow in Smartcar Connect →

​

Test the user-selected battery capacity flow

Some EVs report an undetermined battery capacity, prompting the vehicle owner to select their capacity during Connect.

1. Create a BEV simulated vehicle and disable Connect automatically (or disconnect the vehicle once it’s been created).
2. In the simulated vehicle’s Configuration screen, open the TractionBattery.NominalCapacity signal’s edit modal.
3. Toggle on the prompt for battery capacity selection in Connect.

4. Click Done, then publish the simulated vehicle’s modified signal configuration.
5. Double check the vehicle is in a disconnected state, then launch the Connect flow.
6. Complete the battery capacity selection flow, which is presented after the permissions grant screen in Connect.

Learn more about the battery capacity selection flow in Smartcar Connect →