smartcar

Getting Started

Connect Docs

API Reference

Help Center

Changelog

Request a Demo

Log in

Errors

API Errors

Learn about how to build applications that connect to millions of vehicles around the world.

Introduction

Introduction to Smartcar's API

Plan Your Integration

Test Your Integration

In this tutorial, we will use the iOS SDK to integrate Connect into your application.

iOS Tutorial

In this tutorial, we will use the Android SDK to integrate Connect into your application.

Android

Android Tutorial

In this tutorial, we will use the JavaScript SDK to integrate Connect into your application.

React

React Tutorial

In this tutorial, we will go over how  to integrate Connect into your application and make requests to a vehicle using our backend SDKs.

Backend SDKs

Backend SDK Tutorials

Scheduled webhooks make it incredibly easy to receive vehicle data on a cadence of your choosing. You can set up a webhook for any Smartcar endpoint that allows you to read data from a vehicle.

Scheduled

Scheduled Webhooks

A comprehensive breakout of all Smartcar errors.

Overview

This error occurs when a user denies your application access to the requested scope of permissions.

Access Denied

This error occurs when a user’s vehicle is compatible but their connected services subscription is inactive because either it has expired or it has never been activated.

Invalid Subscription

This error occurs when the user has encountered an Error page in Connect and has chosen to return to your application.

Configuration

This error occurs when a vehicle owner has a connected services account, but there are no vehicles associated with the account.

No Vehicles

If there is a server error, the user will return to your application.

Server

This error occurs when a user tries to authorize an incompatible vehicle in Smartcar Connect.

Vehicle Incompatible

This error occurs when a user went to authorize directly with the OEM but exited the flow for some reason.

OEM Login Cancelled

Thrown when there is an issue with your authorization header.

Authentication

Authentication Errors

Thrown when limits have been reached based on your plan, or if the feature is not avaible.

Billing

Billing Errors

Compatibility

Compatibility Errors

Thrown when there are issues with the user's connected service account.

Connected Services Account

Connected Services Account Errors

Thrown when Smartcar does not support a make or feature for a vehicle.

Permission

Permission Errors

Thrown when there is an issue with the frequency of your requests.

Rate Limit

Rate Limit Errors

Thrown when the incorrect API version is used or when the endpoint URL is incorrect.

Resource Not Found

Thrown when Smartcar runs into an unexpected issue and was unable to process the request.

Server Errors

Thrown when the OEM servers or vehicle failed to process the request.

Upstream

Upstream Errors

Thrown if there is an issue with the format of the request or body.

Validation

Validation Errors

Thrown when a request fails due to the state of a vehicle or logically cannot be completed e.g. you can't start a vehicle charging if it's not plugged in.

Vehicle State

Vehicle State Errors

By launching Connect in [test mode](/docs/connect/advanced-config/modes), you're able to test your application against certain errors.

Testing Errors

All you need to know about the Smartcar Dashboard

Dashboard Overview

Dashboard Configurations

Simulator

Vehicle Simulator

What is Connect?

Our SDKs make integrating Smartcar fast and easy in different languages and frameworks.

SDKs

SDKs for Connect

Dashboard Configuration

Build the Connect URL

Upon successfully accepting the permissions, Smartcar will redirect the user back to your application using the specified `REDIRECT_URI`, along with an authorization code as a query paramter. In the case of on error, we'll provide an error and description as parameters instead.

Handle the Response

Auth Code Exchange

After fetching your first token pair, you'll need to manage them in order to maintain access to the vehicle.

Your access token will expire **2 hours** after it is issued. When this happens, your application  can retrieve a new one by using the corresponding `REFRESH_TOKEN`.

Refreshing Access Tokens

Refresh tokens expire after **60 days ordinarily** or **after 1 minute when used to fetch a new token pair**.

Refreshing Refresh Tokens

Redirect to Connect

If the re-auth is successful, the redirect to your application will contain a vehicle ID. In the case of an error, we'll provide an error and description as parameters instead.

Connect can be launched with three different workflows. Depending on your use case and what information you have about the vehicle ahead of a launching Connect, you may be able to leverage one of these flows for a more streamlined Connect experience.

Connect Flows

Modes

By default Connect will launch based on the devices location impacting the brands that are available to the user e.g. Renault is only available in Europe.

Country Selection

Connect to new vehicles on connected services accounts without going through the Connect flow again.

Account Sync (Early Access)

Smartcar API Reference

Headers

To interact with the Smartcar API, you will need to exchange your authorization code from the [Connect redirect](/docs/connect/handle-the-response) for an access token.

Your access token will expire 2 hours after it is issued. When this happens, your application can retrieve a new one by using the `refresh_token` returned in the [auth code exchange](/docs/api-reference/authorization/auth-code-exchange) or prior token refresh.

Token Refresh

Makes

In order to use an endpoint or webhook, you'll need to request the associated permissions from your user in [Connect](/docs/connect/what-is-connect).

Permissions

By VIN

By Region and Make

Returns a paged list of all vehicles that are connected to the application associated with the management API token used, sorted in descending order by connection date.

Vehicle Connections

Deletes all vehicle connections associated with a Smartcar user ID or a specific vehicle.

Returns arrays of vehicle Ids that have been added to and removed from a connected services account

Account Sync (Beta)

Returns a paged list of all vehicles connected to the application for the current authorized `user`.

All Vehicles

Returns a list of responses from multiple Smartcar `GET` endpoints, all combined into a single request.

Batch

Returns the rated capacity of the electric vehicle's high voltage battery.

Battery Capacity

Returns the state of charge and the remaining range of an electric vehicle's high voltage battery.

Battery Level

Returns the charge limit configuration for the vehicle.

Charge Limit

Set the  charge limit of an electric vehicle.

Returns the charge status for the vehicle.

Charge Status

Control Charge

Returns the status of the fuel remaining in the vehicle’s fuel tank.

Fuel Tank

Returns the vehicle's last known location.

Location

Returns the lock status for a vehicle and the open status of its doors, windows, storage units, sunroof and charging port where available.

Lock Status

Lock and Unlock

Returns the vehicle’s last known odometer reading.

Odometer

Returns the remaining life span of a vehicle’s engine oil.

Oil Life

Returns a list of the permissions that have been granted to your application in relation to this vehicle.

Send destination coordinates to the vehicle's navigation system.

Send Destination

Returns the air pressure of each of the vehicle’s tires.

Tire Pressure

Returns the ID of the vehicle owner who granted access to your application.

User

Returns a single vehicle object, containing identifying information.

Vehicle Info

Returns the vehicle’s manufacturer identifier.

About Make Specific

Make Specific Endpoints

When the vehicle is plugged in, returns the charging voltage measured by the vehicle. When the vehicle is not plugged in, this endpoint results in a vehicle state error.

Voltage

When the vehicle is charging, returns the date and time the vehicle expects to "complete" this charging session.  When the vehicle is not charging, this endpoint results in a vehicle state error.

Charge Completion Time

Returns data associated with completed charging sessions for a vehicle. Limited to the last 30 days or when the owner first granted your application access, which ever is shorter.

Charge Records

Returns all saved charging locations for a vehicle and their associated charging limits, schedules and configurations.

Charge Schedule by Location

Set all schedules for the specified charging location.

Returns the charging schedule of a vehicle. The response contains the start time and departure time of the vehicle's charging schedule.

Charge Schedule

Sets the charging schedule for a vehicle.

Returns detailed configuration information for a vehicle.

Extended Vehicle Info

Vehicle Status

Returns all battery related data for a Tesla vehicle.

Battery

Tesla: Battery Status

Returns all charging related data for a Tesla vehicle.

Charge

Tesla: Charge Status

Set the amperage drawn by the vehicle from the EVSE for the current charging session. If the vehicle is not plugged in, this endpoint results in a vehicle state error.

Amperage

When the vehicle is charging, returns the date and time when the vehicle is expected to reach its charge limit. When the vehicle is not charging, this endpoint results in a vehicle state error.

Returns information about charging sessions for Tesla vehicles at public Tesla chargers including cost and charging site.

Charge Billing Records

When the vehicle is charging, returns the instant charging wattage as measured by the vehicle. When the vehicle is not charging, this endpoint results in a vehicle state error.

Wattage

Returns the vehicle’s last known exterior thermometer reading. See our [climate setting](/docs/api-reference/tesla/get-cabin) endpoints for managing a cabin temperature.

Exterior Temperature

Returns the vehicle’s last known interior thermometer reading. See our [climate setting](/docs/api-reference/tesla/get-cabin) endpoints for managing a cabin temperature.

Interior Temperature

Returns the current compass heading and direction of the vehicle.

Compass

Returns the current speed of the vehicle.

Speed

Returns the current state and target temperature setting of a vehicle's cabin climate system.

Cabin Climate

Set the temperature and control the cabin climate system for a vehicle.

Returns the current state of a vehicle's front and rear defroster.

Defroster

Start or stop the front and rear defroster for a vehicle.

Returns the current state of a vehicle's steering wheel heater system.

Name	Type	Description
type	string	A unique identifier that groups codes into broad categories of errors
code	string	A short, descriptive identifier for the error that occurred
description	string	A short description of the code that provides additional information about the error. The description is always provided in English.
docURL	string	A link to Smartcar’s doc center guide for the given type and code
statusCode	number	The HTTP status code
requestId	string	Smartcar’s request ID
resolution	object	An object with at least one enumerated property named as “type” that specifies which action can be taken to resolve this error. There are three possible values for the property “type”: `RETRY_LATER` - Retry the request at a later time; `REAUTHENTICATE` - Prompt the user to re-authenticate in Smartcar Connect; and `CONTACT_SUPPORT` - Contact Smartcar’s support team. This object could contain other properties depending on the “type” of error.
detail	array	An array of objects that provide further detail regarding the error. Only included with validation errors.

Code	Type	Status
`ACCOUNT_ISSUE`	`CONNECTED_SERVICES_ACCOUNT`	400
`AUTHENTICATION_FAILED`	`CONNECTED_SERVICES_ACCOUNT`	400
`NO_VEHICLES`	`CONNECTED_SERVICES_ACCOUNT`	400
`PERMISSION`	`CONNECTED_SERVICES_ACCOUNT`	400
`SUBSCRIPTION`	`CONNECTED_SERVICES_ACCOUNT`	400
`VEHICLE_MISSING`	`CONNECTED_SERVICES_ACCOUNT`	400
`VIRTUAL_KEY_REQUIRED`	`CONNECTED_SERVICES_ACCOUNT`	400
`null`	`VALIDATION`	400
`PARAMETER`	`VALIDATION`	400
`null`	`AUTHENTICATION`	401
`null`	`PERMISSION`	403
`PATH`	`RESOURCE_NOT_FOUND`	404
`VERSION`	`RESOURCE_NOT_FOUND`	404
`ASLEEP`	`VEHICLE_STATE`	409
`CHARGING_IN_PROGRESS`	`VEHICLE_STATE`	409
`CHARGE_FAULT`	`VEHICLE_STATE`	409
`NOT_CHARGING`	`VEHICLE_STATE`	409
`CHARGING_PLUG_NOT_CONNECTED`	`VEHICLE_STATE`	409
`CHARGING_PLUG_CONNECTED`	`VEHICLE_STATE`	409
`DOOR_OPEN`	`VEHICLE_STATE`	409
`FULLY_CHARGED`	`VEHICLE_STATE`	409
`HOOD_OPEN`	`VEHICLE_STATE`	409
`IGNITION_ON`	`VEHICLE_STATE`	409
`IN_MOTION`	`VEHICLE_STATE`	409
`LOW_BATTERY`	`VEHICLE_STATE`	409
`REMOTE_ACCESS_DISABLED`	`VEHICLE_STATE`	409
`TRUNK_OPEN`	`VEHICLE_STATE`	409
`UNKNOWN`	`VEHICLE_STATE`	409
`UNREACHABLE`	`VEHICLE_STATE`	409
`VEHICLE_OFFLINE_FOR_SERVICE`	`VEHICLE_STATE`	409
`VEHICLE`	`RATE_LIMIT`	429
`SMARTCAR_API`	`RATE_LIMIT`	429
`INVALID_PLAN`	`BILLING`	430
`VEHICLE_LIMIT`	`BILLING`	430
`VEHICLE_REQUEST_LIMIT`	`BILLING`	430
`INTERNAL`	`SERVER`	500
`MAKE_NOT_COMPATIBLE`	`COMPATIBILITY`	501
`SMARTCAR_NOT_CAPABLE`	`COMPATIBILITY`	501
`VEHICLE_NOT_CAPABLE`	`COMPATIBILITY`	501
`PLATFORM_NOT_CAPABLE`	`COMPATIBILITY`	501
`INVALID_DATA`	`UPSTREAM`	502
`KNOWN_ISSUE`	`UPSTREAM`	502
`NO_RESPONSE`	`UPSTREAM`	502
`RATE_LIMIT`	`UPSTREAM`	502
`UNKNOWN_ISSUE`	`UPSTREAM`	502

Introduction

Compatibility

Connection Management

Vehicle Endpoints

Make Specific

Webhooks

API Errors

Error Response

Error Codes

Introduction

Compatibility

Connection Management

Vehicle Endpoints

Make Specific

Webhooks

​Error Response

​Error Codes

Error Response

Error Codes