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.

  • 1
  • 2
  • 3
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:

  1. 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.

  2. 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.
  3. 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 application

    b. configuration_error for when exiting Connect back to your app through an error page (see below).

    Error Page

    c. server_error which is thrown if there is not another Connect error specified.

More documentation on error handling can be found here.

March 6, 2023

The disconnect endpoint now supports the use of management API token (MAT) for authorization purposes. Documentation can be found here

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

Smartcar is now compatible with Kia vehicles in Canada and the United States.

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

The Location endpoint is now available for Volkswagen ID series vehicles in our supported European countries.

November 30, 2022

Smartcar is now compatible with Kia vehicles in Canada and the United States.

August 24, 2022

Smartcar is now compatible with Rivian vehicles in the United States.

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

Smartcar is now compatible with Škoda vehicles in our supported European countries.
The EV Charging control endpoint is now available for Hyundai vehicles in the United States.
The EV Battery Capacity endpoint is now available in our supported European countries.

July 20, 2022

Smartcar is now compatible with Citroën, DS, and Vauxhall vehicles in our supported European countries.

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

Smartcar is now compatible with Peugeot and Opel vehicles in our supported European countries.

June 22, 2022

The Tire Pressure endpoint is now available for BMW, MINI, and Tesla vehicles in Canada, the United States, and our supported European countries.

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

Smartcar is now compatible with Nissan vehicles in our supported European countries.

May 9, 2022

Smartcar is now compatible with Kia vehicles in our supported European countries.

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

Smartcar's webhooks now have beta support for sending events in response to events that are generated by the vehicle itself. The initial release supports the following events on Ford, Tesla, and Toyota vehicles in Canada, the United States, and our supported European countries:
    • 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:

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
{
  "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

Smartcar is now compatible with MINI vehicles in Canada, the United States, and our supported European countries.

February 23, 2022

The EV Battery and EV Charging status and control endpoints are now available for Lexus and Toyota vehicles in Canada and the United States.

February 21, 2022

The Tire Pressure endpoint is now available for Lexus and Toyota vehicles in Canada and the United States.

February 14, 2022

Smartcar is now compatible with Chrysler, Dodge, Jeep, and RAM vehicles in Canada.

February 2, 2022

Brand-specific endpoints are now available for Cadillac, Chevrolet, and Tesla. A full list of the available endpoints is available in the API Reference.
  • 1
const amperage = vehicle.request('GET', 'tesla/charge/ammeter');

January 5, 2022

Smartcar is now compatible with Mercedes-Benz vehicles in the United States.

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 the scope parameter provide access to. Each entry has a field named capable that indicates whether the vehicle capable of supporting that specific endpoint.

Please see the API reference for more detail on the new response format.

Example

GET https://api.smartcar.com/v2.0/compatibility?vin=PLACEHOLDER&scope=read_battery&country=us
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
{
  "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:

  1. If compatible is false, use the reason 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).
  2. 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.
  3. 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:

PropertyDescription
typeA 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.
codeA 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.
descriptionA short description of the code that provides additional information about the error. This property maps to the “message” property in version 1.0.
docURLA link to Smartcar’s doc center guide for the given type and code
statusCodeThe HTTP status code
requestIdSmartcar’s request ID
resolutionAn enumerated type that specifies which action can be taken to resolve this error

Migration steps

  1. Reference body.type instead of body.error.
  2. Reference body.description instead of body.message.
  3. Make use of the new values of type and code 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.
The above steps correspond to the minimal amount of work that you’ll need to do in order to start using version 2.0 of the Smartcar API. In addition to those steps, we recommend that you read the new error guides and make use of all new codes and properties.
error (1.0)code (1.0)type (2.0)code (2.0)
validation_errorN/AVALIDATIONnull
vehicle_owner_action_requiredVOA_000CONNECTED_SERVICES_ACCOUNTAUTHENTICATION_FAILED
vehicle_owner_errorVOA_001CONNECTED_SERVICES_ACCOUNTSUBSCRIPTION
vehicle_owner_errorVOA_002CONNECTED_SERVICES_ACCOUNTNO_VEHICLES
vehicle_owner_errorVOA_002CONNECTED_SERVICES_ACCOUNTVEHICLE_MISSING
vehicle_owner_errorVOA_003CONNECTED_SERVICES_ACCOUNTACCOUNT_ISSUE
authentication_errorN/AAUTHENTICATIONnull
permission_errorN/APERMISSIONnull
resource_not_found_errorN/ARESOURCE_NOT_FOUNDPATH
version_not_found_errorN/ARESOURCE_NOT_FOUNDVERSION
vehicle_state_errorVS_000VEHICLE_STATEUNKNOWN
vehicle_state_errorVS_001VEHICLE_STATEDOOR_OPEN
vehicle_state_errorVS_002VEHICLE_STATETRUNK_OPEN
vehicle_state_errorVS_003VEHICLE_STATEHOOD_OPEN
vehicle_state_errorVS_004VEHICLE_STATECHARGING_PLUG_NOT_CONNECTED
vehicle_state_errorVS_005VEHICLE_STATEFULLY_CHARGED
vehicle_state_errorVS_006VEHICLE_STATEASLEEP
vehicle_state_errorVS_007VEHICLE_STATEUNREACHABLE
vehicle_state_errorVS_008VEHICLE_STATEIGNITION_ON
vehicle_state_errorVS_009VEHICLE_STATEIN_MOTION
vehicle_state_errorN/AVEHICLE_STATENOT_CHARGING
vehicle_state_errorN/AVEHICLE_STATECHARGE_FAULT
vehicle_state_errorVS_010VEHICLE_STATEREMOTE_ACCESS_DISABLED
vehicle_state_errorVS_011VEHICLE_STATECHARGING_IN_PROGRESS
rate_limiting_errorN/ARATE_LIMITSMARTCAR_API
monthly_limit_exceededN/ABILLINGVEHICLE_LIMIT
monthly_limit_exceededN/ABILLINGVEHICLE_REQUEST_LIMIT
server_errorN/ASERVERINTERNAL
server_errorN/AUPSTREAMNO_RESPONSE
server_errorN/AUPSTREAMINVALID_DATA
server_errorN/AUPSTREAMKNOWN_ISSUE
server_errorN/AUPSTREAMUNKNOWN_ISSUE
server_errorN/AUPSTREAMRATE_LIMIT
vehicle_not_capable_errorN/ACOMPATIBILITYSMARTCAR_NOT_CAPABLE
vehicle_not_capable_errorN/ACOMPATIBILITYVEHICLE_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.

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
{
  "version": "2.0",
  "webhookId": "uuid",
  "eventName": "verify",
  "payload": {
    "challenge": "string"
  }
}

Migration steps

  1. Reference body.payload.challenge instead of body.challenge.
  2. (Optional:) Use body.eventName to detect a webhook verification request rather than checking for the presence of the challege property.

Webhook event payloads

The vehicles property is now nested under a payload property.

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
{
  "version": "2.0",
  "webhookId": "uuid",
  "eventName": "schedule",
  "mode": "test|live",
  "payload": {
    "vehicles": []
  }
}

Migration steps

  1. Reference body.payload.vehicles instead of body.vehicles.