Changelog
This changelog contains all major updates and feature additions to version 2.0 of Smartcar’s APIs.
v2.0 SDK methods
If you are using one of our SDKs, please add the following code block to specify that all requests should be made to v2.0 of the Smartcar API. Note: It’s best to invoke the method from a “central” part of your codebase, as the helper method only needs to be invoked once rather than before every API request.
const smartcar = require('smartcar');
smartcar.setApiVersion('2.0');
If you are not using any of our SDKs, simply replace /v1.0/
with /v2.0/
in the URLs that you construct.
March 16, 2023
The API now returns a new code for the RATE_LIMIT error type if your application tries to make a request to a vehicle too frequently. Click the following link to learn more:
March 14, 2023
Smartcar has revamped the Connect flow UI and backend to improve error handling and optimize user conversion rates. Our updates fall into 3 categories: improving brand selection, expanding login methods, and establishing new error codes specific to Connect. These include:
-
Allowing a user to search for:
a. Brand aliases in Brand Select such as VW for Volkswagen
b. Unavailable brands that we plan to introduce in the future, which will display a message highlighting future compatibility with the chosen brand.
- Expanding login method coverage to include phone numbers for certain brands. We now allow users to log in using email or phone number for the Connect flow starting with Kia and Mercedes-Benz. Stay tuned to our changelog for more brand updates.
-
Providing clearer errors for the Connect flow:
a.
no_vehicles
for when the user does not have any vehicles tied to their account and they click to go back to the applicationb.
configuration_error
for when exiting Connect back to your app through an error page (see below).c.
server_error
which is thrown if there is not another Connect error specified.
March 6, 2023
January 6, 2023
Smartcar API v1.0 has been sunset and is no longer supported. If you are currently using v1.0 for API requests, webhooks, errors, or compatibility, we recommend switching to v2.0 as soon as possible.
November 30, 2022
January 6, 2023
Smartcar API v1.0 has been sunset and is no longer supported. If you are currently using v1.0 for API requests, webhooks, errors, or compatibility, we recommend switching to v2.0 as soon as possible.
December 29, 2022
November 30, 2022
August 24, 2022
September 22, 2022
The following brand-specific endpoint is now available for Tesla vehicles in Canada, the United States, and our supported European countries:
August 3, 2022
July 20, 2022
July 6, 2022
The following brand-specific endpoints are now available for Tesla vehicles in Canada, the United States, and our supported European countries:
June 29, 2022
June 22, 2022
June 15, 2022
The API now returns a more detailed VEHICLE_STATE
error whenever a charge request fails due to charger issues or charging schedules. Click the following link to learn more:
June 8, 2022
May 9, 2022
May 5, 2022
The API now returns more detailed errors for the following:
- UPSTREAM:RATE_LIMIT - a request fails due to a vehicle rate limit.
- VEHICLE_STATE:NOT_CHARGING - a vehicle is not charging (only applies to endpoints that return details about a specific charging session e.g. Charging Completion Time).
April 13, 2022
CHARGING_STARTED
CHARGING_STOPPED
CHARGING_COMPLETED
Webhook events sent in response to vehicle events can be distinguished from schedule events based on the eventName
property of the POST body. For example, the POST body for event based webhooks will have the following structure:
{
"version": "2.0",
"webhookId": "uuid",
"eventName": "eventBased",
"mode": "test|live",
"payload": {
"eventId": "uuid",
"vehicleId": "uuid",
"eventType": "CHARGING_STARTED|CHARGING_STOPPED|CHARGING_COMPLETED",
"eventTime": "ISO8601 Datetime"
}
}
March 7, 2022
February 23, 2022
February 21, 2022
February 14, 2022
February 2, 2022
const amperage = vehicle.request('GET', 'tesla/charge/ammeter');
January 5, 2022
Initial Release
Compatibility
The Compatibility API now returns an endpoint-by-endpoint breakdown of the vehicle's capability.
The previous version of the Compatibility API returned a single field named compatible
, which encapsulated both the vehicle’s compatibility with Smartcar and the vehicle’s capability to carry out all of the permissions that were passed into the scope
parameter. This new version of the Compatibility API breaks this single field down into the following fields:
compatible
: Does the vehicle have the required hardware for internet connectivity and does it belong to the set of makes and models that Smartcar is compatible with?Note: The meaning of this field has changed compared to
v1.0
.capabilities
: A list of the endpoints that the permissions passed into thescope
parameter provide access to. Each entry has a field namedcapable
that indicates whether the vehicle capable of supporting that specific endpoint.
Example
GET https://api.smartcar.com/v2.0/compatibility?vin=PLACEHOLDER&scope=read_battery&country=us
{
"compatible": true,
"reason": null,
"capabilities": [
{
"permission": "read_battery",
"endpoint": "/battery",
"capable": true,
"reason": null
},
{
"permission": "read_battery",
"endpoint": "/battery/capacity",
"capable": false,
"reason": "VEHICLE_NOT_CAPABLE"
}
]
}
Migration Steps
The simplest migration path would entail replacing mentions of compatible
with a logical AND between compatible
and capabilities[].capable
. However, we recommend modifying your application logic to make use of the more detailed information that the new version of the Compatibility API offers.
We recommend using logic similar to the following:
- If
compatible
isfalse
, use thereason
field to let the user know that their vehicle is not compatible because it does not have the required hardware (reason = VEHICLE_NOT_CAPABLE
) or because their vehicle is not yet supported (reason = UNSUPPORTED_MAKE
). - Iterate through the list of
capabilities
to check whether the vehicle is capable of the endpoints that your application requires. While iterating through the list, collect the subset of permissions that the vehicle is capable of. - Launch Connect with
scope
set to the list of permissions that the vehicle is capable of.
Errors
We updated the errors returned by Smartcar’s API and webhooks to include a lot more detail. We also introduced new error types and codes to let developers more easily investigate Smartcar errors.
Smartcar errors now contain the following properties:
Property | Description |
---|---|
type | A unique identifier that groups codes into broad categories of errors. This property roughly maps to the “error” property in version 1.0, but we have renamed the types and introduced new ones. |
code | A short, descriptive identifier for the error that occurred. This property roughly maps to the “code” property in version 1.0, but we have renamed the codes and introduced new ones. |
description | A short description of the code that provides additional information about the error. This property maps to the “message” property in version 1.0. |
docURL | A link to Smartcar’s doc center guide for the given type and code |
statusCode | The HTTP status code |
requestId | Smartcar’s request ID |
resolution | An enumerated type that specifies which action can be taken to resolve this error |
Migration steps
- Reference
body.type
instead ofbody.error
. - Reference
body.description
instead ofbody.message
. - Make use of the new values of
type
andcode
rather than the old values by referencing the mapping in the table below. Note that some version 1.0 errors map to multiple version 2.0 errors, as version 2.0 contains more detailed errors.
code
s and properties.error (1.0) | code (1.0) | type (2.0) | code (2.0) |
---|---|---|---|
validation_error | N/A | VALIDATION | null |
vehicle_owner_action_required | VOA_000 | CONNECTED_SERVICES_ACCOUNT | AUTHENTICATION_FAILED |
vehicle_owner_error | VOA_001 | CONNECTED_SERVICES_ACCOUNT | SUBSCRIPTION |
vehicle_owner_error | VOA_002 | CONNECTED_SERVICES_ACCOUNT | NO_VEHICLES |
vehicle_owner_error | VOA_002 | CONNECTED_SERVICES_ACCOUNT | VEHICLE_MISSING |
vehicle_owner_error | VOA_003 | CONNECTED_SERVICES_ACCOUNT | ACCOUNT_ISSUE |
authentication_error | N/A | AUTHENTICATION | null |
permission_error | N/A | PERMISSION | null |
resource_not_found_error | N/A | RESOURCE_NOT_FOUND | PATH |
version_not_found_error | N/A | RESOURCE_NOT_FOUND | VERSION |
vehicle_state_error | VS_000 | VEHICLE_STATE | UNKNOWN |
vehicle_state_error | VS_001 | VEHICLE_STATE | DOOR_OPEN |
vehicle_state_error | VS_002 | VEHICLE_STATE | TRUNK_OPEN |
vehicle_state_error | VS_003 | VEHICLE_STATE | HOOD_OPEN |
vehicle_state_error | VS_004 | VEHICLE_STATE | CHARGING_PLUG_NOT_CONNECTED |
vehicle_state_error | VS_005 | VEHICLE_STATE | FULLY_CHARGED |
vehicle_state_error | VS_006 | VEHICLE_STATE | ASLEEP |
vehicle_state_error | VS_007 | VEHICLE_STATE | UNREACHABLE |
vehicle_state_error | VS_008 | VEHICLE_STATE | IGNITION_ON |
vehicle_state_error | VS_009 | VEHICLE_STATE | IN_MOTION |
vehicle_state_error | N/A | VEHICLE_STATE | NOT_CHARGING |
vehicle_state_error | N/A | VEHICLE_STATE | CHARGE_FAULT |
vehicle_state_error | VS_010 | VEHICLE_STATE | REMOTE_ACCESS_DISABLED |
vehicle_state_error | VS_011 | VEHICLE_STATE | CHARGING_IN_PROGRESS |
rate_limiting_error | N/A | RATE_LIMIT | SMARTCAR_API |
monthly_limit_exceeded | N/A | BILLING | VEHICLE_LIMIT |
monthly_limit_exceeded | N/A | BILLING | VEHICLE_REQUEST_LIMIT |
server_error | N/A | SERVER | INTERNAL |
server_error | N/A | UPSTREAM | NO_RESPONSE |
server_error | N/A | UPSTREAM | INVALID_DATA |
server_error | N/A | UPSTREAM | KNOWN_ISSUE |
server_error | N/A | UPSTREAM | UNKNOWN_ISSUE |
server_error | N/A | UPSTREAM | RATE_LIMIT |
vehicle_not_capable_error | N/A | COMPATIBILITY | SMARTCAR_NOT_CAPABLE |
vehicle_not_capable_error | N/A | COMPATIBILITY | VEHICLE_NOT_CAPABLE |
Webhook verification
The verification payload now includes the ID of the requested webhook. It also includes an eventName
property that lets you distinguish verify events from other webhook events. For verify events, the eventName
property will be set to “verify”. The challenge
property is now nested under a payload
property.
{
"version": "2.0",
"webhookId": "uuid",
"eventName": "verify",
"payload": {
"challenge": "string"
}
}
Migration steps
- Reference
body.payload.challenge
instead ofbody.challenge
. - (Optional:) Use
body.eventName
to detect a webhook verification request rather than checking for the presence of thechallege
property.
Webhook event payloads
The vehicles
property is now nested under a payload
property.
{
"version": "2.0",
"webhookId": "uuid",
"eventName": "schedule",
"mode": "test|live",
"payload": {
"vehicles": []
}
}
Migration steps
- Reference
body.payload.vehicles
instead ofbody.vehicles
.