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.