# smartcar

## Docs

- [Make Specific Endpoints](https://smartcar.com/docs/api-reference/about-brand-specific)
- [All Vehicles](https://smartcar.com/docs/api-reference/all-vehicles): Returns a paged list of all vehicles connected to the application for the current authorized `user`.
- [API Errors](https://smartcar.com/docs/api-reference/api-errors)
- [SDKs](https://smartcar.com/docs/api-reference/api-sdks)
- [Permissions](https://smartcar.com/docs/api-reference/application-permissions): Returns a list of the permissions that have been granted to your application in relation to this vehicle.
- [Audi: Charge Status](https://smartcar.com/docs/api-reference/audi/get-charge): Returns all charging related data for an Audi vehicle.
- [Auth Code Exchange](https://smartcar.com/docs/api-reference/authorization/auth-code-exchange): 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.
- [Token Refresh](https://smartcar.com/docs/api-reference/authorization/token-refresh): 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.
- [Batch](https://smartcar.com/docs/api-reference/batch): Returns a list of responses from multiple Smartcar `GET` endpoints, all combined into a single request.
- [Charge Records](https://smartcar.com/docs/api-reference/bmw/get-charge-records): 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.
- [By Region and Make](https://smartcar.com/docs/api-reference/compatibility/by-region-and-make)
- [By VIN](https://smartcar.com/docs/api-reference/compatibility/by-vin)
- [Lock & Unlock](https://smartcar.com/docs/api-reference/control-lock-unlock): Lock or unlock the vehicle.
- [Start & Stop Charge](https://smartcar.com/docs/api-reference/evs/control-charge): Start or stop the vehicle charging.
- [Battery Capacity](https://smartcar.com/docs/api-reference/evs/get-battery-capacity): Returns the rated capacity of the electric vehicle's high voltage battery.
- [Battery Level](https://smartcar.com/docs/api-reference/evs/get-battery-level): Returns the state of charge and the remaining range of an electric vehicle's high voltage battery.
- [Charge Limit](https://smartcar.com/docs/api-reference/evs/get-charge-limit): Returns the charge limit configuration for the vehicle.
- [Charge Status](https://smartcar.com/docs/api-reference/evs/get-charge-status): Returns the charge status for the vehicle.
- [Charge Limit](https://smartcar.com/docs/api-reference/evs/set-charge-limit): Set the  charge limit of an electric vehicle.
- [Charge Schedule by Location](https://smartcar.com/docs/api-reference/ford/get-charge-schedule-by-location): Returns all saved charging locations for a vehicle and their associated charging limits, schedules and configurations.
- [Charge Schedule by Location](https://smartcar.com/docs/api-reference/ford/set-charge-schedule-by-location): Set all schedules for the specified charging location.
- [Oil Life](https://smartcar.com/docs/api-reference/get-engine-oil-life): Returns the remaining life span of a vehicle’s engine oil.
- [Fuel Tank](https://smartcar.com/docs/api-reference/get-fuel-tank): Returns the status of the fuel remaining in the vehicle’s fuel tank.
- [Location](https://smartcar.com/docs/api-reference/get-location): Returns the vehicle's last known location.
- [Lock Status](https://smartcar.com/docs/api-reference/get-lock-status): Returns the lock status for a vehicle and the open status of its doors, windows, storage units, sunroof and charging port where available.
- [Odometer](https://smartcar.com/docs/api-reference/get-odometer): Returns the vehicle’s last known odometer reading.
- [Service History](https://smartcar.com/docs/api-reference/get-service-records): Retrieve service records tracked by the vehicle's dealer or manually added by the vehicle owner. Currently supporting Ford, Lincoln, Toyota, Lexus, Mazda and Volkswagen (US)
- [System Status (Early Access)](https://smartcar.com/docs/api-reference/get-system-status): Provides a list of vehicle systems and their current health status. Currently supporting FCA and GM brands including RAM, Jeep, Chrysler, Dodge, Fiat, Alpha Romeo, Buick, Cadillac, Chevrolet and GMC. See [Diagnostic Systems](/docs/help/diagnostic-systems) for a complete list of Smartcar System IDs.
- [Tire Pressure](https://smartcar.com/docs/api-reference/get-tire-pressure): Returns the air pressure of each of the vehicle’s tires.
- [Vehicle Attributes](https://smartcar.com/docs/api-reference/get-vehicle-info): Returns a single vehicle object, containing identifying information.
- [VIN](https://smartcar.com/docs/api-reference/get-vin): Returns the vehicle’s manufacturer identifier.
- [Charge Completion Time](https://smartcar.com/docs/api-reference/gm/get-charge-completion-time): 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.
- [Voltage](https://smartcar.com/docs/api-reference/gm/get-charge-voltmeter): 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.
- [Headers](https://smartcar.com/docs/api-reference/headers)
- [Smartcar API Reference](https://smartcar.com/docs/api-reference/intro)
- [Makes](https://smartcar.com/docs/api-reference/makes): Valid values for the `make` parameter
- [Vehicle Connections](https://smartcar.com/docs/api-reference/management/delete-vehicle-connections): Deletes all vehicle connections associated with a Smartcar user ID or a specific vehicle.
- [Vehicle Connections](https://smartcar.com/docs/api-reference/management/get-vehicle-connections): 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.
- [Charge Schedule](https://smartcar.com/docs/api-reference/nissan/get-charge-schedule): Returns the charging schedule of a vehicle. The response contains the start time and departure time of the vehicle's charging schedule.
- [Charge Schedule](https://smartcar.com/docs/api-reference/nissan/set-charge-schedule): Sets the charging schedule for a vehicle.
- [Permissions](https://smartcar.com/docs/api-reference/permissions): 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).
- [Send Destination](https://smartcar.com/docs/api-reference/send-destination-to-vehicle): Send destination coordinates to the vehicle's navigation system.
- [Clear PIN to Drive](https://smartcar.com/docs/api-reference/tesla/clear-pin-to-drive): Disables this feature on the vehicle and resets the PIN.
- [Charge Port](https://smartcar.com/docs/api-reference/tesla/control-charge-port): Open or close the vehicle's charge port door.
- [Frunk](https://smartcar.com/docs/api-reference/tesla/control-frunk): Open or close the frunk (front trunk) of the Tesla vehicle.
- [Trunk](https://smartcar.com/docs/api-reference/tesla/control-trunk): Open or close the trunk of the Tesla vehicle.
- [Alerts](https://smartcar.com/docs/api-reference/tesla/get-alerts): Returns recent alerts from the vehicle.
- [Tesla: Battery Status](https://smartcar.com/docs/api-reference/tesla/get-battery): Returns all battery related data for a Tesla vehicle.
- [Cabin Climate](https://smartcar.com/docs/api-reference/tesla/get-cabin): Returns the current state and target temperature setting of a vehicle's cabin climate system.
- [Tesla: Charge Status](https://smartcar.com/docs/api-reference/tesla/get-charge): Returns all charging related data for a Tesla vehicle.
- [Charge Completion Time](https://smartcar.com/docs/api-reference/tesla/get-charge-completion-time): 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.
- [Charge Billing Records](https://smartcar.com/docs/api-reference/tesla/get-charge-records-billing): Returns information about charging sessions for Tesla vehicles at public Tesla chargers including cost and charging site.
- [Charge Schedule](https://smartcar.com/docs/api-reference/tesla/get-charge-schedule): Returns the charging schedule of a vehicle. The response contains the start time and departure time of the vehicle's charging schedule.
- [Voltage](https://smartcar.com/docs/api-reference/tesla/get-charge-voltmeter): 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.
- [Wattage](https://smartcar.com/docs/api-reference/tesla/get-charge-wattmeter): 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.
- [Compass](https://smartcar.com/docs/api-reference/tesla/get-compass-heading): Returns the current compass heading and direction of the vehicle.
- [Defroster](https://smartcar.com/docs/api-reference/tesla/get-defroster): Returns the current state of a vehicle's front and rear defroster.
- [Extended Vehicle Info](https://smartcar.com/docs/api-reference/tesla/get-ext-vehicle-info): Returns detailed configuration information for a vehicle.
- [Exterior Temperature](https://smartcar.com/docs/api-reference/tesla/get-exterior-temperature): 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.
- [Interior Temperature](https://smartcar.com/docs/api-reference/tesla/get-interior-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.
- [Migration Status](https://smartcar.com/docs/api-reference/tesla/get-migration-status): Indicates if the vehicle needs to migrate to Tesla's new API. See [Tesla - What's New](https://smartcar.com/docs/help/oem-integrations/tesla/whats-new) for more details.
- [Speed](https://smartcar.com/docs/api-reference/tesla/get-speedometer): Returns the current speed of the vehicle.
- [Steering Heater](https://smartcar.com/docs/api-reference/tesla/get-steering-heater): Returns the current state of a vehicle's steering wheel heater system.
- [User Access](https://smartcar.com/docs/api-reference/tesla/get-user-access): Returns the account type and permissions for the connected Tesla account.
- [User Info](https://smartcar.com/docs/api-reference/tesla/get-user-info): Returns the email associated with the connected Tesla account.
- [Vehicle Status](https://smartcar.com/docs/api-reference/tesla/get-vehicle-status): Returns the status for the vehicle.
- [Virtual Key Status](https://smartcar.com/docs/api-reference/tesla/get-virtual-key-status): Indicates if a vehicle has the appropriate virtual key installed. See [Tesla - What's New](https://smartcar.com/docs/help/oem-integrations/tesla/whats-new#if-your-application-issues-commands) for more details on Tesla's virtual key requirements.
- [Cabin Climate](https://smartcar.com/docs/api-reference/tesla/set-cabin): Set the temperature and control the cabin climate system for a vehicle.
- [Amperage](https://smartcar.com/docs/api-reference/tesla/set-charge-ammeter): 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.
- [Charge Schedule](https://smartcar.com/docs/api-reference/tesla/set-charge-schedule): Sets the charging schedule for a vehicle.
- [Defroster](https://smartcar.com/docs/api-reference/tesla/set-defroster): Start or stop the front and rear defroster for a vehicle.
- [Set PIN to Drive](https://smartcar.com/docs/api-reference/tesla/set-pin-to-drive): Enables this feature on the vehicle and sets the PIN needed in order to drive it.
- [Steering Heater](https://smartcar.com/docs/api-reference/tesla/set-steering-heater): Start or stop heating a vehicle's steering wheel.
- [User](https://smartcar.com/docs/api-reference/user): Returns the ID of the vehicle owner who granted access to your application.
- [Callback URI Verification](https://smartcar.com/docs/api-reference/webhooks/callback-verification)
- [Payload Verification](https://smartcar.com/docs/api-reference/webhooks/payload-verification)
- [Subscribe](https://smartcar.com/docs/api-reference/webhooks/subscribe-webhook): Subscribe a vehicle to a webhook.
- [Unsubscribe](https://smartcar.com/docs/api-reference/webhooks/unsubscribe-webhook): Unsubscribe a vehicle from a webhook.
- [2022 Releases](https://smartcar.com/docs/changelog/2022)
- [2023 Releases](https://smartcar.com/docs/changelog/2023)
- [April 2024 Releases](https://smartcar.com/docs/changelog/2024/april)
- [August 2024 Releases](https://smartcar.com/docs/changelog/2024/august)
- [February 2024 Releases](https://smartcar.com/docs/changelog/2024/february)
- [July 2024 Releases](https://smartcar.com/docs/changelog/2024/july)
- [June 2024 Releases](https://smartcar.com/docs/changelog/2024/june)
- [March 2024 Releases](https://smartcar.com/docs/changelog/2024/march)
- [May 2024 Releases](https://smartcar.com/docs/changelog/2024/may)
- [October 2024 Releases](https://smartcar.com/docs/changelog/2024/october)
- [September 2024 Releases](https://smartcar.com/docs/changelog/2024/september)
- [Latest Releases](https://smartcar.com/docs/changelog/latest)
- [Country Selection](https://smartcar.com/docs/connect/advanced-config/country-flag): 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.
- [Connect Flows](https://smartcar.com/docs/connect/advanced-config/flows): 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.
- [Modes](https://smartcar.com/docs/connect/advanced-config/modes)
- [Auth Code Exchange](https://smartcar.com/docs/connect/auth-code-exchange)
- [SDKs for Connect](https://smartcar.com/docs/connect/connect-sdks): Our SDKs make integrating Smartcar fast and easy in different languages and frameworks.
- [Dashboard Configuration](https://smartcar.com/docs/connect/dashboard-config)
- [Handle the Response](https://smartcar.com/docs/connect/handle-the-response): 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 parameter. In the case of on error, we'll provide an error and description as parameters instead.
- [Handle the Response](https://smartcar.com/docs/connect/re-auth/handle-response): 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.
- [Redirect to Connect](https://smartcar.com/docs/connect/re-auth/redirect-to-connect)
- [Build the Connect URL](https://smartcar.com/docs/connect/redirect-to-connect)
- [Overview](https://smartcar.com/docs/connect/token-management/overview): After fetching your first token pair, you'll need to manage them in order to maintain access to the vehicle.
- [Refreshing Refresh Tokens](https://smartcar.com/docs/connect/token-management/refresh-refresh-token): Refresh tokens expire after **60 days ordinarily** or **after 1 minute when used to fetch a new token pair**.
- [Refreshing Access Tokens](https://smartcar.com/docs/connect/token-management/refreshing-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 corresponding `REFRESH_TOKEN`.
- [What is Connect?](https://smartcar.com/docs/connect/what-is-connect)
- [Authentication Errors](https://smartcar.com/docs/errors/api-errors/authentication-errors): Thrown when there is an issue with your authorization header.
- [Billing Errors](https://smartcar.com/docs/errors/api-errors/billing-errors): Thrown when limits have been reached based on your plan, or if the feature is not avaible.
- [Compatibility Errors](https://smartcar.com/docs/errors/api-errors/compatibility-errors): Thrown when Smartcar does not support a make, or feature for a vehicle.
- [Connected Services Account Errors](https://smartcar.com/docs/errors/api-errors/connected-services-account-errors): Thrown when there are issues with the user's connected service account.
- [Permission Errors](https://smartcar.com/docs/errors/api-errors/permission-errors): Thrown when Smartcar does not support a make or feature for a vehicle.
- [Rate Limit Errors](https://smartcar.com/docs/errors/api-errors/rate-limit-errors): Thrown when there is an issue with the frequency of your requests.
- [Resource Not Found](https://smartcar.com/docs/errors/api-errors/resource-not-found-errors): Thrown when the incorrect API version is used or when the endpoint URL is incorrect.
- [Server Errors](https://smartcar.com/docs/errors/api-errors/server-errors): Thrown when Smartcar runs into an unexpected issue and was unable to process the request.
- [Upstream Errors](https://smartcar.com/docs/errors/api-errors/upstream-errors): Thrown when the OEM servers or vehicle failed to process the request.
- [Validation Errors](https://smartcar.com/docs/errors/api-errors/validation-errors): Thrown if there is an issue with the format of the request or body.
- [Vehicle State Errors](https://smartcar.com/docs/errors/api-errors/vehicle-state-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.
- [Access Denied](https://smartcar.com/docs/errors/connect-errors/access-denied): This error occurs when a user denies your application access to the requested scope of permissions.
- [Configuration](https://smartcar.com/docs/errors/connect-errors/configuration-error): This error occurs when the user has encountered an Error page in Connect and has chosen to return to your application.
- [Invalid Subscription](https://smartcar.com/docs/errors/connect-errors/invalid-subscription): 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.
- [No Vehicles](https://smartcar.com/docs/errors/connect-errors/no-vehicles): This error occurs when a vehicle owner has a connected services account, but there are no vehicles associated with the account.
- [OEM Login Cancelled](https://smartcar.com/docs/errors/connect-errors/oem-login-cancelled): This error occurs when a user went to authorize directly with the OEM but exited the flow for some reason.
- [User returned to application](https://smartcar.com/docs/errors/connect-errors/returned-to-application): This error occurs when a user leaves the Connect flow after hitting **Back to application** before granting your application access to their vehicle.
- [Server](https://smartcar.com/docs/errors/connect-errors/server-error): If there is a server error, the user will return to your application.
- [Vehicle Incompatible](https://smartcar.com/docs/errors/connect-errors/vehicle-incompatible): This error occurs when a user tries to authorize an incompatible vehicle in Smartcar Connect.
- [Overview](https://smartcar.com/docs/errors/overview): A comprehensive breakout of all Smartcar errors.
- [Testing Errors](https://smartcar.com/docs/errors/testing-errors): By launching Connect in [simulated mode](/docs/connect/advanced-config/modes), you're able to test your application against certain errors.
- [Dashboard Configurations](https://smartcar.com/docs/getting-started/dashboard/configuration)
- [Dashboard Multi-Factor Authentication (MFA)](https://smartcar.com/docs/getting-started/dashboard/dashboard-mfa)
- [Dashboard Overview](https://smartcar.com/docs/getting-started/dashboard/overview): All you need to know about the Smartcar Dashboard
- [Vehicle Simulator](https://smartcar.com/docs/getting-started/dashboard/simulator)
- [Charging Station Utilization](https://smartcar.com/docs/getting-started/guides/charging-station-utilization): This guide explains how to use the Smartcar API to enhance charging station discoverability by leveraging vehicle data such as state of charge,  battery level, range, and location. These capabilities allow developers to help EV drivers find nearby charging stations based on real-time vehicle data.
- [Plan Your Integration](https://smartcar.com/docs/getting-started/integration-overview)
- [Introduction to Smartcar's API](https://smartcar.com/docs/getting-started/introduction): Learn about how to build applications that connect to millions of vehicles around the world.
- [Test Your Integration](https://smartcar.com/docs/getting-started/test-your-integration)
- [Android Tutorial](https://smartcar.com/docs/getting-started/tutorials/android): In this tutorial, we will use the Android SDK to integrate Connect into your application.
- [Backend SDK Tutorials](https://smartcar.com/docs/getting-started/tutorials/backend): In this tutorial, we will go over how  to integrate Connect into your application and make requests to a vehicle using our backend SDKs.
- [iOS Tutorial](https://smartcar.com/docs/getting-started/tutorials/ios): In this tutorial, we will use the iOS SDK to integrate Connect into your application.
- [React Tutorial](https://smartcar.com/docs/getting-started/tutorials/react): In this tutorial, we will use the JavaScript SDK to integrate Connect into your application.
- [Dynamic Webhooks (Early Access)](https://smartcar.com/docs/getting-started/tutorials/webhooks-dynamic): Dynamic webhooks make it incredibly easy to receive data from a vehicle at the optimal frequency supported by the OEM. Specifically, once a certain condition is met, you will be able to receive data more frequently from the vehicle to stay up-to-date with the state of the vehicle when it matters most to you.
- [Scheduled Webhooks](https://smartcar.com/docs/getting-started/tutorials/webhooks-scheduled): 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.
- [Testing with Postman](https://smartcar.com/docs/getting-started/using-vs-with-postman): In this guide we'll go over how to use Vehicle Simulator to test out Smartcar using Postman.
- [Smartcar Usage Limits](https://smartcar.com/docs/help/api-limits): Learn about limits you may encounter when using Smartcar.
- [Brand Quirks](https://smartcar.com/docs/help/brand-quirks): Brand specific quirks to keep in mind while building out your application.
- [Brand Subscription Information](https://smartcar.com/docs/help/brand-subscriptions): Below you can find the connected service name for each brand as well as any specific subscription packages needed to connect to the vehicle via Smartcar.
- [Compatible Vehicles](https://smartcar.com/docs/help/compatibility)
- [Connect your car](https://smartcar.com/docs/help/connect-your-car)
- [Diagnostic Systems](https://smartcar.com/docs/help/diagnostic-systems): To support our System Status endpoint, reference the below list of unified systems.
- [Early Access](https://smartcar.com/docs/help/early-access): Understand Smartcar's approach to Early Access features.
- [Frequently Asked Questions (FAQs)](https://smartcar.com/docs/help/faqs)
- [Submit a Feature Request](https://smartcar.com/docs/help/feature-request)
- [Upgraded Tesla API Integration](https://smartcar.com/docs/help/oem-integrations/tesla/developers): This page has information regarding Smartcar's upgraded Tesla integration and what this means for developers. For an overview of the changes see [this page](https://smartcar.com/docs/help/oem-integrations/tesla/whats-new).
- [Tesla FAQs](https://smartcar.com/docs/help/oem-integrations/tesla/faqs): FAQs on our new Tesla integration. For an overview of the changes see [this page](https://smartcar.com/docs/help/oem-integrations/tesla/whats-new).
- [What's New?](https://smartcar.com/docs/help/oem-integrations/tesla/whats-new)
- [OEM Latency](https://smartcar.com/docs/help/oem-latency): Request latency we've observed by make
- [Reliability and Data Age](https://smartcar.com/docs/help/reliability-and-freshness): When making requests to vehicles, there is variation in how often data is updated and how many requests it can process in a given period. The tables below indicate the performance for each of Smartcar supported brands in each region.
- [Join the Research Fleet](https://smartcar.com/docs/help/research-fleet)
- [Teams](https://smartcar.com/docs/help/teams): With Teams you're able to easily manage your team's access to Dashboard
- [Vehicle Simulator](https://smartcar.com/docs/help/vehicle-simulator): Learn about what to expect from Vehicle Simulator and how it compares to Live mode.
- [What is a Connected Car?](https://smartcar.com/docs/help/what-is-a-connected-car): Learn about how to build applications that connect to millions of vehicles around the world.
- [What is Smartcar?](https://smartcar.com/docs/help/what-is-smartcar): Learn about how to build applications that connect to millions of vehicles around the world.


# Make Specific Endpoints



In cases where there are many differences in how each OEM provides the same data, Smartcar will provide you with a make-specific endpoint before making it widely available to all supported makes. This allows our customers to start taking advantage of these endpoints and share feedback with Smartcar earlier.

These endpoints will maintain consistent behavior and will not "break" with future releases. In time, a make-specific endpoint might be standardized across various makes, eliminating the need to indicate the make in the URL. You won't need to modify your code but you might benefit from a newly standardized version.

<Info>When using make specific endpoints, please ensure to specify the make in lower case format. Using upper case letters will result in a PERMISSION error.</Info>


# All Vehicles

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

## Request

**Query**

<ParamField query="limit" type="integer" default="10">
  The number of vehicles to return per page. `Max: 50`
</ParamField>

<ParamField query="offset" type="integer">
  The index to start the `vehicles` list at.
</ParamField>

<RequestExample>
  <Snippet file="api-reference/core-sdk-methods/all-vehicles.mdx" />
</RequestExample>

## Response

<ResponseField name="paging" type="Object">
  Metadata about the current list of elements.

  <Expandable>
    <ResponseField name="count" type="integer">
      The total number of elements for the entire query (not just the given page).
    </ResponseField>

    <ResponseField name="offset" type="integer">
      The current start index of the returned list of elements.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="vehicles" type="[string]">
  An array of vehicle IDs.
</ResponseField>

<ResponseExample>
  ```json Example Response
  {
      "paging": {
          "count": 25,
          "offset": 10
      },
      "vehicles": [
          "36ab27d0-fd9d-4455-823a-ce30af709ffc"
      ]
  }
  ```
</ResponseExample>


# API Errors



Smartcar uses HTTP status codes to indicate success or failure of API requests. This includes:

*   `2XX`: indicates success
*   `4XX`: indicates an invalid request (e.g. a required parameter is missing from the request body)
*   `5XX`: indicates Smartcar-related issues (e.g. a vehicle is not capable of fulfilling a request).

## Error Response

All Smartcar errors contain the following fields:

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

## Error Codes

| 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    |
| `ACCOUNT_SUSPENDED`           | `BILLING`                    | 430    |
| `INTERNAL`                    | `SERVER`                     | 500    |
| `INTERNAL`                    | `MULTIPLE_RECORDS_FOUND`     | 500    |
| `INTERNAL`                    | `RECORD_NOT_FOUND`           | 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    |


# SDKs



Our backend SDKs simplify the process of making calls to our API.

<Snippet file="sdks/api-sdk-card-group.mdx" />

<br />

<Tip>
  While we provide a number of SDKs for popular languages, you do not need to use an SDK to integrate with our API.
  Our APIs are just standard HTTP endpoints that can be reached with any HTTP library of your choice.
</Tip>


# Permissions

GET /vehicles/{id}/permissions
Returns a list of the permissions that have been granted to your application in relation to this vehicle.

## Request

<ParamField path="id" type="string" required>
  The vehicle id.
</ParamField>

<ParamField query="limit" type="integer" default="10">
  The number of vehicles to return per page. `Max: 50`
</ParamField>

<ParamField query="offset" type="integer">
  The index to start vehicle list at.
</ParamField>

<RequestExample>
  <Snippet file="api-reference/core-sdk-methods/application-permissions.mdx" />
</RequestExample>

## Response

<ResponseField name="permissions" type="[permissions]">
  An array of [permissions](/api-reference/permissions).
</ResponseField>

<ResponseField name="paging" type="object">
  Metadata about the current list of elements.

  <Expandable>
    <ResponseField name="count" type="integer">
      The total number of elements for the entire query (not just the given page).
    </ResponseField>

    <ResponseField name="offset" type="integer">
      The current start index of the returned list of elements.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json Example Response
  {
      "paging": {
          "count": 25,
          "offset": 10
      },
      "permissions": [
          "read_vehicle_info"
      ]
  } 
  ```
</ResponseExample>


# Audi: Charge Status

GET /vehicles/{id}/{make}/charge
Returns all charging related data for an Audi vehicle.

<Snippet file="api-reference/note-bse-audi.mdx" />

## Permission

`read_charge`

<RequestExample>
  ```curl cURL
  curl "https://api.smartcar.com/v2.0/vehicles/{id}/{make}/charge" \
  -H "Authorization: Bearer {token}" \
  -X "GET"
  ```

  ```python Python
  charge =  vehicle.request(
        "GET", 
        "{make}/charge"
  )
  ```

  ```js Node
  const charge =  await vehicle.request(
        "GET", 
        "{make}/charge"
  );
  ```

  ```java Java
  SmartcarVehicleRequest request = new SmartcarVehicleRequest.Builder()
        .method("GET")
        .path("{make}/charge")
        .build();
  VehicleResponse charge =  vehicle.request(request);
  ```

  ```ruby Ruby
  charge =  vehicle.request(
        "GET", 
        "{make}/charge"
  )
  ```
</RequestExample>

## Request

**Path**

<Snippet file="api-reference/path-bse.mdx" />

## Response

<ResponseField name="chargingStatus" type="string | null">
  Indicates the charging status of the vehicle
</ResponseField>

<ResponseField name="isPluggedIn" type="bool | null">
  Indicates if the vehicle is plugged in
</ResponseField>

<ResponseField name="wattage" type="number | null">
  The instant power measured by the vehicle (in kilowatts).
</ResponseField>

<ResponseField name="chargeRate" type="number | null">
  The rate of range added in the charging session (in kilometers added / hour).
</ResponseField>

<ResponseField name="chargeType" type="string | null">
  Indicates the type of charger.
</ResponseField>

<ResponseField name="chargePortColor" type="string | null">
  The indicator light color of the connector.
</ResponseField>

<ResponseField name="chargePortLatch" type="string | null">
  Indicates if the charge port latch status.
</ResponseField>

<ResponseField name="completionTime" type="string | null">
  An ISO8601 formatted datetime (YYYY-MM-DDTHH:mm:ss.SSSZ) for the time at which the vehicle expects to complete this charging session.
</ResponseField>

<ResponseField name="chargeMode" type="string | null">
  Indicates if the vehicle is set to charge on a timer. One of `manual` or `timer`.
</ResponseField>

<ResponseField name="socLimit" type="number | null">
  Indicates the level at which the vehicle will stop charging and be considered fully charged as a percentage.
</ResponseField>

<ResponseField name="externalPowerStatus" type="string | null">
  When plugged in indicates if the charging station is able to provide power to the vehicle.
</ResponseField>

<ResponseExample>
  ```json Example Response 
      {
            "chargingStatus": "CHARGING",
            "isPluggedIn": null,
            "chargeRate": 21,
            "chargeType": "ac",
            "chargePortColor": "green",
            "chargePortLatch": "locked",
            "completionTime": "2022-01-13T22:52:55.358Z",
            "chargeMode": "manual",
            "socLimit": 0.8,
            "externalPowerStatus": "active",
            "wattage" : 1.5
      }
  ```
</ResponseExample>


# Auth Code Exchange

POST https://auth.smartcar.com/oauth/token
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.

<Snippet file="authorization/auth-code-exchange.mdx" />


# Token Refresh

POST https://auth.smartcar.com/oauth/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.

<Snippet file="authorization/token-exchange.mdx" />


# Batch

POST /vehicles/{id}/batch
Returns a list of responses from multiple Smartcar `GET` endpoints, all combined into a single request.

<Info>
  Each endpoint in the batch counts against your [request limit](/errors/api-errors/billing-errors) for a vehicle.
</Info>

## Request

**Path**

<Snippet file="api-reference/path-vehicle-id.mdx" />

**Body**

<ParamField body="requests" type="array" required>
  An array of requests to make.

  <Expandable>
    <ParamField body="path" type="string" required>
      The Smartcar endpoint to request data from.
    </ParamField>
  </Expandable>
</ParamField>

<RequestExample>
  <Snippet file="api-reference/core-sdk-methods/batch.mdx" />
</RequestExample>

## Response

<ResponseField name="responses" type="array">
  The responses from Smartcar.

  <Expandable title="response" defaultOpen="true">
    <ResponseField name="headers" type="object">
      The headers for this response.

      <Expandable title="headers">
        <ResponseField name="sc-unit-system">
          The unit system to use for the request.
        </ResponseField>

        <ResponseField name="sc-data-age">
          The timestamp (ISO-8601 format) of when the returned data was recorded by the vehicle.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="code" type="number">
      The HTTP response status code.
    </ResponseField>

    <ResponseField name="path" type="string">
      The Smartcar endpoint to request data from.
    </ResponseField>

    <ResponseField name="body" type="string">
      The response body of this request. The structure of this object will vary by endpoint. See the according endpoint specification.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json Example Response 
  {
    "responses": [
      {
        "path": "/odometer",
        "body": {
          "distance": 37829
        },
        "code": 200,
        "headers": {
          "sc-data-age": "2019-10-24T00:43:46.000Z",
          "sc-unit-system": "metric"
        }
      },
      {
        "path": "/location",
        "body": {
          "latitude": 37.4292,
          "longitude": 122.1381
        },
        "code": 200,
        "headers": {
          "sc-data-age": "2019-10-24T00:43:46.000Z"
        }
      }
    ]
  }
  ```
</ResponseExample>


# Charge Records

GET /vehicles/{id}/{make}/charge/records
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.

<Note>
  This endpoint is currently available for `bmw` and `mini`
</Note>

## Permission

`read_charge_records`

## Request

**Path**

<Snippet file="api-reference/path-bse.mdx" />

**Query**

<ParamField query="startDate">
  Date of the first record to return in YYYY-MM-DD format.
  Defaults to 30 days prior  or when the owner first granted your application access, whichever is shorter.
</ParamField>

<ParamField query="endDate">
  Date of the final record to return in YYYY-MM-DD format. Defaults to the date of the request.
</ParamField>

## Response

<ResponseField name="records" type="[object]">
  An array of charge records for the vehicle.

  <Expandable defaultOpen="true">
    <ResponseField name="chargeStart" type="string">
      The start date of the charging record, formatted in ISO 8601 standard
    </ResponseField>

    <ResponseField name="chargeEnd" type="string">
      The end date of the charging record, formatted in ISO 8601 standard
    </ResponseField>

    <ResponseField name="location" type="string">
      Location of the charge session.
    </ResponseField>

    <ResponseField name="energy" type="number" default="kWh">
      The amount of energy consumed during the charging session.
    </ResponseField>

    <ResponseField name="isPublic" type="bool">
      Indicates whether the charging location is public or not.
    </ResponseField>

    <ResponseField name="startPercentRemaining" type="number">
      The remaining battery soc at the start of the charging session.
    </ResponseField>

    <ResponseField name="endPercentRemaining" type="number">
      The remaining battery soc at the end of the charging session.
    </ResponseField>

    <ResponseField name="chargingType" type="string">
      The type of charger used for the session.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json Example Response 
  {
    "records": [
      {
        "chargeStart" : "2023-03-08T12:54:44Z",
        "chargeEnd" : "2023-03-08T14:14:44Z",
        "location": "Cockfosters Road, Barnet, EN4 0",
        "energy"  : 34.22998046875,
        "isPublic" : true,
        "startPercentRemaining" : 0.57,
        "endPercentRemaining" : 1, 
        "chargingType" : "DC" 
      }
    ]
  }
  ```
</ResponseExample>


# By Region and Make

GET /compatibility/matrix

<Info>
  The Compatibility API is an Enterprise feature. Please [contact us](https://smartcar.com/pricing/) to upgrade your plan.
</Info>

Compatibility by region and make allows developers to query the latest version of our Compatibility Matrix based on region,
engine type, make, and permission.

## Request

**Headers**

<Snippet file="header-basic-auth.mdx" />

**Query**

<ParamField query="region" type="string" initialValue="US" required>
  One of the following regions: `US`, `CA` or `EUROPE`
</ParamField>

<ParamField query="type" type="string">
  Queries for all engine types if none are specified.

  <Expandable>
    <ResponseField name="ICE" />

    <ResponseField name="BEV" />

    <ResponseField name="PHEV" />

    <ResponseField name="HEV" />
  </Expandable>
</ParamField>

<ParamField query="make" type="string" initialValue="NISSAN TESLA ">
  A space-separated list of makes. Valid makes for a given region can be found in the makes section.
</ParamField>

<ParamField query="scope" type="string">
  A space-separated list of [permissions](/api-reference/permissions).
  Queries for all permissions if none are specified.
</ParamField>

<RequestExample>
  <Snippet file="api-reference/compatibility/matrix.mdx" />
</RequestExample>

## Response

<ResponseField name="make" type="array">
  An array of models supported for the given `make`.

  <Expandable title="make[]">
    <ResponseField name="model" type="string">
      `model` for the given `make`.
    </ResponseField>

    <ResponseField name="startYear" type="number">
      The earliest model year supported by Smartcar.
    </ResponseField>

    <ResponseField name="endYear" type="number">
      The latest model year supported by Smartcar.
    </ResponseField>

    <ResponseField name="type" type="string">
      Engine type for the given `model`.

      <Expandable title="type">
        <ResponseField name="ICE" />

        <ResponseField name="BEV" />

        <ResponseField name="PHEV" />

        <ResponseField name="HEV" />
      </Expandable>
    </ResponseField>

    <ResponseField name="endpoints" type="array">
      An array of endpoints supported for the given `model`.
    </ResponseField>

    <ResponseField name="permissions" type="array">
      An array of `permissions` supported for the given `model`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json Example Response 
    {
      "NISSAN": [
        {
          "model": "LEAF",
          "startYear": 2018,
          "endYear": 2022,
          "type": "BEV",
          "endpoints": [
            "EV battery",
            "EV charging status",
            "Location",
            "Lock & unlock",
            "Odometer"
          ],
          "permissions": [
            "read_battery",
            "read_charge",
            "read_location",
            "control_security",
            "read_odometer"
          ]
        }
      ],
      "TESLA": [
        {
          "model": "3",
          "startYear": 2017,
          "endYear": 2023,
          "type": "BEV",
          "endpoints": [
            "EV battery",
            "EV charging status",
            "EV start & stop charge",
            "Location",
            "Lock & unlock",
            "Odometer",
            "Tire pressure"
          ],
          "permissions": [
            "read_battery",
            "read_charge",
            "control_charge",
            "read_location",
            "control_security",
            "read_odometer",
            "read_tires"
          ]
        }
      ]
    }
  ```
</ResponseExample>


# By VIN

GET /compatibility

<Info>
  The Compatibility API is an Enterprise feature. Please [contact us](https://smartcar.com/pricing/) to upgrade your plan.
</Info>

Compatibility by VIN allows developers to determine if a specific vehicle is compatible with Smartcar.

A vehicle is capable of a given feature if:

1.  The vehicle supports the feature (e.g., a Ford Escape supports /fuel but a Mustang Mach-e does not)
2.  Smartcar supports the feature for the vehicle's make

This endpoint only supports checking capabilities for vehicles sold in the United States. It **does not** support checking `capabilities` for VINs in Canada and Europe.

## Request

**Headers**

<Snippet file="header-basic-auth.mdx" />

**Parameters**

<ParamField query="vin" type="string" initialValue="1SCCRYW2W1C7BYB78" required>
  The VIN (Vehicle Identification Number) of the vehicle.
</ParamField>

<ParamField query="scope" type="string" initialValue="read_odometer read_fuel" required>
  A space-separated list of permissions.
</ParamField>

<ParamField query="country" type="string" default="US">
  An optional country code string according to ISO 3166-1 alpha-2.
</ParamField>

<RequestExample>
  <Snippet file="api-reference/compatibility/vin.mdx" />
</RequestExample>

## Response

<ResponseField name="compatible" type="boolean">
  `true` if the vehicle is likely compatible, `false` otherwise.
</ResponseField>

<ResponseField name="reason" type="string | null">
  One of the reasons described below if compatible is `false`, `null` otherwise

  <Expandable title="reasons">
    <ResponseField name="VEHICLE_NOT_COMPATIBLE">
      The vehicle does not have the hardware required for internet connectivity
    </ResponseField>

    <ResponseField name="MAKE_NOT_COMPATIBLE">
      Smartcar is not yet compatible with the vehicle's make in the specified country
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="capabilities" type="array">
  An array containing capability objects for the set of endpoints that the provided scope value can provide authorization for.
  This array will be empty if `compatible` is `false`.

  <Expandable title="Capability object">
    <ResponseField name="permission" type="string">
      One of the permissions provided in the scope parameter
    </ResponseField>

    <ResponseField name="endpoint" type="string">
      One of the endpoints that the permission authorizes access to
    </ResponseField>

    <ResponseField name="capable" type="boolean">
      `true` if the vehicle is likely capable of this feature, `false` otherwise
    </ResponseField>

    <ResponseField name="reason" type="string | null">
      One of the reasons described below if capable is `false`, `null` otherwise

      <Expandable title="reasons">
        <ResponseField name="VEHICLE_NOT_CAPABLE">
          The vehicle does not support this feature
        </ResponseField>

        <ResponseField name="SMARTCAR_NOT_CAPABLE">
          Smartcar is not capable of supporting the given feature on the vehicle's make
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json Example Response
    {
    "compatible": true,
    "reason": null,
    "capabilities": [
      {
        "capable": false,
        "endpoint": "/engine/oil",
        "permission": "read_engine_oil",
        "reason": "SMARTCAR_NOT_CAPABLE"
      },
      {
        "capable": true,
        "endpoint": "/battery",
        "permission": "read_battery",
        "reason": null
      },
      {
        "capable": true,
        "endpoint": "/battery/capacity",
        "permission": "read_battery",
        "reason": null
      },
      {
        "capable": true,
        "endpoint": "/vin",
        "permission": "read_vin",
        "reason": null
      }
    ]
  }
  ```
</ResponseExample>

<Info>
  A vehicle's compatibility depends on many factors such as its make, model, model year, trim, etc. The API optimizes returning false positives.
</Info>


# Lock & Unlock

POST /vehicles/{id}/security
Lock or unlock the vehicle.

## Permission

`control_security`

## Request

**Path**

<Snippet file="api-reference/path-vehicle-id.mdx" />

**Body**

<ParamField body="action" type="string" initialValue="UNLOCK" required>
  `LOCK` or `UNLOCK` the vehicle’s doors.
</ParamField>

<RequestExample>
  <Snippet file="api-reference/core-sdk-methods/control-lock-unlock.mdx" />
</RequestExample>

## Response

<ResponseField name="status" type="string">
  If the request is successful, Smartcar will return “success” (HTTP 200 status).
</ResponseField>

<ResponseField name="message" type="string">
  If the request is successful, Smartcar will return a message (HTTP 200 status).
</ResponseField>

<ResponseExample>
  ```json Example Response 
  {
      "message": "Successfully sent request to vehicle",
      "status": "success"
  }   
  ```
</ResponseExample>


# Start & Stop Charge

POST /vehicles/{id}/charge
Start or stop the vehicle charging.

## Permission

`control_charge`

## Request

**Path**

<Snippet file="api-reference/path-vehicle-id.mdx" />

**Body**

<ParamField body="action" type="string" initialValue="START" required>
  `START` or `STOP` the vehicle charging.
</ParamField>

<RequestExample>
  <Snippet file="api-reference/core-sdk-methods/control-charge.mdx" />
</RequestExample>

## Response

<ResponseField name="status" type="string">
  If the request is successful, Smartcar will return “success”.
</ResponseField>

<ResponseField name="message" type="string">
  If the request is successful, Smartcar will return a message.
</ResponseField>

<ResponseExample>
  ```json Example Response 
      {
          "message": "Successfully sent request to vehicle",
          "status": "success"
      }   
  ```
</ResponseExample>

## Notes

**Ford and Lincoln**<br />
Issuing a start command while the vehicle has a schedule in place for its current charging location will result in the vehicle charging to 100%.

Please see [charge schedule by location](/api-reference/ford/set-charge-schedule-by-location) for details on setting a charge limit with preferred charging times
or clearing schedules.

**Nissan**<br />
Currently only START charge commands are supported in the US. See [Set Charge Schedule](/api-reference/nissan/set-charge-schedule) for details on setting a charge schedule for Nissan vehicles.

**Chevrolet, GMC, Buick and Cadillac**<br />
These vehicles require a minimum charge of 50% in order to be able to start or stop charging via the API.


# Battery Capacity

GET /vehicles/{id}/battery/capacity
Returns the rated capacity of the electric vehicle's high voltage battery.

## Permission

`read_battery`

## Request

**Path**

<Snippet file="api-reference/path-vehicle-id.mdx" />

<RequestExample>
  <Snippet file="api-reference/core-sdk-methods/get-battery-capacity.mdx" />
</RequestExample>

## Response

<ResponseField name="capacity" type="number">
  The rated capacity of the battery in kWh.
</ResponseField>

<ResponseExample>
  ```json Example Response 
  {
      "capacity": 28
  }
  ```
</ResponseExample>


# Battery Level

GET /vehicles/{id}/battery
Returns the state of charge and the remaining range of an electric vehicle's high voltage battery.

## Permission

`read_battery`

<Snippet file="api-reference/note-no-hev-support.mdx" />

## Request

**Path**

<Snippet file="api-reference/path-vehicle-id.mdx" />

<RequestExample>
  <Snippet file="api-reference/core-sdk-methods/get-battery-level.mdx" />
</RequestExample>

## Response

<ResponseField name="percentRemaining" type="number">
  The EV's state of charge as a percentage.
</ResponseField>

<ResponseField name="range" type="number" default="kilometers">
  The estimated remaining distance the vehicle can travel powered by its high voltage battery.
</ResponseField>

<ResponseExample>
  ```json Example Response 
  {
      "percentRemaining": 0.3,
      "range": 40.5
  }
  ```
</ResponseExample>


# Charge Limit

GET /vehicles/{id}/charge/limit
Returns the charge limit configuration for the vehicle.

## Permission

`read_charge`

## Request

**Path**

<Snippet file="api-reference/path-vehicle-id.mdx" />

<RequestExample>
  <Snippet file="api-reference/core-sdk-methods/get-charge-limit.mdx" />
</RequestExample>

## Response

<ResponseField name="limit" type="number">
  The level at which the vehicle will stop charging and be considered fully charged as a percentage.
</ResponseField>

<ResponseExample>
  ```json Example Response 
  {
      "limit": 0.8,
  }
  ```
</ResponseExample>

## Notes

This endpoint will return a [`CHARGING_PLUG_NOT_CONNECTED`](/errors/api-errors/vehicle-state-errors#charging-plug-not-connected)
error if the OEM is unable to provide a charge limit unless the vehicle is plugged in.

**Ford and Lincoln**<br />
If a vehicle starts charing as a result of a [start charge](/api-reference/evs/control-charge) request, this endpoint will always return `1` if the charging location has a schedule in place.

For the vehicle to respect its charge limit, please set one along with preferred charge times or clear the schedule through through the [charge schedule by location](/api-reference/ford/set-charge-schedule-by-location) endpoint.

**BMW and MINI**<br />
Vehicle needs to be on OS Version 8+


# Charge Status

GET /vehicles/{id}/charge
Returns the charge status for the vehicle.

## Permission

`read_charge`

## Request

**Path**

<Snippet file="api-reference/path-vehicle-id.mdx" />

<RequestExample>
  <Snippet file="api-reference/core-sdk-methods/get-charge-status.mdx" />
</RequestExample>

## Response

<ResponseField name="isPluggedIn" type="bool">
  Indicates whether a charging cable is currently plugged into the vehicle’s charge port.
</ResponseField>

<ResponseField name="state" type="string">
  Returns the current charge status of a vehicle. A vehicle can be `FULLY_CHARGED` at less than 100% SoC if its [Charge Limit](/api-reference/evs/get-charge-limit) is less than `1`.

  <Expandable title="states">
    <ResponseField name="CHARGING" />

    <ResponseField name="FULLY_CHARGED" />

    <ResponseField name="NOT_CHARGING" />
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json Example Response 
  {
      "isPluggedIn": true,
      "state": "FULLY_CHARGED"
  }
  ```
</ResponseExample>


# Charge Limit

POST /vehicles/{id}/charge/limit
Set the  charge limit of an electric vehicle.

## Permission

`control_charge`

## Request

**Path**

<Snippet file="api-reference/path-vehicle-id.mdx" />

**Body**

<ParamField body="limit" type="number" initialValue="0.7" required>
  The level at which the vehicle should stop charging and be considered fully charged.
  Cannot be less than `0.5`, or greater than `1`.
</ParamField>

<RequestExample>
  <Snippet file="api-reference/core-sdk-methods/set-charge-limit.mdx" />
</RequestExample>

## Response

<ResponseField name="status" type="string">
  If the request is successful, Smartcar will return “success” (HTTP 200 status).
</ResponseField>

<ResponseField name="message" type="string">
  If the request is successful, Smartcar will return a message (HTTP 200 status).
</ResponseField>

## Notes

This endpoint will return a [`CHARGING_PLUG_NOT_CONNECTED`](/errors/api-errors/vehicle-state-errors#charging-plug-not-connected) error if
the OEM is unable to set a charge limit while the vehicle is unpluged.

**Ford and Lincoln**<br />
If a vehicle starts charing as a result of a [start charge](/api-reference/evs/control-charge) request it will always charge to 100%
if the charging location has a schedule in place.

For the vehicle to respect its charge limit, please set one along with preferred charge
times or clear the schedule through the [charge schedule by location](/api-reference/ford/set-charge-schedule-by-location) endpoint.

**BMW and MINI**<br />
Vehicle needs to be on OS Version 8+

<ResponseExample>
  ```json Example Response 
  {
      "message": "Successfully sent request to vehicle",
      "status": "success"
  }   
  ```
</ResponseExample>


# Charge Schedule by Location

GET /vehicles/{id}/{make}/charge/schedule_by_location
Returns all saved charging locations for a vehicle and their associated charging limits, schedules and configurations.

<Snippet file="api-reference/note-bse-ford.mdx" />

## Permission

`read_charge_locations`

## Request

**Path**

<Snippet file="api-reference/path-bse.mdx" />

<RequestExample>
  ```curl cURL
  curl "https://api.smartcar.com/v2.0/vehicles/{id}/{make}/charge/schedule_by_location" \
  -H "Authorization: Bearer {token}" \
  -X "GET"
  ```

  ```python Python
  chargeScheduleByLocation = vehicle.request(
          "GET", 
          "{make}/charge/schedule_by_location"
      )
  ```

  ```js Node
  const chargeScheduleByLocation = await vehicle.request(
          "GET", 
          "{make}/charge/schedule_by_location"
      );
  ```

  ```java Java
  SmartcarVehicleRequest request = new SmartcarVehicleRequest.Builder()
        .method("GET")
        .path("{make}/charge/schedule_by_location")
        .build();
  VehicleResponse getChargeScheduleByLocation = vehicle.request(request)
  ```

  ```ruby Ruby
  chargeScheduleByLocation = vehicle.request(
          "GET", 
          "{make}/charge/schedule_by_location"
      )
  ```
</RequestExample>

## Response

<ResponseField name="chargingLocations" type="[object] | [empty]">
  An array of charging locations. Empty if none are currently set on the vehicle.

  <Expandable>
    <ResponseField name="chargeLimit" type="number">
      The maximum charge limit for the vehicle at the location as a percent.
    </ResponseField>

    <ResponseField name="location" type="object">
      The latitude and longitude of the charging location.

      <Expandable title="location">
        <ResponseField name="longitude" type="number">
          The longitude of the charging location.
        </ResponseField>

        <ResponseField name="latitude" type="number">
          The latitude of the charging location.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="chargingSchedules" type="object">
      The weekday and weekend charging schedules for the vehicle at the location.

      <Expandable>
        <ResponseField name="weekday" type="[object] | [empty]">
          The charging schedule for the vehicle on weekdays (Monday - Friday).

          <Expandable>
            <ResponseField name="start" type="string">
              The exact hour a vehicle should start charging in HH:00 e.g. 17:00.
            </ResponseField>

            <ResponseField name="end" type="string">
              The exact hour a vehicle should stop charging in HH:00 e.g. 21:00.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="weekend" type="[object] | [empty]">
          The charging schedule for the vehicle on weekends (Saturday - Sunday).

          <Expandable>
            <ResponseField name="start" type="string">
              The exact hour a vehicle should start charging in HH:00 e.g. 17:00.
            </ResponseField>

            <ResponseField name="end" type="string">
              The exact hour a vehicle should stop charging in HH:00 e.g. 21:00.
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json Example Response 
  {
    "chargingLocations": [
      {
        "chargeLimit": 0.8,
        "chargingSchedules": {
          "weekday": [
            {
              "end": "17:00",
              "start": "09:00"
            }
          ],
          "weekend": [
            {
              "end": "17:00",
              "start": "09:00"
            }
          ]
        },
        "location": {
          "latitude": 48.8566,
          "longitude": 2.3522
        }
      }
    ]
  }
  ```
</ResponseExample>

## Example Schedule States

<AccordionGroup>
  <Accordion title="Vehicle will charge at any time">
    ```json
    {
      "chargingLocations": [
        {
          "chargeLimit": 0.8,
          "chargingSchedules": {
            "weekday": [],
            "weekend": []
          },
          "location": {
            "latitude": 48.8566,
            "longitude": 2.3522
          }
        }
      ]
    }
    ```
  </Accordion>

  <Accordion title="Vehicle has a schedule for Weekdays only">
    ```json
    {
      "chargingLocations": [
        {
          "chargeLimit": 0.8,
          "chargingSchedules": {
            "weekday": [
              {
                "end": "17:00",
                "start": "09:00"
              }
            ],
            "weekend": []
          },
          "location": {
            "latitude": 48.8566,
            "longitude": 2.3522
          }
        }
      ]
    }
    ```
  </Accordion>

  <Accordion title="Vehicle has a schedule for Weekends only">
    ```json
    {
        "chargingLocation" : {   
            "chargeLimit": 0.9, 
            "chargingSchedules": {
                "weekday": [], 
                "weekend": [
                    {   
                        "start": "16:00", 
                        "end": "07:00"
                    }
                ]
            }
        }
    }
    ```
  </Accordion>
</AccordionGroup>


# Charge Schedule by Location

PUT /vehicles/{id}/{make}/charge/schedule_by_location
Set all schedules for the specified charging location.

<Snippet file="api-reference/note-bse-ford.mdx" />

## Permission

`control_charge`

## Request

<Info>
  In order to set a schedule, you must use a location from the [`GET Charge Schedule by Location`](/api-reference/ford/get-charge-schedule-by-location) endpoint.
  If the location you want to manage is not in the response, the vehicle owner has not charged at that location within the last 90 days and it has been
  removed from their app's saved charging location list.
</Info>

**Path**

<Snippet file="api-reference/path-bse.mdx" />

**Query**

<ParamField query="longitude" type="number" required>
  The longitude of a charging location from [`GET Charge Schedule by Location`](/api-reference/ford/get-charge-schedule-by-location)
</ParamField>

<ParamField query="latitude" type="number" required>
  The latitude of a charging location from [`GET Charge Schedule by Location`](/api-reference/ford/get-charge-schedule-by-location)
</ParamField>

**Body**

<ParamField body="chargingLocation" type="object" required>
  <Expandable defaultOpen="true" title="chargingLocation">
    <ParamField body="chargeLimit" type="number" required>
      The maximum charge limit for the vehicle at the location as a percent between `0.5` and `1`.
    </ParamField>

    <ParamField body="chargingWindows" type="object" required>
      The weekday and weekend charging schedules for the vehicle at the location.

      <Expandable defaultOpen="true">
        <ParamField body="weekday" type="[object]" required>
          The charging schedule for the vehicle on weekdays (Monday - Friday).

          <Expandable defaultOpen="true">
            <ParamField body="start" type="string" required>
              The exact hour a vehicle should start charging in HH:00 e.g. 17:00.
            </ParamField>

            <ParamField body="end" type="string" required>
              The exact hour a vehicle should stop charging in HH:00 e.g. 21:00.
            </ParamField>
          </Expandable>
        </ParamField>

        <ParamField body="weekend" type="[object]" required>
          The charging schedule for the vehicle on weekends (Saturday - Sunday).

          <Expandable defaultOpen="true">
            <ParamField body="start" type="string" required>
              The exact hour a vehicle should start charging in HH:00 e.g. 17:00.
            </ParamField>

            <ParamField body="end" type="string" required>
              The exact hour a vehicle should stop charging in HH:00 e.g. 21:00.
            </ParamField>
          </Expandable>
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<RequestExample>
  ```curl cURL
  curl "https://api.smartcar.com/v2.0/vehicles/{id}/{make}/charge/schedule_by_location?longitude=2.3522&latitude=48.8566" \
      -H "Authorization: Bearer {token}" \
      -X "PUT" \
      -H "Content-Type: application/json" \
      -d '{chargingLocation:{"chargeLimit": 0.9, "chargingWindows": {"weekday": [{"start": "09:00", "end": "17:00"}], "weekend": [{"start": "09:00", "end": "17:00"}]}}}'
  ```

  ```python Python
  setChargeScheduleByLocation = vehicle.request(
          "PUT", 
          "{make}/charge/schedule_by_location?longitude=2.3522&latitude=48.8566", 
          {
            "chargingLocation" : {   
                "chargeLimit": 0.9, 
                "chargingWindows": {
                    "weekday": [
                        {   
                            "start": "09:00", 
                            "end": "10:00"
                        }
                    ], 
                    "weekend": [
                        {   
                            "start": "09:00", 
                            "end": "10:00"
                        }
                    ]
                }
            }
        }
      )
  ```

  ```js Node
  const setChargeScheduleByLocation = vehicle.request(
        "PUT", 
        "{make}/charge/schedule_by_location?longitude=2.3522&latitude=48.8566", 
        {
          "chargingLocation" : {   
              "chargeLimit": 0.9, 
              "chargingWindows": {
                  "weekday": [
                      {   
                          "start": "09:00", 
                          "end": "10:00"
                      }
                  ], 
                  "weekend": [
                      {   
                          "start": "09:00", 
                          "end": "10:00"
                      }
                  ]
              }
          }
        }
      );
  ```

  ```java Java
  JsonArrayBuilder weekday = Json.createArrayBuilder().add(
      Json.createObjectBuilder().add("start", "05:00").add("end", "07:00"));

  JsonArrayBuilder weekend = Json.createArrayBuilder().add(
      Json.createObjectBuilder().add("start", "06:00").add("end", "07:00"));

  JsonObject chargingWindows = Json.createObjectBuilder()
                                      .add("weekday", weekday)
                                      .add("weekend", weekend)
                                      .build();

  JsonObject chargingLocation = Json.createObjectBuilder()
                                      .add("chargeLimit", 1.0)
                                      .add("chargingWindows", chargingWindows)
                                      .build();

  SmartcarVehicleRequest request =
      new SmartcarVehicleRequest.Builder()
          .method("PUT")
          .path("ford/charge/schedule_by_location")
          .addQueryParameter("latitude", "37.749008")
          .addQueryParameter("longitude", "-122.46981")
          .addBodyParameter("chargingLocation", chargingLocation)
          .build();

  VehicleResponse chargeSched = vehicle.request(request);
  ```

  ```ruby Ruby
  setChargeScheduleByLocation = vehicle.request(
        "PUT", 
        "{make}/charge/schedule_by_location?longitude=2.3522&latitude=48.8566", 
        {
          "chargingLocation" : {   
              "chargeLimit": 0.9, 
              "chargingWindows": {
                  "weekday": [
                      {   
                          "start": "09:00", 
                          "end": "10:00"
                      }
                  ], 
                  "weekend": [
                      {   
                          "start": "09:00", 
                          "end": "10:00"
                      }
                  ]
              }
          }
        }
      )
  ```
</RequestExample>

## Response

<ResponseField name="message" type="string">
  If the request is successful, Smartcar will return a message.
</ResponseField>

<ResponseField name="status" type="string">
  If the request is successful, Smartcar will return `success`.
</ResponseField>

<ResponseExample>
  ```json Example Response 
  {
    "message": "Successfully sent request to vehicle",
    "status": "success"
  }
  ```
</ResponseExample>

## Example Request Bodies

<AccordionGroup>
  <Accordion title="Set a schedule for Weekdays and Weekends">
    ```json
    {
      "chargingLocation" : {   
          "chargeLimit": 0.9, 
          "chargingWindows": {
              "weekday": [
                  {   
                      "start": "17:00", 
                      "end": "06:00"
                  }
              ], 
              "weekend": [
                  {   
                      "start": "16:00", 
                      "end": "07:00"
                  }
              ]
          }
      }
    }
    ```
  </Accordion>

  <Accordion title="Set a schedule for only Weekdays">
    ```json
    {
      "chargingLocation" : {   
          "chargeLimit": 0.9, 
          "chargingWindows": {
              "weekday": [
                  {   
                      "start": "17:00", 
                      "end": "06:00"
                  }
              ], 
              "weekend": []
          }
      }
    }
    ```
  </Accordion>

  <Accordion title="Set a schedule for only Weekends">
    ```json
    {
        "chargingLocation" : {   
            "chargeLimit": 0.9, 
            "chargingWindows": {
                "weekday": [], 
                "weekend": [
                    {   
                        "start": "16:00", 
                        "end": "07:00"
                    }
                ]
            }
        }
    }
    ```
  </Accordion>

  <Accordion title="Clear schedules">
    ```json
    {
        "chargingLocation" : {   
            "chargeLimit": 0.9, 
            "chargingWindows": {
                "weekday": [], 
                "weekend": []
            }
        }
    }
    ```
  </Accordion>
</AccordionGroup>


# Oil Life

GET /vehicles/{id}/engine/oil
Returns the remaining life span of a vehicle’s engine oil.

## Permission

`read_engine_oil`

## Request

**Path**

<Snippet file="api-reference/path-vehicle-id.mdx" />

<RequestExample>
  <Snippet file="api-reference/core-sdk-methods/get-engine-oil-life.mdx" />
</RequestExample>

## Response

<ResponseField name="lifeRemaining" type="number">
  The engine oil’s remaining life span based on the current quality of the oil as a percentage.
  `1` indicates the oil was changed recently and `0` indicates the oil should be changed immediately.
  It is not a representation of how much oil is left in the vehicle.
</ResponseField>

<ResponseExample>
  ```json Example Response 
  {
    "lifeRemaining": 0.35
  }
  ```
</ResponseExample>


# Fuel Tank

GET /vehicles/{id}/fuel
Returns the status of the fuel remaining in the vehicle’s fuel tank.

## Permission

`read_fuel`

<Note>
  This endpoint may return `null` values for vehicles sold in Europe. Please see the [Notes](/api-reference/get-fuel-tank#notes) section for details.
</Note>

## Request

**Path**

<Snippet file="api-reference/path-vehicle-id.mdx" />

<RequestExample>
  <Snippet file="api-reference/core-sdk-methods/get-fuel-tank.mdx" />
</RequestExample>

## Response

<ResponseField name="percentRemaining" type="number | null">
  The remaining level of fuel in the tank as a percentage.
</ResponseField>

<ResponseField name="amountRemaining" type="number | null" default="liters">
  The amount of fuel in the tank.
</ResponseField>

<ResponseField name="range" type="number | null" default="kilometers">
  The estimated remaining distance the car can travel.
</ResponseField>

<ResponseExample>
  ```json Example Response 
  {
    "amountRemaining": 53.2,
    "percentRemaining": 0.3,
    "range": 40.5
  }
  ```
</ResponseExample>

## Notes

The table below indicates values Smartcar attempts to retrieve from vehicles sold in Europe.

|                                      | `range` | `percentRemaining` | `amountRemaining` |
| ------------------------------------ | ------- | ------------------ | ----------------- |
| Audi                                 | ✅       | ✅                  |                   |
| BMW, MINI                            | ✅       | ✅                  | ✅                 |
| Citroen, DS, Opel, Peugeot, Vauxhall | ✅       |                    | ✅                 |
| Ford                                 | ✅       | ✅                  |                   |
| Hyundai                              | ✅       |                    | ✅                 |
| Jaguar, Land Rover                   | ✅       | ✅                  |                   |
| Kia                                  | ✅       | ✅                  |                   |
| Mazda                                | ✅       | ✅                  |                   |
| Mercedes                             | ✅       | ✅                  |                   |
| Renault                              | ✅       |                    | ✅                 |
| Skoda, Volkswagen                    | ✅       | ✅                  |                   |
| Volvo                                | ✅       | ✅                  | ✅                 |


# Location

GET /vehicles/{id}/location
Returns the vehicle's last known location.

## Permission

`read_location`

## Request

**Path**

<Snippet file="api-reference/path-vehicle-id.mdx" />

<RequestExample>
  <Snippet file="api-reference/core-sdk-methods/get-location.mdx" />
</RequestExample>

## Response

<ResponseField name="latitude" type="number">
  The latitude in degrees.
</ResponseField>

<ResponseField name="longitude" type="number">
  The longitude in degrees.
</ResponseField>

<ResponseExample>
  ```json Example Response
  {
    "latitude": 37.4292,
    "longitude": 122.1381
  }
  ```
</ResponseExample>


# Lock Status

GET /vehicles/{id}/security
Returns the lock status for a vehicle and the open status of its doors, windows, storage units, sunroof and charging port where available.

## Permission

`read_security`

## Request

**Path**

<Snippet file="api-reference/path-vehicle-id.mdx" />

<RequestExample>
  <Snippet file="api-reference/core-sdk-methods/get-lock-status.mdx" />
</RequestExample>

## Response

<ResponseField name="isLocked" type="bool">
  Indicates the current lock status of the vehicle as reported by the OEM.
</ResponseField>

<ResponseField name="doors" type="[object]">
  An array of the open status of the vehicle's doors.

  <Expandable title="doors">
    <ResponseField name="type" type="string">
      The location of the door.
    </ResponseField>

    <ResponseField name="status" type="string">
      Indicates the current state of the vehicle's door.
      `UNKNOWN` indicates the vehicle supports this status, but did not provide a valid status for the request
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="windows" type="[object]">
  An array of the open status of the vehicle's windows.

  <Expandable title="windows">
    <ResponseField name="type" type="string">
      The location of the window.
    </ResponseField>

    <ResponseField name="status" type="string">
      Indicates the current state of the vehicle's window.
      `UNKNOWN` indicates the vehicle supports this status, but did not provide a valid status for the request
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="sunroof" type="[object]">
  An array of the open status of the vehicle's sunroofs.

  <Expandable title="sunroofs">
    <ResponseField name="type" type="string">
      The location of the sunroof.
    </ResponseField>

    <ResponseField name="status" type="string">
      Indicates the current state of the vehicle's sunroof.
      `UNKNOWN` indicates the vehicle supports this status, but did not provide a valid status for the request
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="storage" type="[object]">
  An array of the open status of the vehicle's storages.
  For internal combustion and plug-in hybrid vehicles front refers to the engine hood.
  For battery vehicles, this will be the front trunk.

  <Expandable title="storage">
    <ResponseField name="type" type="string">
      The location of the sunroof.
    </ResponseField>

    <ResponseField name="status" type="string">
      Indicates the current state of the vehicle's storage.
      `UNKNOWN` indicates the vehicle supports this status, but did not provide a valid status for the request
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="chargingPort" type="[object]">
  An array of the open status of the vehicle's charging port.

  <Expandable title="storage">
    <ResponseField name="type" type="string">
      The location of the charging port.
    </ResponseField>

    <ResponseField name="status" type="string">
      Indicates the current state of the vehicle's charging port.
      `UNKNOWN` indicates the vehicle supports this status, but did not provide a valid status for the request
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json Example Response 
  {
  	"isLocked" : false,
  	"doors" : [
  		{"type": "frontLeft" , "status" : "CLOSED"},
  		{"type": "frontRight" , "status" : "OPEN"},
  		{"type": "backRight" , "status" : "CLOSED"},
  		{"type": "backLeft" , "status" : "CLOSED"}
  	],
  	"windows" : [
  		{"type": "frontLeft" , "status" : "CLOSED"},
  		{"type": "frontRight" , "status" : "CLOSED"},
  		{"type": "backRight" , "status" : "UNKNOWN"},
  		{"type": "backLeft" , "status" : "CLOSED"}
  	],
  	"sunroof" : [
  		{"type": "sunroof" , "status" : "CLOSED"}
  	], 	
  	"storage" : [
  		{"type": "rear" , "status" : "UNKNOWN"},
  		{"type": "front" , "status" : "CLOSED"}
  	],
  	"chargingPort" : [ 
  		{"type" : "chargingPort", "status" : "CLOSED" } 
  	]
  }
  ```
</ResponseExample>

# Notes

*   The open status array(s) will be empty if a vehicle has partial support.
*   The request will error if `lockStatus` can not be retrieved from the vehicle or the brand is not supported.


# Odometer

GET /vehicles/{id}/odometer
Returns the vehicle’s last known odometer reading.

## Permission

`read_odometer`

## Request

**Path**

<Snippet file="api-reference/path-vehicle-id.mdx" />

<RequestExample>
  <Snippet file="api-reference/core-sdk-methods/get-odometer.mdx" />
</RequestExample>

## Response

<ResponseField name="distance" type="number" default="kilometers">
  The current odometer of the vehicle.
</ResponseField>

<ResponseExample>
  ```json Example Response 
  {
    "distance": 104.32
  }
  ```
</ResponseExample>


# Service History

GET /vehicles/{id}/service/history
Retrieve service records tracked by the vehicle's dealer or manually added by the vehicle owner. Currently supporting Ford, Lincoln, Toyota, Lexus, Mazda and Volkswagen (US)

## Permission

`read_service_history`

<RequestExample>
  ```curl cURL
  curl "https://api.smartcar.com/v2.0/vehicles/{id}/service/history \
  -H "Authorization: Bearer {token}" \
  -X "GET"
  ```

  ```python Python
  service = vehicle.request(
        "GET", 
        "service/history"
  )
  ```

  ```js Node
  const service = await vehicle.request(
        "GET", 
        "service/history"
  );
  ```

  ```java Java
  SmartcarVehicleRequest request = new SmartcarVehicleRequest.Builder()
        .method("GET")
        .path("service/history")
        .build();
  VehicleResponse service =vehicle.request(request);
  ```

  ```ruby Ruby
  Service = vehicle.request(
        "GET", 
        "service/history"
  )
  ```
</RequestExample>

## Request

**Path**

<Snippet file="api-reference/path-vehicle-id.mdx" />

## Response

<ResponseField name="serviceID" type="string | null">
  A unique identifier of the service record.
</ResponseField>

<ResponseField name="serviceDate" type="timestamp | null">
  The date and time the vehicle was serviced
</ResponseField>

<ResponseField name="odometerDistance" type="string | null">
  the odometer of the vehicle at time of service in kilometers.
</ResponseField>

<Expandable title="service tasks" description="An overview of specific tasks completed in the service event.">
  <ResponseField name="taskID" type="string | null">
    The unique identifier of the tasks completed as part of the service event.
  </ResponseField>

  <ResponseField name="taskDescription" type="string | null">
    Tasks completed as part of the service event. Note that not all makes provide service tasks.
  </ResponseField>
</Expandable>

Additional service details.

<Expandable title="service details">
  <ResponseField name="type" type="string | null">
    Indicates if the service event was completed by a dealership or manually entered by the vehicle owner.
  </ResponseField>
</Expandable>

An overview of service costs.

<Expandable title="service cost">
  <ResponseField name="totalCost" type="string | null">
    The total cost of the service event. Note that not all makes provide service cost.
  </ResponseField>

  <ResponseField name="currency" type="string | null">
    Identifies the currency used for service cost.
  </ResponseField>
</Expandable>

<ResponseExample>
  ```json Example Response 
  {
        "serviceId": null,
        "odometerDistance": 46047.22,
        "serviceDate": "2023-06-28T22:21:41.583Z",
        "serviceTasks": [
              {
              "taskId": "3262",
              "taskDescription": "Service Task 0"
              },
              {
              "taskId": "3041",
              "taskDescription": null
              },
              {
              "taskId": null,
              "taskDescription": null
              }
        ],
        "serviceDetails": [
              {
              "type": "Service Details Type 0",
              "value": "Service Details Value 0"
              },
              {
              "type": "Service Details Type 1",
              "value": null
              }
        ],
        "serviceCost": {
              "totalCost": null,
              "currency": null
        }
  }
  ```
</ResponseExample>


# System Status (Early Access)

GET /vehicles/{id}/diagnostics/system_status
Provides a list of vehicle systems and their current health status. Currently supporting FCA and GM brands including RAM, Jeep, Chrysler, Dodge, Fiat, Alpha Romeo, Buick, Cadillac, Chevrolet and GMC. See [Diagnostic Systems](/docs/help/diagnostic-systems) for a complete list of Smartcar System IDs.

## Permission

`read_diagnostics`

<RequestExample>
  ```curl cURL
  curl "https://api.smartcar.com/v2.0/vehicles/{id}/diagnostics/system_status" \\
      -H "Authorization: Bearer {token}" \\
      -X "GET"
  ```

  ```python Python
  diagnostic_system_status = vehicle.diagnostic_system_status()
  ```

  ```js Node
  const diagnosticSystemStatus = await vehicle.diagnosticSystemStatus();
  ```

  ```java Java
  VehicleDiagnosticSystemStatus diagnosticSystemStatus = vehicle.diagnosticSystemStatus();
  ```

  ```ruby Ruby
  diagnostic_system_status = vehicle.diagnostic_system_status
  ```
</RequestExample>

## Request

**Path**

<Snippet file="api-reference/path-vehicle-id.mdx" />

## Response

<ResponseField name="systems" type="array">
  An overview of systems reported by the vehicle.
</ResponseField>

<ResponseField name="systemID" type="string">
  The unique identifier of a system reported by the vehicle.
</ResponseField>

<ResponseField name="status" type="string">
  The status of a vehicle, expected as "OK" or "ALERT".
</ResponseField>

<ResponseField name="description" type="string | null">
  A plain-text description of the status, if available.
</ResponseField>

<ResponseExample>
  ```json Example Response 
  {
        "systems":
            {
                // System ID from Smartcar unified system definition list
                "systemId": "SYSTEM_TPMS",
            
                // "OK" or "ALERT"
                "status": "ALERT",
                
                // Optional, human-readable text field to provide additional context for the alert
                "description": "Left rear tire sensor battery low"
            },
            
            {
                "systemId": "SYSTEM_AIRBAG",
                "status": "OK",
                "description": null
            },
            
            {
                "systemId": "SYSTEM_MIL",
                "status": "OK",
                "description": null
            },
            ...
  }
  ```
</ResponseExample>


# Tire Pressure

GET /vehicles/{id}/tires/pressure
Returns the air pressure of each of the vehicle’s tires.

## Permission

`read_tires`

## Request

**Path**

<Snippet file="api-reference/path-vehicle-id.mdx" />

<RequestExample>
  <Snippet file="api-reference/core-sdk-methods/get-tire-pressure.mdx" />
</RequestExample>

## Response

<ResponseField name="frontLeft" type="number" default="kilopascals">
  The current air pressure of the front left tire.
</ResponseField>

<ResponseField name="frontRight" type="number" default="kilopascals">
  The current air pressure of the front right tire.
</ResponseField>

<ResponseField name="backLeft" type="number" default="kilopascals">
  The current air pressure of the back left tire.
</ResponseField>

<ResponseField name="backRight" type="number" default="kilopascals">
  The current air pressure of the back right tire.
</ResponseField>

<ResponseExample>
  ```json Example Response 
  {
      "backLeft": 219.3,
      "backRight": 219.3,
      "frontLeft": 219.3,
      "frontRight": 219.3
  }
  ```
</ResponseExample>


# Vehicle Attributes

GET /vehicles/{id}
Returns a single vehicle object, containing identifying information.

## Permission

`read_vehicle_info`

## Request

**Path**

<Snippet file="api-reference/path-vehicle-id.mdx" />

<RequestExample>
  <Snippet file="api-reference/core-sdk-methods/get-vehicle-info.mdx" />
</RequestExample>

## Response

<ResponseField name="id" type="string">
  The ID for the vehicle.
</ResponseField>

<ResponseField name="make" type="string">
  The manufacturer of the vehicle.
</ResponseField>

<ResponseField name="model" type="string">
  The model of the vehicle.
</ResponseField>

<ResponseField name="year" type="integer">
  The model year.
</ResponseField>

<ResponseExample>
  ```json Example Response 
  {
      "id": "36ab27d0-fd9d-4455-823a-ce30af709ffc",
      "make": "TESLA",
      "model": "Model S",
      "year": "2014"
  }
  ```
</ResponseExample>


# VIN

GET /vehicles/{id}/vin
Returns the vehicle’s manufacturer identifier.

## Permission

`read_vin`

## Request

**Path**

<Snippet file="api-reference/path-vehicle-id.mdx" />

<RequestExample>
  <Snippet file="api-reference/core-sdk-methods/get-vin.mdx" />
</RequestExample>

## Response

<ResponseField name="vin" type="string">
  The manufacturer unique identifier.
</ResponseField>

<ResponseExample>
  ```json Example Response 
  {
    "vin": "5YJSA1CN5DFP00101"
  }
  ```
</ResponseExample>


# Charge Completion Time

GET /vehicles/{id}/{make}/charge/completion
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.

<Note>
  This endpoint is currently available for `cadillac` and `chevrolet`.
</Note>

## Permission

`read_charge`

## Request

<ParamField path="id" type="string" required>
  `vehicle_id` of the vehicle you are making the request to.
</ParamField>

<ParamField path="make" type="string" required>
  The make to pass in the URL.
</ParamField>

<RequestExample>
  <Snippet file="api-reference/bse/get-charge-completion-time.mdx" />
</RequestExample>

## Response

<ResponseField name="time" type="string">
  An ISO8601 formatted datetime (`YYYY-MM-DDTHH:mm:ss.SSSZ`) for the time at which the vehicle expects to complete this charging session.
</ResponseField>

<ResponseExample>
  ```json Example Response
  {
    "time": "2022-01-13T22:52:55.358Z"
  }
  ```
</ResponseExample>


# Voltage

GET /vehicles/{id}/{make}/charge/voltmeter
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.

<Note>
  This endpoint is currently available for `cadillac` and `chevrolet`.
</Note>

## Permission

`read_charge`

## Request

<Snippet file="api-reference/path-bse.mdx" />

<RequestExample>
  <Snippet file="api-reference/bse/get-charge-voltmeter.mdx" />
</RequestExample>

## Response

<ResponseField name="voltage" type="number">
  The potential difference measured by the vehicle in volts (V).
</ResponseField>

<ResponseExample>
  ```json Example Response
  {
    "voltage": 240
  }
  ```
</ResponseExample>


# Headers



Smartcar uses the following headers for requests and responses.

## Request

<ParamField header="SC-Unit-System" default="metric">
  Smartcar supports both `metric` and `imperial` unit systems of measurement.
</ParamField>

<RequestExample>
  ```curl Request Headers
  SC-Unit-System: metric
  ```
</RequestExample>

## Response

<ResponseField name="SC-Data-Age">
  Indicates the timestamp (ISO-8601 format) of when the returned data was recorded by the vehicle.
</ResponseField>

<ResponseField name="SC-Unit-System">
  Indicates whether the unit system used in the returned data is `imperial` or `metric`.
</ResponseField>

<ResponseField name="SC-Request-Id">
  Each response from Smartcar’s API has a unique request identifier. If you need to contact us about a specific request, providing the request identifier will ensure the fastest possible resolution.
</ResponseField>

<ResponseExample>
  ```curl Response Headers
  SC-Data-Age: 2018-06-20T01:33:37.078Z
  SC-Unit-System: metric
  SC-Request-Id: 26c14915-0c26-43c5-8e42-9edfc2a66a0f
  ```
</ResponseExample>


# Smartcar API Reference



Welcome to Smartcar! Here you’ll find everything you need to get started with Smartcar.
If you have any questions, please email us at [support@smartcar.com](mailto:support@smartcar.com)!

Smartcar makes it easy to read vehicle data and send commands to vehicles of any brand using HTTP
requests. All requests made to our API require an access token. Our API uses the OAuth2 authorization framework
and provides a granular permissioning system that authorizes API endpoints based on user preferences.
This allows applications to easily authorize and interact with vehicles through
the Smartcar API.

<Card title="Starter app" icon="github-alt" href="https://github.com/smartcar/starter-app-react-node" horizontal="true">
  Easily connect a vehicle and make API requests using our starter app.
</Card>

<Card title="Postman" icon="rocket" href="https://www.postman.com/smartcar/smartcar-api/collection/fqmwehs/smartcar-api" horizontal="true">
  Get a feel for the API using our Postman collection.
</Card>


# Makes

Valid values for the `make` parameter

#### United States

|            |             |            |                 |           |              |   |
| ---------- | ----------- | ---------- | --------------- | --------- | ------------ | - |
| `ACURA`    | `CHEVROLET` | `HYUNDAI`  | `LAND_ROVER`    | `MINI`    | `SUBARU`     |   |
| `AUDI`     | `CHRYSLER`  | `INFINITI` | `LEXUS`         | `NISSAN`  | `TESLA`      |   |
| `BMW`      | `DODGE`     | `JAGUAR`   | `LINCOLN`       | `PORSCHE` | `TOYOTA`     |   |
| `BUICK`    | `FORD`      | `JEEP`     | `MAZDA`         | `RAM`     | `VOLKSWAGEN` |   |
| `CADILLAC` | `GMC`       | `KIA`      | `MERCEDES_BENZ` | `RIVIAN`  | `VOLVO`      |   |

#### Europe

|              |           |                 |           |              |
| ------------ | --------- | --------------- | --------- | ------------ |
| `AUDI`       | `DS`      | `KIA`           | `NISSAN`  | `SKODA`      |
| `ALFA_ROMEO` | `FIAT`    | `LAND_ROVER`    | `OPEL`    | `TESLA`      |
| `BMW`        | `FORD`    | `MAZDA`         | `PEUGEOT` | `VAUXHALL`   |
| `CITROEN`    | `JAGUAR`  | `MERCEDES_BENZ` | `PORSCHE` | `VOLKSWAGEN` |
| `CUPRA`      | `HYUNDAI` | `MINI`          | `RENAULT` | `VOLVO`      |

See [this](https://smartcar.com/global/) page for supported countries.

#### Canada

|            |             |              |           |          |
| ---------- | ----------- | ------------ | --------- | -------- |
| `ACURA`    | `CHEVROLET` | `HYUNDAI`    | `LEXUS`   | `TOYOTA` |
| `AUDI`     | `CHRYSLER`  | `JAGUAR`     | `LINCOLN` | `VOLVO`  |
| `BMW`      | `DODGE`     | `JEEP`       | `MINI`    |          |
| `BUICK`    | `FORD`      | `KIA`        | `RAM`     |          |
| `CADILLAC` | `GMC`       | `LAND_ROVER` | `TESLA`   |          |


# Vehicle Connections

DELETE https://management.smartcar.com/v2.0/management/connections
Deletes all vehicle connections associated with a Smartcar user ID or a specific vehicle.

## Request

**Header**

<ParamField header="Authorization" type="string" initialValue="Basic base64({application_management_token})" required>
  In the format `Basic base64({application_management_token})`. You can find your `application_management_token` under
  your Application Configuration in the Smartcar Dashboard.
</ParamField>

**Query**

<ParamField query="user_id | vehicle_id" type="string">
  Delete a connection for the given `vehicle_id` or all vehicle connections
  for the given `user_id`.
</ParamField>

<RequestExample>
  <Snippet file="api-reference/core-sdk-methods/delete-vehicle-connections.mdx" />
</RequestExample>

## Response

<ResponseField name="connections" type="array">
  An array of connections

  <Expandable title="connections">
    <ResponseField name="userId" type="string">
      ID of the user that authorized the deleted connection (UUID v4)
    </ResponseField>

    <ResponseField name="vehicleId" type="string">
      ID of the vehicle disconnected (UUID v4)
    </ResponseField>
  </Expandable>
</ResponseField>


# Vehicle Connections

GET https://management.smartcar.com/v2.0/management/connections
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.

## Request

**Header**

<ParamField header="Authorization" type="string" initialValue="Basic base64({application_management_token})" required>
  In the format `Basic base64(default:{application_management_token})`. You can find your `application_management_token` under
  your Application Configuration in the Smartcar Dashboard.
</ParamField>

**Query**

<ParamField query="limit" type="integer" default="10">
  Number of connections to return per page. `Max: 100`
</ParamField>

<ParamField query="cursor" type="string">
  Used for accessing pages other than the first page. Each page returned has a cursor value
  that can be passed here to fetch the “next” page.
</ParamField>

<ParamField query="user_id" type="string">
  Filter for connections created by the provider user ID.
</ParamField>

<ParamField query="vehicle_id" type="string">
  Filter for connections to the provided vehicle ID.
</ParamField>

<RequestExample>
  <Snippet file="api-reference/core-sdk-methods/get-vehicle-connections.mdx" />
</RequestExample>

## Response

<ResponseField name="connections" type="array">
  An array of connections

  <Expandable title="connections">
    <ResponseField name="userId" type="string">
      ID of the user that authorized this connection (UUID v4).
    </ResponseField>

    <ResponseField name="vehicleId" type="string">
      ID of the vehicle connected (UUID v4).
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      Time at which the connection was created in UTC.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="paging" type="Object">
  Metadata about the current query

  <Expandable>
    <ResponseField name="cursor" type="string">
      The cursor parameter that should be used to fetch the next page of results.
      This field will be null if there are no more pages.
    </ResponseField>
  </Expandable>
</ResponseField>


# Charge Schedule

GET /vehicles/{id}/{make}/charge/schedule
Returns the charging schedule of a vehicle. The response contains the start time and departure time of the vehicle's charging schedule.

<Note>
  This endpoint is currently available for `nissan` EVs on the `MyNISSAN` platform.
</Note>

## Permission

`read_charge`

## Request

**Path**

<Snippet file="api-reference/path-bse.mdx" />

<RequestExample>
  <Snippet file="api-reference/bse/get-charge-schedule.mdx" />
</RequestExample>

## Response

<ResponseField name="chargeSchedules" type="array">
  An array of charge schedules. Maximum of 3 schedules, empty if no schedules are set.

  <Expandable>
    <ResponseField name="start" type="array">
      HH:mm in UTC for a schedule start time.
    </ResponseField>

    <ResponseField name="end" type="array">
      HH:mm in UTC for a schedule end time.
    </ResponseField>

    <ResponseField name="days" type="array">
      An array of days the schedule applies to.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json Example Response 
  {
    "chargeSchedules": [
      {
        "end": "2020-01-01T02:00:00.000Z",
        "start": "2020-01-01T01:00:00.000Z",
        "days": [
          "MONDAY",
          "WEDNESDAY",
          "FRIDAY"
        ]
      }
    ]
  }
  ```
</ResponseExample>


# Charge Schedule

PUT /vehicles/{id}/{make}/charge/schedule
Sets the charging schedule for a vehicle.

<Note>
  This endpoint is currently available for `nissan` EVs on the `MyNISSAN` platform
</Note>

## Permission

`control_charge`

## Request

**Path**

<Snippet file="api-reference/path-bse.mdx" />

**Body**

<ParamField body="chargeSchedules" type="array" required>
  An array of charge schedules. A maximum of 3 schedules can be set.

  <Expandable defaultOpen="true">
    <ParamField body="start" type="string" required>
      HH:mm in UTC for a schedule start time.
    </ParamField>

    <ParamField body="end" type="string" required>
      HH:mm in UTC for a schedule start time.
    </ParamField>

    <ParamField body="days" type="[days]" required>
      An array of days for the schedule to be applied.
      Options: `MONDAY` `TUESDAY` `WEDNESDAY` `THURSDAY` `FRIDAY` `SATURDAY` `SUNDAY`
    </ParamField>
  </Expandable>
</ParamField>

<RequestExample>
  ```curl cURL
  curl "https://api.smartcar.com/v2.0/vehicles/{id}/{make}/charge/schedule" \
  -H "Authorization: Bearer {token}" \
  -X "PUT" \
  -H "Content-Type: application/json" \
  -d '{
      "chargeSchedules": [
          {
              "start": "08:00",
              "end": "12:00",
              "days": ["MONDAY", "WEDNESDAY", "FRIDAY"]
          },
          {
              "start": "14:00",
              "end": "18:00",
              "days": ["TUESDAY", "THURSDAY", "SATURDAY"]
          }
      ]
  }'
  ```

  ```python Python
  charge_schedule = vehicle.request("PUT", "{make}/charge/schedule", {
      "chargeSchedules": [
          {
              "start": "08:00",
              "end": "12:00",
              "days": ["MONDAY", "WEDNESDAY", "FRIDAY"]
          },
          {
              "start": "14:00",
              "end": "18:00",
              "days": ["TUESDAY", "THURSDAY", "SATURDAY"]
          }
      ]
  })
  ```

  ```js Node
  const chargeSchedule = vehicle.request("PUT", "{make}/charge/schedule", {
      "chargeSchedules": [
          {
              "start": "08:00",
              "end": "12:00",
              "days": ["MONDAY", "WEDNESDAY", "FRIDAY"]
          },
          {
              "start": "14:00",
              "end": "18:00",
              "days": ["TUESDAY", "THURSDAY", "SATURDAY"]
          }
      ]
  });
  ```

  ```java Java
  SmartcarVehicleRequest request = new SmartcarVehicleRequest.Builder()
      .method("PUT")
      .path("{make}/charge/schedule")
      .addBodyParameter("chargeSchedules", [
          {
              "start": "08:00",
              "end": "12:00",
              "days": ["MONDAY", "WEDNESDAY", "FRIDAY"]
          },
          {
              "start": "14:00",
              "end": "18:00",
              "days": ["TUESDAY", "THURSDAY", "SATURDAY"]
          }
      ])
      .build();
  ChargeSchedule chargeSchedule = vehicle.request(request);
  ```

  ```ruby Ruby
  charge_schedule = vehicle.request("PUT", "{make}/charge/schedule", {
      "chargeSchedules": [
          {
              "start": "08:00",
              "end": "12:00",
              "days": ["MONDAY", "WEDNESDAY", "FRIDAY"]
          },
          {
              "start": "14:00",
              "end": "18:00",
              "days": ["TUESDAY", "THURSDAY", "SATURDAY"]
          }
      ]
  })
  ```
</RequestExample>

## Response

<ResponseField name="message" type="string">
  If the request is successful, Smartcar will return a message.
</ResponseField>

<ResponseField name="status" type="string">
  If the request is successful, Smartcar will return `success`.
</ResponseField>

<ResponseExample>
  ```json Example Response 
  {
    "message": "Successfully sent request to vehicle",
    "status": "success"
  }
  ```
</ResponseExample>


# Permissions

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

A permission is *optional* by default. This means that if you were to pass `read_fuel` in your Connect URL and the user tried to connect a Tesla, the permission would not show up as Tesla does not support fuel.

It can be made required by adding the `required:` prefix to the permission name, e.g. `required:read_fuel`. In this case, if a user were to try and connect a Tesla they'd see a `No Compatible Vehicles` Connect error as your
application is requiring vehicles to have the `read_fuel` permission.

<Info>
  In Europe, permissions can be conditional meaning that even if the `required:` prefix is provided, a vehicle can make it through Connect as we cannot be sure of a vehicle's capability until you attempt to make an API request.

  In this case you'll receive a [VEHICLE\_NOT\_CAPABLE](/errors/api-errors/compatibility-errors#vehicle-not-capable) API error. To read more about capabilities please see [Compatibility by VIN](/api-reference/compatibility/by-vin).
</Info>

## Read

Permissions prefixed with `read_` allow your application to get data from a vehicle as part of `GET` requests.

|                              |                                                                                                                       |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `read_alerts`                | Read alerts from the vehicle                                                                                          |
| `read_battery`               | Read an EV's high voltage battery data                                                                                |
| `read_charge`                | Read charging data                                                                                                    |
| `read_charge_locations`      | Access previous charging locations and their associated charging configurations                                       |
| `read_charge_records`        | Read charge records and associated billing information                                                                |
| `read_charge_events`         | Receive notifications for events associate with charging                                                              |
| `read_climate`               | Read the status and settings of the vehicle's climate control system                                                  |
| `read_compass`               | Read the compass direction the vehicle is facing                                                                      |
| `read_engine_oil`            | Read vehicle engine oil health                                                                                        |
| `read_extended_vehicle_info` | Read vehicle configuration information from a vehicle                                                                 |
| `read_fuel`                  | Read fuel tank level                                                                                                  |
| `read_location`              | Access the vehicles location                                                                                          |
| `read_odometer`              | Retrieve total distance traveled                                                                                      |
| `read_security`              | Read the lock status of doors, windows, charging port, etc.                                                           |
| `read_speedometer`           | Read a vehicle's speed                                                                                                |
| `read_thermometer`           | Read temperatures from inside and outside the vehicle                                                                 |
| `read_tires`                 | Read a vehicle's tire status                                                                                          |
| `read_user_profile`          | Read the information associated with a users connected services account profile such as their email and phone number. |
| `read_vehicle_info`          | Know make, model, and year                                                                                            |
| `read_vin`                   | Read VIN                                                                                                              |

## Control

Permissions prefixed with `control_` allow your application to issue commands or apply settings to a vehicle as part of `POST` or `PUT` requests.

|                      |                                                                     |
| -------------------- | ------------------------------------------------------------------- |
| `control_charge`     | Control a vehicle's charge state                                    |
| `control_climate`    | Set the status and settings of the vehicle's climate control system |
| `control_navigation` | Send commands to the vehicle's navigation system                    |
| `control_security`   | Lock or unlock the vehicle                                          |
| `control_pin`        | Modify a PIN and enable the PIN to Drive feature for the vehicle.   |
| `control_trunk`      | Open a vehicle's trunk or frunk                                     |


# Send Destination

POST /vehicles/{id}/navigation/destination
Send destination coordinates to the vehicle's navigation system.

## Permission

`control_navigation`

## Request

**Path**

<Snippet file="api-reference/path-vehicle-id.mdx" />

**Body**

<ParamField body="latitude" type="number" initialValue="51.5007" required>
  The latitude of the location you wish to set the vehicle's navigation to.
</ParamField>

<ParamField body="longitude" type="number" initialValue="0.1246" required>
  The longitude of the location you wish to set the vehicle's navigation to.
</ParamField>

<RequestExample>
  <Snippet file="api-reference/core-sdk-methods/send-destination-to-vehicle.mdx" />
</RequestExample>

## Response

<ResponseField name="status" type="string">
  If the request is successful, Smartcar will return “success” (HTTP 200 status).
</ResponseField>

<ResponseField name="message" type="string">
  If the request is successful, Smartcar will return a message (HTTP 200 status).
</ResponseField>

<ResponseExample>
  ```json Example Response 
  {
      "message": "Successfully sent request to vehicle",
      "status": "success"
  }   
  ```
</ResponseExample>


# Clear PIN to Drive

DELETE /vehicles/{id}/{make}/pin
Disables this feature on the vehicle and resets the PIN.

<Snippet file="api-reference/note-bse-tesla.mdx" />

## Permission

`control_pin`

## Request

**Path**

<Snippet file="api-reference/path-bse.mdx" />

<RequestExample>
  ```curl cURL
  curl "https://api.smartcar.com/v2.0/vehicles/{id}/{make}/pin" \
  -H "Authorization: Bearer {token}" \
  -X "DELETE" \
  -H "Content-Type: application/json" \
  ```

  ```python Python
  pin = vehicle.request(
    "DELETE", 
    "{make}/pin"
  )
  ```

  ```js Node
  const pin = vehicle.request(
    "DELETE", 
    "{make}/pin"
  );
  ```

  ```java Java
  SmartcarVehicleRequest request = new SmartcarVehicleRequest.Builder()
        .method("DELETE")
        .path("{make}/pin")
        .build();
  VehicleResponse pin =  vehicle.request(request);
  ```

  ```ruby Ruby
  pin =  vehicle.request(
    "DELETE", 
    "{make}/pin"
  )
  ```
</RequestExample>

## Response

<ResponseField name="status" type="string">
  If the request is successful, Smartcar will return “success”.
</ResponseField>

<ResponseField name="message" type="string">
  If the request is successful, Smartcar will return a message.
</ResponseField>

<ResponseExample>
  ```json Example Response 
      {
          "message": "Successfully sent request to vehicle",
          "status": "success"
      }   
  ```
</ResponseExample>

## Notes

*   Call `POST` [PIN to Drive](/api-reference/tesla/set-pin-to-drive) in order to enable this feature and set the PIN
*   Currently both owner and driver account types can clear a PIN for the vehicle and disable the feature via the API.


# Charge Port

POST /vehicles/{id}/{make}/charge/charge_port_door
Open or close the vehicle's charge port door.

<Snippet file="api-reference/note-bse-tesla.mdx" />

## Permission

`control_charge`

## Request

**Path**

<Snippet file="api-reference/path-bse.mdx" />

**Body**

<ParamField body="action" type="string" required>
  Indicate whether to open or close the charge port door.
  Options: `OPEN` or `CLOSE`
</ParamField>

<RequestExample>
  ```curl cURL
  curl "https://api.smartcar.com/v2.0/vehicles/{id}/{make}/charge/charge_port_door" \
  -H "Authorization: Bearer {token}" \
  -X "POST" \
  -H "Content-Type: application/json" \
  -d '{"action" : "OPEN"}'
  ```

  ```python Python
  charge_port = vehicle.request(
    "POST", 
    "{make}/charge/charge_port_door", 
    {"action" : "OPEN"}
  )
  ```

  ```js Node
  const chargePort = vehicle.request(
    "POST", 
    "{make}/charge/charge_port_door", 
    {"action" : "OPEN"}
  );
  ```

  ```java Java
  SmartcarVehicleRequest request = new SmartcarVehicleRequest.Builder()
        .method("POST")
        .path("{make}/charge/charge_port_door")
        .addBodyParameter("action" : "OPEN")
        .build();
  VehicleResponse chargePort =  vehicle.request(request);
  ```

  ```ruby Ruby
  charge_port =  vehicle.request(
    "POST", 
    "{make}/charge/charge_port_door", 
    {"action" : "OPEN"}
  )
  ```
</RequestExample>

## Response

<ResponseField name="status" type="string">
  If the request is successful, Smartcar will return “success”.
</ResponseField>

<ResponseField name="message" type="string">
  If the request is successful, Smartcar will return a message.
</ResponseField>

<ResponseExample>
  ```json Example Response 
      {
          "message": "Successfully sent request to vehicle",
          "status": "success"
      }   
  ```
</ResponseExample>


# Frunk

POST /vehicles/{id}/{make}/security/frunk
Open or close the frunk (front trunk) of the Tesla vehicle.

<Snippet file="api-reference/note-bse-tesla.mdx" />

## Permission

`control_trunk`

## Request

**Path**

<Snippet file="api-reference/path-bse.mdx" />

**Body**

<ParamField body="action" type="string" required>
  Indicate whether to open or close the charge port door.
  Options: `OPEN` or `CLOSE`
</ParamField>

<RequestExample>
  ```curl cURL
  curl "https://api.smartcar.com/v2.0/vehicles/{id}/{make}/security/frunk" \
  -H "Authorization: Bearer {token}" \
  -X "POST" \
  -H "Content-Type: application/json" \
  -d '{"action" : "OPEN"}'
  ```

  ```python Python
  frunk = vehicle.request(
    "POST", 
    "{make}/security/frunk", 
    {"action" : "OPEN"}
  )
  ```

  ```js Node
  const frunk = vehicle.request(
    "POST", 
    "{make}/security/frunk", 
    {"action" : "OPEN"}
  );
  ```

  ```java Java
  SmartcarVehicleRequest request = new SmartcarVehicleRequest.Builder()
        .method("POST")
        .path("{make}/security/frunk")
        .addBodyParameter("action" : "OPEN")
        .build();
  VehicleResponse frunk =  vehicle.request(request);
  ```

  ```ruby Ruby
  frunk =  vehicle.request(
    "POST", 
    "{make}/security/frunk", 
    {"action" : "OPEN"}
  )
  ```
</RequestExample>

## Response

<ResponseField name="status" type="string">
  If the request is successful, Smartcar will return “success”.
</ResponseField>

<ResponseField name="message" type="string">
  If the request is successful, Smartcar will return a message.
</ResponseField>

<ResponseExample>
  ```json Example Response 
      {
          "message": "Successfully sent request to vehicle",
          "status": "success"
      }   
  ```
</ResponseExample>


# Trunk

POST /vehicles/{id}/{make}/security/trunk
Open or close the trunk of the Tesla vehicle.

<Snippet file="api-reference/note-bse-tesla.mdx" />

## Permission

`control_trunk`

## Request

**Path**

<Snippet file="api-reference/path-bse.mdx" />

**Body**

<ParamField body="action" type="string" required>
  Indicate whether to open or close the charge port door.
  Options: `OPEN` or `CLOSE`
</ParamField>

<RequestExample>
  ```curl cURL
  curl "https://api.smartcar.com/v2.0/vehicles/{id}/{make}/security/trunk" \
  -H "Authorization: Bearer {token}" \
  -X "POST" \
  -H "Content-Type: application/json" \
  -d '{"action" : "OPEN"}'
  ```

  ```python Python
  trunk = vehicle.request(
    "POST", 
    "{make}/security/trunk", 
    {"action" : "OPEN"}
  )
  ```

  ```js Node
  const trunk = vehicle.request(
    "POST", 
    "{make}/security/trunk", 
    {"action" : "OPEN"}
  );
  ```

  ```java Java
  SmartcarVehicleRequest request = new SmartcarVehicleRequest.Builder()
        .method("POST")
        .path("{make}/security/trunk")
        .addBodyParameter("action" : "OPEN")
        .build();
  VehicleResponse trunk =  vehicle.request(request);
  ```

  ```ruby Ruby
  trunk =  vehicle.request(
    "POST", 
    "{make}/security/trunk", 
    {"action" : "OPEN"}
  )
  ```
</RequestExample>

## Response

<ResponseField name="status" type="string">
  If the request is successful, Smartcar will return “success”.
</ResponseField>

<ResponseField name="message" type="string">
  If the request is successful, Smartcar will return a message.
</ResponseField>

<ResponseExample>
  ```json Example Response 
      {
          "message": "Successfully sent request to vehicle",
          "status": "success"
      }   
  ```
</ResponseExample>


# Alerts

GET /vehicles/{id}/{make}/alerts
Returns recent alerts from the vehicle.

<Snippet file="api-reference/note-bse-tesla.mdx" />

## Permission

`read_alerts`

<RequestExample>
  ```curl cURL
  curl "https://api.smartcar.com/v2.0/vehicles/{id}/{make}/alerts" \
  -H "Authorization: Bearer {token}" \
  -X "GET"
  ```

  ```python Python
  alerts = vehicle.request(
        "GET", 
        "{make}/alerts"
  )
  ```

  ```js Node
  const alerts = await vehicle.request(
        "GET", 
        "{make}/alerts"
  );
  ```

  ```java Java
  SmartcarVehicleRequest request = new SmartcarVehicleRequest.Builder()
        .method("GET")
        .path("{make}/alerts")
        .build();
  VehicleResponse alerts =vehicle.request(request);
  ```

  ```ruby Ruby
  alerts = vehicle.request(
        "GET", 
        "{make}/alerts"
  )
  ```
</RequestExample>

## Request

**Path**

<Snippet file="api-reference/path-bse.mdx" />

## Response

<ResponseField name="alerts" type="[alert] | null">
  <Expandable title="alert">
    <ResponseField name="name" type="string | null">
      The name of the alert.
    </ResponseField>

    <ResponseField name="dateTime" type="timestamp | null">
      Date and time of the alert.
    </ResponseField>

    <ResponseField name="audience" type="[string] | null">
      Indicates recipients of the alert.
    </ResponseField>

    <ResponseField name="userText" type="[string] | null">
      Additional context related to the alert.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json Example Response 
  {
      "alerts" : [
            {
                  "name": "Name_Of_The_Alert",
                  "dateTime": "2022-07-10T16:20:00.000Z",
                  "audience": [
                        "service-fix",
                        "customer"
                  ],
                  "userText": "additional description text"
            }
      ]
  }
  ```
</ResponseExample>


# Tesla: Battery Status

GET /vehicles/{id}/{make}/battery
Returns all battery related data for a Tesla vehicle.

<Snippet file="api-reference/note-bse-tesla.mdx" />

## Permission

`read_battery`

<RequestExample>
  ```curl cURL
  curl "https://api.smartcar.com/v2.0/vehicles/{id}/{make}/battery" \
  -H "Authorization: Bearer {token}" \
  -X "GET"
  ```

  ```python Python
  battery =  vehicle.request(
        "GET", 
        "{make}/battery"
  )
  ```

  ```js Node
  const battery =  await vehicle.request(
        "GET", 
        "{make}/battery"
  );
  ```

  ```java Java
  SmartcarVehicleRequest request = new SmartcarVehicleRequest.Builder()
        .method("GET")
        .path("{make}/battery")
        .build();
  VehicleResponse battery = vehicle.request(request);
  ```

  ```ruby Ruby
  battery =  vehicle.request(
        "GET", 
        "{make}/battery"
  )
  ```
</RequestExample>

## Request

**Path**

<Snippet file="api-reference/path-bse.mdx" />

## Response

<ResponseField name="percentRemaining" type="number | null">
  The EV’s state of charge as a percentage.
</ResponseField>

<ResponseField name="range" type="number | null">
  The distance the vehicle can travel powered by it’s high voltage battery.
</ResponseField>

<ResponseField name="heaterOn" type="bool | null">
  Indicates if the battery heater is on.
</ResponseField>

<ResponseField name="rangeEstimated" type="number | null">
  The estimated remaining distance the vehicle can travel powered by it’s high voltage battery as determined by Tesla.
</ResponseField>

<ResponseField name="rangeIdeal" type="number | null">
  The ideal remaining distance the vehicle can travel powered by it’s high voltage battery as determined by Tesla.
</ResponseField>

<ResponseField name="percentRemainingUsable" type="number | null">
  The EV’s useable state of charge as a percentage as reported by Tesla.
</ResponseField>

<ResponseField name="maxRangeChargeCounter" type="number | null">
  The number of times the vehicle has been charged to 100% as reported by Tesla.
</ResponseField>

<ResponseField name="notEnoughPowerToHeat" type="bool | null">
  Indicates if there is enough power to heat the battery.
</ResponseField>

<ResponseExample>
  ```json Example Response 
  {
      "heaterOn": null,
      "maxRangeChargeCounter" : null,
      "notEnoughPowerToHeat" : true, 
      "percentRemaining": 0.3,
      "percentRemainingUsable" : 0.29,
      "range": 40.5,
      "rangeEstimated": 39.01,
      "rangeIdeal" : 40.5
  }
  ```
</ResponseExample>


# Cabin Climate

GET /vehicles/{id}/{make}/climate/cabin
Returns the current state and target temperature setting of a vehicle's cabin climate system.

<Snippet file="api-reference/note-bse-tesla.mdx" />

## Permission

`read_climate`

## Request

**Path**

<Snippet file="api-reference/path-bse.mdx" />

<RequestExample>
  ```curl cURL
  curl "https://api.smartcar.com/v2.0/vehicles/{id}/{make}/climate/cabin" \
  -H "Authorization: Bearer {token}" \
  -X "GET"
  ```

  ```python Python
  cabin = vehicle.request(
        "GET", 
        "{make}/climate/cabin"
  )
  ```

  ```js Node
  const chargeCompletion = await vehicle.request(
        "GET", 
        "{make}/climate/cabin"
  );
  ```

  ```java Java
  SmartcarVehicleRequest request = new SmartcarVehicleRequest.Builder()
        .method("GET")
        .path("{make}/climate/cabin")
        .build();
  VehicleResponse chargeCompletion = vehicle.request(request);
  ```

  ```ruby Ruby
  chargeCompletion = vehicle.request(
        "GET", 
        "{make}/climate/cabin"
  )
  ```
</RequestExample>

## Response

<ResponseField name="status" type="string">
  The current state of the climate cabin system.
</ResponseField>

<ResponseField name="temperature" type="number">
  The target temperature setting of the vehicle when the climate system is on (in Celsius by default or in Fahrenheit using the sc-unit-system).
</ResponseField>

<ResponseExample>
  ```json Example Response
  {
    "status": "ON",
    "temperature": 20
  }
  ```
</ResponseExample>


# Tesla: Charge Status

GET /vehicles/{id}/{make}/charge
Returns all charging related data for a Tesla vehicle.

<Snippet file="api-reference/note-bse-tesla.mdx" />

## Permission

`read_charge`

<RequestExample>
  ```curl cURL
  curl "https://api.smartcar.com/v2.0/vehicles/{id}/{make}/charge" \
  -H "Authorization: Bearer {token}" \
  -X "GET"
  ```

  ```python Python
  charge =  vehicle.request(
        "GET", 
        "{make}/charge"
  )
  ```

  ```js Node
  const charge =  await vehicle.request(
        "GET", 
        "{make}/charge"
  );
  ```

  ```java Java
  SmartcarVehicleRequest request = new SmartcarVehicleRequest.Builder()
        .method("GET")
        .path("{make}/charge")
        .build();
  VehicleResponse charge =  vehicle.request(request);
  ```

  ```ruby Ruby
  charge =  vehicle.request(
        "GET", 
        "{make}/charge"
  )
  ```
</RequestExample>

## Request

**Path**

<Snippet file="api-reference/path-bse.mdx" />

## Response

<ResponseField name="amperage" type="number | null">
  The rate that the vehicle is charging at (in amperes).
</ResponseField>

<ResponseField name="completionTime" type="string | null">
  An ISO8601 formatted datetime (YYYY-MM-DDTHH:mm:ss.SSSZ) for the time at which the vehicle expects to complete this charging session.
</ResponseField>

<ResponseField name="wattage" type="number | null">
  The instant power measured by the vehicle (in kilowatts).
</ResponseField>

<ResponseField name="isPluggedIn" type="bool | null">
  Indicates if the vehicle is plugged in
</ResponseField>

<ResponseField name="state" type="string | null">
  Indicates the charging status of the vehicle
</ResponseField>

<ResponseField name="socLimit" type="number | null">
  Indicates the level at which the vehicle will stop charging and be considered fully charged as a percentage.
</ResponseField>

<ResponseField name="amperageMaxVehicle" type="number | null">
  Indicates the max amperage the vehicle can request from the charger.
</ResponseField>

<ResponseField name="socLimitMax" type="number | null">
  Indicates the max SoC limit that can be set.
</ResponseField>

<ResponseField name="socLimitMin" type="number | null">
  Indicates the min SoC limit that can be set.
</ResponseField>

<ResponseField name="socLimitDefault" type="number | null">
  Indicates the default SoC limit of the vehicle.
</ResponseField>

<ResponseField name="amperageRequested" type="number | null">
  Indicates the amperage requested from the charger by the vehicle.
</ResponseField>

<ResponseField name="energyAdded" type="number | null">
  Energy added in the current charging session or most recent session if the vehicle is not charging (in kilowatts).
</ResponseField>

<ResponseField name="rangeAddedRated" type="number | null">
  The rated range as determined by Tesla added in the current charging session or most recent session if the vehicle is not charging (in kilometers added).
</ResponseField>

<ResponseField name="rangeAddedIdeal" type="number | null">
  The ideal range as determined by Tesla added in the current charging session or most recent session if the vehicle is not charging (in kilometers added).
</ResponseField>

<ResponseField name="chargeRate" type="number | null">
  The rate of range added in the charging session (in kilometers added / hour).
</ResponseField>

<ResponseField name="connector" type="string | null">
  Standard of the connector e.g. SAE
</ResponseField>

<ResponseField name="fastChargerPresent" type="bool | null">
  When charging, indicates if the vehicle connected to a fast charger.
</ResponseField>

<ResponseField name="fastChargerType" type="string | null">
  Indicates the type of fast charger.
</ResponseField>

<ResponseField name="fastChargerBrand" type="string | null">
  Indicates the brand of fast charger.
</ResponseField>

<ResponseField name="amperageMaxCharger" type="number | null">
  Indicates the max amperage supported by the charger.
</ResponseField>

<ResponseField name="chargePortColor" type="string | null">
  The indicator light color of the connector.
</ResponseField>

<ResponseField name="chargePortOpen" type="bool | null">
  Indicates if th charge port door is open.
</ResponseField>

<ResponseField name="chargePortLatch" type="string | null">
  Indicates if the charge port latch status.
</ResponseField>

<ResponseField name="chargerPhases" type="number | null">
  Indicates the charging phase.
</ResponseField>

<ResponseExample>
  ```json Example Response 
      {
            "amperage": 0,
            "completionTime": null,
            "wattage": 0,
            "voltage": 1,
            "isPluggedIn": false,
            "state": "NOT_CHARGING",
            "socLimit": 0.8,
            "amperageMaxVehicle": 48,
            "socLimitMax": 1,
            "socLimitMin": 0.5,
            "socLimitDefault": 0.8,
            "amperageRequested": 48,
            "energyAdded": 11.52,
            "rangeAddedRated": 70.811,
            "rangeAddedIdeal": 70.811,
            "chargeRate": 0,
            "connector": "<invalid>",
            "fastChargerPresent": false,
            "fastChargerType": "<invalid>",
            "fastChargerBrand": "<invalid>",
            "amperageMaxCharger": 48,
            "chargePortColor": "<invalid>",
            "chargePortOpen": false,
            "chargePortLatch": "Engaged",
            "chargerPhases": null
      }
  ```
</ResponseExample>


# Charge Completion Time

GET /vehicles/{id}/{make}/charge/completion
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.

<Note>
  This endpoint is currently available for `tesla`.
</Note>

## Permission

`read_charge`

## Request

<ParamField path="id" type="string" required>
  `vehicle_id` of the vehicle you are making the request to.
</ParamField>

<ParamField path="make" type="string" required>
  The make to pass in the URL.
</ParamField>

<RequestExample>
  <Snippet file="api-reference/bse/get-charge-completion-time.mdx" />
</RequestExample>

## Response

<ResponseField name="time" type="string">
  An ISO8601 formatted datetime (`YYYY-MM-DDTHH:mm:ss.SSSZ`) for the time at which the vehicle expects to complete this charging session.
</ResponseField>

<ResponseExample>
  ```json Example Response
  {
    "time": "2022-01-13T22:52:55.358Z"
  }
  ```
</ResponseExample>


# Charge Billing Records

GET /vehicles/{id}/{make}/charge/records/billing
Returns information about charging sessions for Tesla vehicles at public Tesla chargers including cost and charging site.

<Snippet file="api-reference/note-bse-tesla.mdx" />

## Permission

`read_charge_records`

## Request

**Path**

<Snippet file="api-reference/path-bse.mdx" />

**Query**

<ParamField query="startDate">
  Date of the first record to return in YYYY-MM-DD format.
  Defaults to 30 days prior  or when the owner first granted your application access, whichever is shorter.
</ParamField>

<ParamField query="endDate">
  Date of the final record to return in YYYY-MM-DD format. Defaults to the date of the request.
</ParamField>

<ParamField query="page">
  The page number to fetch from Tesla where page 1 contains the most recent records.
</ParamField>

<RequestExample>
  ```curl cURL
  curl "https://api.smartcar.com/v2.0/vehicles/{id}/{make}/charge/records/billing?page=12&startDate=2023-08-24" \
      -H "Authorization: Bearer {token}" \
      -X "GET" \
      -H "Content-Type: application/json" \
  ```

  ```python Python
  billing = vehicle.request(
    "GET", 
    "{make}/charge/records/billing?startDate=2023-08-24&page=12"
  )
  ```

  ```js Node
  const billing = vehicle.request(
    "GET", 
    "{make}/charge/records/billing?startDate=2023-08-24&page=12"
  );
  ```

  ```java Java
  SmartcarVehicleRequest request =
      new SmartcarVehicleRequest.Builder()
          .method("GET")
          .path("ford/charge/schedule_by_location")
          .addQueryParameter("startDate", "2023-08-24")
          .addQueryParameter("page", "12")
          .build();

  VehicleResponse billing = vehicle.request(request);
  ```

  ```ruby Ruby
  billing = vehicle.request(
    "GET", 
    "{make}/charge/records/billing?startDate=2023-08-24&page=12"
  )
  ```
</RequestExample>

## Response

<ResponseField name="records" type="[object]">
  An array of billing records for the vehicle associated with charging at public Tesla charging stations.

  Can be empty if the specified page does not contain any records for the vehicle.
  This **does not** mean that subsequent pages will also contain no records. Please check the `hasMoreData` field for confirmation instead.

  <Expandable defaultOpen="true">
    <ResponseField name="chargeStart" type="string">
      The date and time of charging session start, formatted in ISO 8601 standard.
    </ResponseField>

    <ResponseField name="chargeEnd" type="string">
      The date and time of charging session end, formatted in ISO 8601 standard.
    </ResponseField>

    <ResponseField name="energyConsumed" type="number" default="kWh">
      Energy consumed in the charging session.
    </ResponseField>

    <ResponseField name="cost" type="object">
      A cost breakout of the charging session.

      <Expandable defaultOpen="true">
        <ResponseField name="currency" type="string">
          The currency code for the fees.
        </ResponseField>

        <ResponseField name="energy" type="number">
          Fess associated with charging the vehicle.
        </ResponseField>

        <ResponseField name="other" type="number">
          Fees associated with the session other than charging the vehicle e.g. parking.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="location" type="string">
      The name of the charging site.
    </ResponseField>

    <ResponseField name="recordId" type="string">
      Tesla’s id for this charging session.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="hasMoreData" type="bool">
  Indicates if there are any more records to fetch from Tesla for this vehicle. **Does not** guarantee a non-empty list for the next page when `true`.
</ResponseField>

<ResponseExample>
  ```json Example Response 
  {
    "records": [
        {
            "chargeEnd": "2022-07-10T16:20:00.000Z",
            "chargeStart": "2022-07-10T15:40:00.000Z",
            "energyConsumed": 44.10293884
            "cost": {
                "currency": "USD",
                "energy": "41",
                "other": "41"
            },
            "location": "Los Gatos, CA",
            "recordId": "GF220075000028-3-1682903685"
        }
    ],
    "hasMoreData" : false
  }
  ```
</ResponseExample>


# Charge Schedule

GET /vehicles/{id}/{make}/charge/schedule
Returns the charging schedule of a vehicle. The response contains the start time and departure time of the vehicle's charging schedule.

<Snippet file="api-reference/note-bse-tesla.mdx" />

## Permission

`read_charge`

## Request

**Path**

<Snippet file="api-reference/path-bse.mdx" />

<RequestExample>
  <Snippet file="api-reference/bse/get-charge-schedule.mdx" />
</RequestExample>

## Response

<ResponseField name="departureTime" type="object">
  The departure time configuration for the charging schedule.

  <Expandable title="departureTime">
    <ResponseField name="enabled" type="boolean">
      Indicates whether this schedule type is enabled or disabled.
      Only one of `departureTime` or `departureTime` can be enabled at a time.
    </ResponseField>

    <ResponseField name="time" type="string | null">
      When plugged in, the vehicle **may** delay starting a charging session as long as it can reach its
      [charge limit](/api-reference/evs/get-charge-limit) by this time in HH:mm.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="startTime" type="object">
  The start time configuration for the charging schedule.

  <Expandable title="startTime">
    <ResponseField name="enabled" type="boolean">
      Indicates whether this schedule type is enabled or disabled.
      Only one of `departureTime` or `departureTime` can be enabled at a time.
    </ResponseField>

    <ResponseField name="time" type="string | null">
      When plugged in, the vehicle will delay starting a charging session until this time in HH:mm.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json Example Response 
  {
    "departureTime": {
      "enabled": false,
      "time": null
    },
    "startTime": {
      "enabled": true,
      "time": "18:30"
    }
  }
  ```
</ResponseExample>


# Voltage

GET /vehicles/{id}/{make}/charge/voltmeter
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.

<Note>
  This endpoint is currently available for `tesla`.
</Note>

## Permission

`read_charge`

## Request

<Snippet file="api-reference/path-bse.mdx" />

<RequestExample>
  <Snippet file="api-reference/bse/get-charge-voltmeter.mdx" />
</RequestExample>

## Response

<ResponseField name="voltage" type="number">
  The potential difference measured by the vehicle in volts (V).
</ResponseField>

<ResponseExample>
  ```json Example Response
  {
    "voltage": 240
  }
  ```
</ResponseExample>


# Wattage

GET /vehicles/{id}/{make}/charge/wattmeter
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.

<Snippet file="api-reference/note-bse-tesla.mdx" />

## Permission

`read_charge`

## Request

**Path**

<Snippet file="api-reference/path-bse.mdx" />

<RequestExample>
  ```curl cURL
  curl "https://api.smartcar.com/v2.0/vehicles/{id}/{make}/charge/wattmeter" \
  -H "Authorization: Bearer {token}" \
  -X "GET"
  ```

  ```python Python
  wattmeter = vehicle.request(
        "GET", 
        "{make}/charge/wattmeter"
  )
  ```

  ```js Node
  const wattmeter = await vehicle.request(
        "GET", 
        "{make}/charge/wattmeter"
  );
  ```

  ```java Java
  SmartcarVehicleRequest request = new SmartcarVehicleRequest.Builder()
        .method("GET")
        .path("{make}/charge/wattmeter")
        .build();
  VehicleResponse wattmeter = vehicle.request(request);
  ```

  ```ruby Ruby
  wattmeter = vehicle.request(
        "GET", 
        "{make}/charge/wattmeter"
  )
  ```
</RequestExample>

## Response

<ResponseField name="wattage" type="number">
  The instant power measured by the vehicle (in kilowatts).
</ResponseField>

<ResponseExample>
  ```json Example Response 
  {
    "wattage": 3.5
  }
  ```
</ResponseExample>


# Compass

GET /vehicles/{id}/{make}/compass
Returns the current compass heading and direction of the vehicle.

<Snippet file="api-reference/note-bse-tesla.mdx" />

## Permission

`read_compass`

## Request

**Path**

<Snippet file="api-reference/path-bse.mdx" />

<RequestExample>
  ```curl cURL
  curl "https://api.smartcar.com/v2.0/vehicles/{id}/{make}/compass" \
  -H "Authorization: Bearer {token}" \
  -X "GET"
  ```

  ```python Python
  compass = vehicle.request(
        "GET", 
        "{make}/compass"
  )
  ```

  ```js Node
  const compass = await vehicle.request(
        "GET", 
        "{make}/compass"
  );
  ```

  ```java Java
  SmartcarVehicleRequest request = new SmartcarVehicleRequest.Builder()
        .method("GET")
        .path("{make}/compass")
        .build();
  VehicleResponse compass = vehicle.request(request);
  ```

  ```ruby Ruby
  compass = vehicle.request(
        "GET", 
        "{make}/compass"
  )
  ```
</RequestExample>

## Response

<ResponseField name="direction" type="string">
  The current direction of the vehicle.
</ResponseField>

<ResponseField name="heading" type="number">
  The current compass heading of the vehicle (in degrees).
</ResponseField>

<ResponseExample>
  ```json Example Response 
  {
    "direction": "SW",
    "heading": 185
  }
  ```
</ResponseExample>


# Defroster

GET /vehicles/{is}/{make}/climate/defroster
Returns the current state of a vehicle's front and rear defroster.

<Snippet file="api-reference/note-bse-tesla.mdx" />

## Permission

`read_climate`

<RequestExample>
  ```curl cURL
  curl "https://api.smartcar.com/v2.0/vehicles/{id}/{make}/climate/defroster" \
  -H "Authorization: Bearer {token}" \
  -X "GET"
  ```

  ```python Python
  defroster = vehicle.request(
        "GET", 
        "{make}/climate/defroster"
  )
  ```

  ```js Node
  const defroster = await vehicle.request(
        "GET", 
        "{make}/climate/defroster"
  );
  ```

  ```java Java
  SmartcarVehicleRequest request = new SmartcarVehicleRequest.Builder()
        .method("GET")
        .path("{make}/climate/defroster")
        .build();
  VehicleResponse defroster = vehicle.request(request);
  ```

  ```ruby Ruby
  defroster = vehicle.request(
        "GET", 
        "{make}/climate/defroster"
  )
  ```
</RequestExample>

## Request

**Path**

<Snippet file="api-reference/path-bse.mdx" />

## Response

<ResponseField name="frontStatus" type="string">
  The current state of the front defroster.
</ResponseField>

<ResponseField name="rearStatus" type="string">
  The current state of the rear defroster.
</ResponseField>

<ResponseExample>
  ```json Example Response  
  {
    "frontStatus": "ON",
    "rearStatus": "OFF"
  }
  ```
</ResponseExample>


# Extended Vehicle Info

GET /vehicles/{id}/{make}/attributes
Returns detailed configuration information for a vehicle.

<Snippet file="api-reference/note-bse-tesla.mdx" />

## Permission

`read_extended_vehicle_info`

## Request

**Path**

<Snippet file="api-reference/path-bse.mdx" />

<RequestExample>
  ```curl cURL
  curl "https://api.smartcar.com/v2.0/vehicles/{id}/{make}/attributes" \
  -H "Authorization: Bearer {token}" \
  -X "GET"
  ```

  ```python Python
  attributes = vehicle.request(
        "GET", 
        "{make}/attributes"
  )
  ```

  ```js Node
  const attributes = await vehicle.request(
        "GET", 
        "{make}/attributes"
  );
  ```

  ```java Java
  SmartcarVehicleRequest request = new SmartcarVehicleRequest.Builder()
        .method("GET")
        .path("{make}/attributes")
        .build();
  VehicleResponse attributes = vehicle.request(request);
  ```

  ```ruby Ruby
  attributes = vehicle.request(
        "GET", 
        "{make}/attributes"
  )
  ```
</RequestExample>

## Response

<ResponseField name="id" type="string">
  A vehicle ID (UUID v4).
</ResponseField>

<ResponseField name="make" type="string">
  The manufacturer of the vehicle.
</ResponseField>

<ResponseField name="model" type="string">
  The model of the vehicle.
</ResponseField>

<ResponseField name="year" type="integer">
  The model year.
</ResponseField>

<ResponseField name="firmwareVersion" type="string">
  Vehicle's current firmware.
</ResponseField>

<ResponseField name="trimBadging" type="string">
  Indicates the Tesla's trim.
</ResponseField>

<ResponseField name="efficiencyPackage" type="string">
  Efficiency package.
</ResponseField>

<ResponseField name="performancePackage" type="string">
  Performance package.
</ResponseField>

<ResponseField name="nickname" type="string">
  Vehicle's nickname.
</ResponseField>

<ResponseField name="driverAssistVersion" type="string">
  Driver Assist version.
</ResponseField>

<ResponseField name="sentryMode" type="object">
  Sentry Mode status and availability.

  <Expandable>
    <ResponseField name="available" type="bool">
      Does the vehicle support Sentry Mode.
    </ResponseField>

    <ResponseField name="enabled" type="bool">
      Is Sentry Mode currently enabled for a vehicle.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="style" type="object">
  Descriptors of the vehicle's interior and exterior.

  <Expandable>
    <ResponseField name="exteriorColor" type="string">
      Exterior color.
    </ResponseField>

    <ResponseField name="exteriorTrim" type="string">
      Exterior trim.
    </ResponseField>

    <ResponseField name="interiorTrim" type="string">
      Interior trim.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="wheel" type="object">
  Descriptors of the vehicle's wheel.

  <Expandable>
    <ResponseField name="style" type="string">
      Style of the wheel.
    </ResponseField>

    <ResponseField name="diameter" type="number" default="millimeters">
      Diameter of the wheel.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="driveUnit" type="object">
  Details on the vehicle's drive unit(s).

  <Expandable>
    <ResponseField name="rear" type="string">
      Rear drive unit.
    </ResponseField>

    <ResponseField name="front" type="string">
      Front drive unit.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json Example Response 
  {
      "driveUnit": {
          "front": "PM216MOSFET",
          "rear": "NoneOrSmall"
      },
      "driverAssistVersion": "TeslaAP3",
      "efficiencyPackage": "MY2021",
      "firmwareVersion": "2022.8.10.12 0ce482dac45d",
      "id": "36ab27d0-fd9d-4455-823a-ce30af709ffc",
      "make": "TESLA",
      "model": "Model S",
      "nickname": "Tommy",
      "performancePackage": "Base",
      "sentryMode": {
          "available": false,
          "enabled": true
      },
      "style": {
          "exteriorColor": "SolidBlack",
          "exteriorTrim": "Black",
          "interiorTrim": "Black2"
      },
      "trimBadging": "74d",
      "wheel": {
          "diameter": 482.6,
          "style": "Apollo"
      },
      "year": 2022
  }
  ```
</ResponseExample>


# Exterior Temperature

GET /vehicles/{id}/{make}/thermometer/exterior
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.

<Snippet file="api-reference/note-bse-tesla.mdx" />

## Permission

`read_thermometer`

## Request

**Path**

<Snippet file="api-reference/path-bse.mdx" />

<RequestExample>
  ```curl cURL
  curl "https://api.smartcar.com/v2.0/vehicles/{id}/{make}/thermometer/exterior" \
  -H "Authorization: Bearer {token}" \
  -X "GET"
  ```

  ```python Python
  temperature = vehicle.request(
        "GET", 
        "{make}/thermometer/exterior"
  )
  ```

  ```js Node
  const temperature = await vehicle.request(
        "GET", 
        "{make}/thermometer/exterior"
  );
  ```

  ```java Java
  SmartcarVehicleRequest request = new SmartcarVehicleRequest.Builder()
        .method("GET")
        .path("{make}/thermometer/exterior")
        .build();
  VehicleResponse temperature = vehicle.request(request);
  ```

  ```ruby Ruby
  temperature = vehicle.request(
        "GET", 
        "{make}/thermometer/exterior"
  )
  ```
</RequestExample>

## Response

<ResponseField name="temperature" default="celsius" type="number">
  The current exterior temperature of the vehicle.
</ResponseField>

<ResponseExample>
  ```json Example Response 
  {
    "temperature": 33.42
  }
  ```
</ResponseExample>


# Interior Temperature

GET /vehicles/{id}/{make}/thermometer/interior
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.

<Snippet file="api-reference/note-bse-tesla.mdx" />

## Permission

`read_thermometer`

## Request

**Path**

<Snippet file="api-reference/path-bse.mdx" />

<RequestExample>
  ```curl cURL
  curl "https://api.smartcar.com/v2.0/vehicles/{id}/{make}/thermometer/interior" \
  -H "Authorization: Bearer {token}" \
  -X "GET"
  ```

  ```python Python
  temperature = vehicle.request(
        "GET", 
        "{make}/thermometer/interior"
  )
  ```

  ```js Node
  const temperature = await vehicle.request(
        "GET", 
        "{make}/thermometer/interior"
  );
  ```

  ```java Java
  SmartcarVehicleRequest request = new SmartcarVehicleRequest.Builder()
        .method("GET")
        .path("{make}/thermometer/interior")
        .build();
  VehicleResponse temperature = vehicle.request(request);
  ```

  ```ruby Ruby
  temperature = vehicle.request(
        "GET", 
        "{make}/thermometer/interior"
  )
  ```
</RequestExample>

## Response

<ResponseField name="temperature" default="celsius" type="number">
  The current interior temperature of the vehicle.
</ResponseField>

<ResponseExample>
  ```json Example Response 
  {
    "temperature": 25.64
  }
  ```
</ResponseExample>


# Migration Status

GET /vehicles/{id}/{make}/migration
Indicates if the vehicle needs to migrate to Tesla's new API. See [Tesla - What's New](https://smartcar.com/docs/help/oem-integrations/tesla/whats-new) for more details.

<Snippet file="api-reference/note-bse-tesla.mdx" />

## Permission

`read_vehicle_info`

## Request

**Path**

<Snippet file="api-reference/path-bse.mdx" />

<RequestExample>
  ```curl cURL
  curl "https://api.smartcar.com/v2.0/vehicles/{id}/{make}/migration" \
  -H "Authorization: Bearer {token}" \
  -X "GET"
  ```

  ```python Python
  status = vehicle.request(
        "GET", 
        "{make}/migration"
  )
  ```

  ```js Node
  const status = await vehicle.request(
        "GET", 
        "{make}/migration"
  );
  ```

  ```java Java
  SmartcarVehicleRequest request = new SmartcarVehicleRequest.Builder()
        .method("GET")
        .path("{make}/migration")
        .build();
  VehicleResponse status = vehicle.request(request);
  ```

  ```ruby Ruby
  status = vehicle.request(
        "GET", 
        "{make}/migration"
  )
  ```
</RequestExample>

## Response

<ResponseField name="requiresMigration" type="boolean">
  Set to `false` if the vehicle is connected to Smartcar via Tesla's new integration. See [Tesla - What's New](/help/oem-integrations/tesla/whats-new) for more details.
</ResponseField>

<ResponseExample>
  ```json Example Response 
  {
      "requiresMigration": false
  }
  ```
</ResponseExample>


# Speed

GET /vehicles/{id}/{make}/speedometer
Returns the current speed of the vehicle.

<Snippet file="api-reference/note-bse-tesla.mdx" />

## Permission

`read_speedometer`

## Request

**Path**

<Snippet file="api-reference/path-bse.mdx" />

<RequestExample>
  ```curl cURL
  curl "https://api.smartcar.com/v2.0/vehicles/{id}/{make}/speedometer" \
  -H "Authorization: Bearer {token}" \
  -X "GET"
  ```

  ```python Python
  speed = vehicle.request(
        "GET", 
        "{make}/speedometer"
  )
  ```

  ```js Node
  const speed = await vehicle.request(
        "GET", 
        "{make}/speedometer"
  );
  ```

  ```java Java
  SmartcarVehicleRequest request = new SmartcarVehicleRequest.Builder()
        .method("GET")
        .path("{make}/speedometer")
        .build();
  VehicleResponse speed = vehicle.request(request);
  ```

  ```ruby Ruby
  speed = vehicle.request(
        "GET", 
        "{make}/speedometer"
  )
  ```
</RequestExample>

## Response

<ResponseField name="speed" default="km/h" type="number">
  The current speed of the vehicle.
</ResponseField>

<ResponseExample>
  ```json Example Response 
  {
    "speed": 84.32
  }
  ```
</ResponseExample>


# Steering Heater

GET /vehicles/{id}/{make}/climate/steering_wheel
Returns the current state of a vehicle's steering wheel heater system.

<Snippet file="api-reference/note-bse-tesla.mdx" />

## Permission

`read_climate`

## Request

**Path**

<Snippet file="api-reference/path-bse.mdx" />

<RequestExample>
  ```curl cURL
  curl "https://api.smartcar.com/v2.0/vehicles/{id}/{make}/climate/steering_wheel" \
  -H "Authorization: Bearer {token}" \
  -X "GET"
  ```

  ```python Python
  steering_wheel = vehicle.request(
        "GET", 
        "{make}/climate/steering_wheel"
  )
  ```

  ```js Node
  const steeringWheel = await vehicle.request(
        "GET", 
        "{make}/climate/steering_wheel"
  );
  ```

  ```java Java
  SmartcarVehicleRequest request = new SmartcarVehicleRequest.Builder()
        .method("GET")
        .path("{make}/climate/steering_wheel")
        .build();
  VehicleResponse steeringWheel = vehicle.request(request);
  ```

  ```ruby Ruby
  steering_wheel = vehicle.request(
        "GET", 
        "{make}/climate/steering_wheel"
  )
  ```
</RequestExample>

## Response

<ResponseField name="status" type="enum">
  The current state of the steering wheel heater system. `UNAVAILABLE` indicates the vehicle is not equipped with a steering wheel heater.
</ResponseField>

<ResponseExample>
  ```json Example Response
  {
    "status": "ON",
  }
  ```
</ResponseExample>


# User Access

GET /vehicles/{id}/{make}/user/access
Returns the account type and permissions for the connected Tesla account.

<Snippet file="api-reference/note-bse-tesla.mdx" />

<RequestExample>
  ```curl cURL
  curl "https://api.smartcar.com/v2.0/vehicles/{id}/{make}/user/access" \
  -H "Authorization: Bearer {token}" \
  -X "GET"
  ```

  ```python Python
  access = vehicle.request(
        "GET", 
        "{make}/user/access"
  )
  ```

  ```js Node
  const access = await vehicle.request(
        "GET", 
        "{make}/user/access"
  );
  ```

  ```java Java
  SmartcarVehicleRequest request = new SmartcarVehicleRequest.Builder()
        .method("GET")
        .path("{make}/user/access")
        .build();
  VehicleResponse access =vehicle.request(request);
  ```

  ```ruby Ruby
  access = vehicle.request(
        "GET", 
        "{make}/user/access"
  )
  ```
</RequestExample>

## Request

**Path**

<Snippet file="api-reference/path-bse.mdx" />

## Response

<ResponseField name="accessType" type="string | null">
  Returns the type of Tesla account connected. Can be either `OWNER` or `DRIVER`. Please see our [Tesla FAQs](/help/oem-integrations/tesla/faqs) for details on the differences between account types.
</ResponseField>

<ResponseField name="permissions" type="[string] | null">
  Returns a list of permissions granted by the user with their Tesla account. Please see [this page](/help/oem-integrations/tesla/developers#permission-mappings) on the mapping from Smartcar permissions to Tesla's.
</ResponseField>

<ResponseExample>
  ```json Example Response 
  {
    "accessType": "OWNER",
    "permissions" : ["vehicle_cmds", "vehicle_device_data"]
  }
  ```
</ResponseExample>

## Notes

*   If you're receiving a [SERVER:INTERNAL](/errors/api-errors/server-errors#internal) error please have the user reconnect their vehicle.


# User Info

GET /vehicles/{id}/{make}/user/info
Returns the email associated with the connected Tesla account.

<Snippet file="api-reference/note-bse-tesla.mdx" />

## Permission

`read_user_profile`

<RequestExample>
  ```curl cURL
  curl "https://api.smartcar.com/v2.0/vehicles/{id}/{make}/user/info" \
  -H "Authorization: Bearer {token}" \
  -X "GET"
  ```

  ```python Python
  info = vehicle.request(
        "GET", 
        "{make}/user/info"
  )
  ```

  ```js Node
  const info = await vehicle.request(
        "GET", 
        "{make}/user/info"
  );
  ```

  ```java Java
  SmartcarVehicleRequest request = new SmartcarVehicleRequest.Builder()
        .method("GET")
        .path("{make}/user/info")
        .build();
  VehicleResponse info =vehicle.request(request);
  ```

  ```ruby Ruby
  info = vehicle.request(
        "GET", 
        "{make}/user/info"
  )
  ```
</RequestExample>

## Request

**Path**

<Snippet file="api-reference/path-bse.mdx" />

## Response

<ResponseField name="email" type="string | null">
  The email associated with the connected Tesla account.
</ResponseField>

<ResponseExample>
  ```json Example Response 
      {
          "email" : "api@smartcar.com"
      }
  ```
</ResponseExample>


# Vehicle Status

GET /vehicles/{id}/{make}/status
Returns the status for the vehicle.

<Snippet file="api-reference/note-bse-tesla.mdx" />

## Permission

`read_extended_vehicle_info`

## Request

**Path**

<Snippet file="api-reference/path-bse.mdx" />

<RequestExample>
  ```curl cURL
  curl "https://api.smartcar.com/v2.0/vehicles/{id}/{make}/status" \
  -H "Authorization: Bearer {token}" \
  -X "GET"
  ```

  ```python Python
  status = vehicle.request(
        "GET", 
        "{make}/status"
  )
  ```

  ```js Node
  const status = await vehicle.request(
        "GET", 
        "{make}/status"
  );
  ```

  ```java Java
  SmartcarVehicleRequest request = new SmartcarVehicleRequest.Builder()
        .method("GET")
        .path("{make}/status")
        .build();
  VehicleResponse status = vehicle.request(request);
  ```

  ```ruby Ruby
  status = vehicle.request(
        "GET", 
        "{make}/status"
  )
  ```
</RequestExample>

## Response

<ResponseField name="status" type="string">
  The current status of the vehicle. If the vehicle is asleep, this request will not wake the vehicle.
</ResponseField>

<ResponseField name="inService" type="bool">
  Indicates if the vehicle is in service mode.
</ResponseField>

<ResponseField name="gear" type="string">
  Indicates the current gear shift position.
</ResponseField>

<ResponseExample>
  ```json Example Response 
  {
  "status": "ASLEEP",
  "inService": true,
  "gear": "DRIVE"
  }
  ```
</ResponseExample>


# Virtual Key Status

GET /vehicles/{id}/{make}/virtual_key
Indicates if a vehicle has the appropriate virtual key installed. See [Tesla - What's New](https://smartcar.com/docs/help/oem-integrations/tesla/whats-new#if-your-application-issues-commands) for more details on Tesla's virtual key requirements.

<Snippet file="api-reference/note-bse-tesla.mdx" />

## Permission

`read_vehicle_info`

## Request

**Path**

<Snippet file="api-reference/path-bse.mdx" />

<RequestExample>
  ```curl cURL
  curl "https://api.smartcar.com/v2.0/vehicles/{id}/{make}/virtual_key" \
  -H "Authorization: Bearer {token}" \
  -X "GET"
  ```

  ```python Python
  virtual_key = vehicle.request(
        "GET", 
        "{make}/virtual_key"
  )
  ```

  ```js Node
  const virtualKey = await vehicle.request(
        "GET", 
        "{make}/virtual_key"
  );
  ```

  ```java Java
  SmartcarVehicleRequest request = new SmartcarVehicleRequest.Builder()
        .method("GET")
        .path("{make}/virtual_key")
        .build();
  VehicleResponse virtualKey = vehicle.request(request);
  ```

  ```ruby Ruby
  virtual_key = vehicle.request(
        "GET", 
        "{make}/virtual_key"
  )
  ```
</RequestExample>

## Response

<ResponseField name="isPaired" type="boolean">
  Returns `true` if the vehicle has the appropriate Virtual Key installed. See [Tesla - What's New](/help/oem-integrations/tesla/whats-new#if-your-application-issues-commands) for more details on Tesla's virtual key requirements.
</ResponseField>

<ResponseExample>
  ```json Example Response 
  {
      "isPaired": true
  }
  ```
</ResponseExample>

## Notes

*   This endpoint will throw a [COMPATIBILITY:PLATFORM\_NOT\_CAPABLE](/errors/api-errors/compatibility-errors#platform-not-capable) error if a vehicle is connected to your application via Tesla's legacy integration.
*   This endpoint will throw a [CONNECTED\_SERVICES\_ACCOUNT:VEHICLE\_MISSING](/errors/api-errors/compatibility-errors#vehicle-missing) error if the Tesla account connected to Smartcar is **not** the Owner of the vehicle. See our [FAQs](/help/oem-integrations/tesla/faqs#can-owner-and-driver-accounts-authorize-access-with-smartcar-through-connect) for more information on Owner and Driver account types.


# Cabin Climate

POST /vehicles/{id}/{make}/climate/cabin
Set the temperature and control the cabin climate system for a vehicle.

<Snippet file="api-reference/note-bse-tesla.mdx" />

## Permission

`control_climate`

## Request

**Path**

<Snippet file="api-reference/path-bse.mdx" />

**Body**

<ParamField body="action" type="string" required>
  Indicate whether to start or stop the cabin climate control system, or set the temperature.
  If starting or stopping the system, `temperature` is optional and will use the vehicle's current setting by default.

  <Expandable title="status">
    <ResponseField name="START" type="string" />

    <ResponseField name="STOP" type="string" />

    <ResponseField name="SET" type="string">
      Use `SET` to set the `temperature` without changing the climate systems status.
    </ResponseField>
  </Expandable>
</ParamField>

<ParamField body="temperature" type="string">
  Indicate what temperature to set (in Celsius by default or in Fahrenheit using the sc-unit-system).
  If the provided temperature is out of the bounds allowed by the vehicle's climate control system,
  the request will fail with the upper and lower limits in the error response message.
</ParamField>

<RequestExample>
  ```curl cURL
  curl "https://api.smartcar.com/v2.0/vehicles/{id}/{make}/climate/cabin" \
  -H "Authorization: Bearer {token}" \
  -X "POST" \
  -H "Content-Type: application/json" \
  -d '{"action": "SET", "temperature": 20}'
  ```

  ```python Python
  set_climate_cabin = vehicle.request(
    "POST", 
    "{make}/climate/cabin", 
    {
      "action": "SET", 
      "temperature": 18
    }
  )

  ```

  ```js Node
  const vehicleStopCabin = vehicle.request(
    "POST", 
    "{make}/climate/cabin", 
    {"action": "STOP"}
  );

  ```

  ```java Java
  SmartcarVehicleRequest request = new SmartcarVehicleRequest.Builder()
        .method("POST")
        .path("{make}/climate/cabin")
        .addBodyParameter("action", "START")
        .build();
  VehicleResponse startClimateCabin = vehicle.request(request);
  ```

  ```ruby Ruby
  setChargeScheduleByLocation = vehicle.request(
    "POST", 
    "{make}/climate/cabin", 
    {"action" : "START"}
  )
  ```
</RequestExample>

## Response

<ResponseField name="status" type="string">
  If the request is successful, Smartcar will return `"success"` (HTTP 200 status) containing the current state of the climate cabin system.
</ResponseField>

<ResponseField name="temperature" type="number">
  The target temperature setting of the vehicle when the climate system is on (in Celsius by default or in Fahrenheit using the sc-unit-system).
</ResponseField>

<ResponseExample>
  ```json Example Response
  {
    "status": "ON",
    "temperature": 24
  }
  ```
</ResponseExample>


# Amperage

POST /vehicles/{id}/{make}/charge/ammeter
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.

<Snippet file="api-reference/note-bse-tesla.mdx" />

## Permission

`control_charge`

## Request

**Path**

<Snippet file="api-reference/path-bse.mdx" />

**Body**

<ParamField body="amperage" type="number" required>
  The target amperage to be drawn by the vehicle from the charging point (in amperes). If the value passed is greater than what is supported by the charger, it will be set to the maximum.
</ParamField>

<RequestExample>
  ```curl cURL
  curl "https://api.smartcar.com/v2.0/vehicles/{id}/{make}/charge/ammeter" \
  -H "Authorization: Bearer {token}" \
  -X "POST" \
  -H "Content-Type: application/json" \
  -d '{"amperage": 48}'
  ```

  ```python Python
  ammeter = vehicle.request(
    "POST", 
    "{make}/charge/ammeter", 
    {"amperage": 48}
  )
  ```

  ```js Node
  const ammeter = vehicle.request(
    "POST", 
    "{make}/charge/ammeter", 
    {"amperage": 48}
  );
  ```

  ```java Java
  SmartcarVehicleRequest request = new SmartcarVehicleRequest.Builder()
        .method("POST")
        .path("{make}/charge/ammeter")
        .addBodyParameter("amperage": 48)
        .build();
  VehicleResponse ammeter = vehicle.request(request);
  ```

  ```ruby Ruby
  ammeter = vehicle.request(
    "POST", 
    "{make}/charge/ammeter", 
    {"amperage": 48}
  )
  ```
</RequestExample>

## Response

<ResponseField name="message" type="string">
  If the request is successful, Smartcar will return “success” (HTTP 200 status). If the amperage passed was greater than what is supported by the charger, it will be set to the maximum which will be shown here.
</ResponseField>

<ResponseField name="status" type="string">
  If the request is successful, Smartcar will return a message (HTTP 200 status) containing the amperage set to be drawn from the vehicle.
</ResponseField>

<ResponseExample>
  ```json Example Response 
  {
    "message": "Successfully sent the following amperage: 48",
    "status": "success"
  }
  ```
</ResponseExample>


# Charge Schedule

POST /vehicles/{id}/{make}/charge/schedule
Sets the charging schedule for a vehicle.

<Snippet file="api-reference/note-bse-tesla.mdx" />

## Permission

`control_charge`

## Request

**Path**

<Snippet file="api-reference/path-bse.mdx" />

**Body**

<ParamField body="type" type="string" required>
  The type of schedule you want to set.

  <Expandable title="type" defaultOpen="true">
    <ResponseField name="START_TIME">
      When plugged in, the vehicle will delay starting a charging session until this time in `HH:mm`.
    </ResponseField>

    <ResponseField name="DEPARTURE_TIME">
      When plugged in, the vehicle may delay starting a charging session as long as it can reach its
      [charge limit](/api-reference/evs/get-charge-limit) by this time in `HH:mm`.
    </ResponseField>
  </Expandable>
</ParamField>

<ParamField body="enabled" type="boolean" required>
  Enables or disables the specified charging schedule.
</ParamField>

<ParamField body="time" type="string" required>
  The time for the provided schedule type in HH:mm.
</ParamField>

<RequestExample>
  ```curl cURL
  curl "https://api.smartcar.com/v2.0/vehicles/{id}/{make}/charge/schedule" \
  -H "Authorization: Bearer {token}" \
  -X "POST" \
  -H "Content-Type: application/json" \
  -d '{"type": "START_TIME", "enable": true, "time": "23:30"}'
  ```

  ```python Python
  chargeSchedule = vehicle.request(
    "POST", 
    "{make}/charge/schedule",
    {"type": "START_TIME", "enable": true, "time": "23:30"}
  )
  ```

  ```js Node
  const chargeSchedule = vehicle.request(
    "POST", 
    "{make}/charge/schedule",
    {"type": "START_TIME", "enable": true, "time": "23:30"}
  );
  ```

  ```java Java
  SmartcarVehicleRequest request = new SmartcarVehicleRequest.Builder()
        .method("POST")
        .path("{make}/charge/schedule")
        .addBodyParameter("type", "START_TIME")
        .addBodyParameter("enable", "true")
        .addBodyParameter("time", "23:30")
        .build();
  ChargeSchedule chargeSchedule = vehicle.request(request);
  ```

  ```ruby Ruby
  chargeSchedule = vehicle.request(
    "POST", 
    "{make}/charge/schedule",
    {"type": "START_TIME", "enable": true, "time": "23:30"}
  )
  ```
</RequestExample>

## Response

<ResponseField name="departureTime" type="object">
  The departure time configuration for the charging schedule.

  <Expandable title="departureTime">
    <ResponseField name="enabled" type="boolean">
      Indicates whether this schedule type is enabled or disabled.
      Only one of `departureTime` or `departureTime` can be enabled at a time.
    </ResponseField>

    <ResponseField name="time" type="string | null">
      When plugged in, the vehicle **may** delay starting a charging session as long as it can reach its
      [charge limit](/api-reference/evs/get-charge-limit) by this time in HH:mm.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="startTime" type="object">
  The start time configuration for the charging schedule.

  <Expandable title="startTime">
    <ResponseField name="enabled" type="boolean">
      Indicates whether this schedule type is enabled or disabled.
      Only one of `departureTime` or `departureTime` can be enabled at a time.
    </ResponseField>

    <ResponseField name="time" type="string | null">
      When plugged in, the vehicle will delay starting a charging session until this time in HH:mm.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json Example Response 
  {
    "departureTime": {
      "enabled": false,
      "time": null
    },
    "startTime": {
      "enabled": true,
      "time": "18:30"
    }
  }
  ```
</ResponseExample>


# Defroster

POST /vehicles/{id}/{make}/climate/defroster
Start or stop the front and rear defroster for a vehicle.

<Snippet file="api-reference/note-bse-tesla.mdx" />

## Permission

`control_climate`

## Request

**Path**

<Snippet file="api-reference/path-bse.mdx" />

**Body**

<ParamField body="action" type="string" required>
  Indicate whether to start or stop defrosting the vehicle.
  Options: `START` or `STOP`
</ParamField>

<RequestExample>
  ```curl cURL
  curl "https://api.smartcar.com/v2.0/vehicles/{id}/{make}/climate/defroster" \
  -H "Authorization: Bearer {token}" \
  -X "POST" \
  -H "Content-Type: application/json" \
  -d '{"action" : "STOP"}'
  ```

  ```python Python
  defroster = vehicle.request(
    "POST", 
    "{make}/climate/defroster", 
    {"action" : "STOP"}
  )
  ```

  ```js Node
  const defroster = vehicle.request(
    "POST", 
    "{make}/climate/defroster", 
    {"action" : "STOP"}
  );
  ```

  ```java Java
  SmartcarVehicleRequest request = new SmartcarVehicleRequest.Builder()
        .method("POST")
        .path("{make}/climate/defroster")
        .addBodyParameter("action" : "STOP")
        .build();
  VehicleResponse defroster = vehicle.request(request);
  ```

  ```ruby Ruby
  defroster = vehicle.request(
    "POST", 
    "{make}/climate/defroster", 
    {"action" : "STOP"}
  )
  ```
</RequestExample>

## Response

<ResponseField name="status" type="string">
  If the request is successful, Smartcar will return `status` containing the action sent to the
  climate defroster system of the vehicle.
</ResponseField>

<ResponseExample>
  ```json Example Response  
  {
    "status": "START"
  }
  ```
</ResponseExample>


# Set PIN to Drive

POST /vehicles/{id}/{make}/pin
Enables this feature on the vehicle and sets the PIN needed in order to drive it.

<Snippet file="api-reference/note-bse-tesla.mdx" />

## Permission

`control_pin`

## Request

**Path**

<Snippet file="api-reference/path-bse.mdx" />

**Body**

<ParamField body="pin" type="string" required>
  A four digit numeric PIN
</ParamField>

<RequestExample>
  ```curl cURL
  curl "https://api.smartcar.com/v2.0/vehicles/{id}/{make}/pin" \
  -H "Authorization: Bearer {token}" \
  -X "POST" \
  -H "Content-Type: application/json" \
  -d '{"pin" : "1234"}'
  ```

  ```python Python
  pin = vehicle.request(
    "POST", 
    "{make}/pin", 
    {"pin" : "1234"}
  )
  ```

  ```js Node
  const pin = vehicle.request(
    "POST", 
    "{make}/pin", 
    {"pin" : "1234"}
  );
  ```

  ```java Java
  SmartcarVehicleRequest request = new SmartcarVehicleRequest.Builder()
        .method("POST")
        .path("{make}/pin")
        .addBodyParameter("pin" : "1234")
        .build();
  VehicleResponse pin =  vehicle.request(request);
  ```

  ```ruby Ruby
  pin =  vehicle.request(
    "POST", 
    "{make}/pin", 
    {"pin" : "1234"}
  )
  ```
</RequestExample>

## Response

<ResponseField name="status" type="string">
  If the request is successful, Smartcar will return “success”.
</ResponseField>

<ResponseField name="message" type="string">
  If the request is successful, Smartcar will return a message.
</ResponseField>

<ResponseExample>
  ```json Example Response 
      {
          "message": "Successfully sent request to vehicle",
          "status": "success"
      }   
  ```
</ResponseExample>

## Notes

*   Calling this endpoint will override an existing PIN on the vehicle.
*   Call `DELETE` [PIN to Drive](/api-reference/tesla/clear-pin-to-drive) in order to enable this feature and set the PIN
*   Currently both owner and driver account types can set a PIN for the vehicle and enable the feature via the API.
*   Only account owners can disable this feature from the Tesla app.


# Steering Heater

POST /vehicles/{id}/{make}/climate/steering_wheel
Start or stop heating a vehicle's steering wheel.

<Snippet file="api-reference/note-bse-tesla.mdx" />

## Permission

`control_climate`

## Request

**Path**

<Snippet file="api-reference/path-bse.mdx" />

**Body**

<ParamField body="action" type="string" required>
  Indicate whether to start or stop heating the vehicle's steering wheel.
  Options: `START` or `STOP`
</ParamField>

<RequestExample>
  ```curl cURL
  curl "https://api.smartcar.com/v2.0/vehicles/{id}/{make}/climate/steering_wheel" \
  -H "Authorization: Bearer {token}" \
  -X "POST" \
  -H "Content-Type: application/json" \
  -d '{"action" : "STOP"}'
  ```

  ```python Python
  steering_wheel = vehicle.request(
    "POST", 
    "{make}/climate/steering_wheel", 
    {"action" : "STOP"}
  )
  ```

  ```js Node
  const steeringWheel = vehicle.request(
    "POST", 
    "{make}/climate/steering_wheel", 
    {"action" : "STOP"}
  );
  ```

  ```java Java
  SmartcarVehicleRequest request = new SmartcarVehicleRequest.Builder()
        .method("POST")
        .path("{make}/climate/steering_wheel")
        .addBodyParameter("action" : "STOP")
        .build();
  VehicleResponse steeringWheel =  vehicle.request(request);
  ```

  ```ruby Ruby
  steering_wheel =  vehicle.request(
    "POST", 
    "{make}/climate/steering_wheel", 
    {"action" : "STOP"}
  )
  ```
</RequestExample>

## Response

<ResponseField name="status" type="string">
  If the request is successful, Smartcar will return status containing the action sent to the vehicle.
  `UNAVAILABLE` indicates the vehicle is not equipped with a steering wheel heater.
</ResponseField>

<ResponseExample>
  ```json Example Response
  {
    "status": "START",
  }
  ```
</ResponseExample>


# User

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

This should be used as the static unique identifier for storing the access token and refresh token pair in your database.
Note: A single user can own multiple vehicles, and multiple users can own the same vehicle.

<Info>
  When using Single Select for Connect, a single user with multiple vehicles
  will have a 1:1 (`access_token`:`vehicle_id`) mapping.
</Info>

<RequestExample>
  <Snippet file="api-reference/core-sdk-methods/user.mdx" />
</RequestExample>

## Response

<ResponseField name="id" type="string">
  A user ID (UUID v4).
</ResponseField>

<ResponseExample>
  ```json Example Response
      {
          "id": "e0514ef4-5226-11e8-8c13-8f6e8f02e27e"
      }   
  ```
</ResponseExample>


# Callback URI Verification



<Info>
  This page covers the verification step **when first setting up a webhook** on Dashboard.
  Please see our [payload verification](/api-reference/webhooks/payload-verification) section for
  information on how to verify webhook payloads from vehicles.
</Info>

When you first set up a webhook on Dashboard, Smartcar will post a challenge request to ensure
we're sending payloads to the correct place. This is a **one time** event and will be in the following format:

```json verificationRequest.body
    {
        "version": "2.0",
        "webhookId": "<uuid>",
        "eventName": "verify",
        "payload": { "challenge": "<random-string>" }
    }
```

Upon receiving the request, your server will need respond to the challenge by hashing `payload.challenge` with your `application_management_token` to create a `SHA-256` based `HMAC`.

Return the hex-encoded hash as the value for `challenge` in your response body with a `200 status code`.

<Tip>
  Our [backend SDKs](/api-reference/api-sdks) have helper methods to generate the `HMAC`.
</Tip>

```json verificationResponse.body
{
    "status" : 200,
    "headers" : {
        "Content-Type": "application/json"
    },
    "body" : {
        "challenge" : "{HMAC}"
    }
}

```

<ResponseExample>
  ```python Python
      hmac = smartcar.hash_challenge(
              application_management_token, 
              payload.challenge
          )
  ```

  ```js Node
      let hmac = smartcar.hashChallenge(
          application_management_token, 
          payload.challenge
      ); 
  ```

  ```java Java
  String hmac =  Smartcar.hashChallenge(
              application_management_token, 
              payload.challenge
          );
  ```

  ```ruby Ruby
      hmac = Smartcar.hash_challenge(
          application_management_token, 
          payload.challenge
      )
  ```
</ResponseExample>


# Payload Verification



<Info>
  This page covers verification of payloads from vehicles.
  Please see our [callback verification](/api-reference/webhooks/callback-verification) section for
  information on how to initially verify your callback uri.
</Info>

Verify webhook payloads against the `SC-Signature` header and a `SHA-256` based `HMAC` generated by hashing
your `application_management_token` and the body.

<Tip>
  Our [backend SDKs](/api-reference/api-sdks) have helper methods that return `true` if the payload is good.
</Tip>

<CodeGroup>
  ```python Python
      Smartcar.verify_payload(
          {application_management_token},
          {SC-Signature}, 
          {webhook_body}
      )
  ```

  ```js Node
      smartcar.verify_payload(
          {application_management_token},
          {SC-Signature}, 
          {webhook_body}
      );
  ```

  ```java Java
      Smartcar.verifyPayload(
          {application_management_token},
          {SC-Signature}, 
          {webhook_body}
      );
  ```

  ```ruby Ruby
      Smartcar.verify_payload(
          {application_management_token},
          {SC-Signature}, 
          {webhook_body}
      )
  ```
</CodeGroup>


# Subscribe

POST /vehicles/{id}/webhooks/{webhook_id}
Subscribe a vehicle to a webhook.

## Request

**Path**

<Snippet file="api-reference/path-vehicle-id.mdx" />

<ParamField path="webhook_id" type="string" initialValue="9b6ae692-60cc-4b3e-89d8-71e7549cf805" required>
  The webhook id you are subscribing the vehicle to. This can be found in Dashboard under Webhooks.
</ParamField>

<Snippet file="code-group-subscribe.mdx" />

<RequestExample>
  <Snippet file="api-reference/core-sdk-methods/subscribe-webhook.mdx" />
</RequestExample>

## Response

<ResponseField name="vehicleId" type="string">
  The [vehicle id](/api-reference/all-vehicles) of the vehicle you are making a request to.
</ResponseField>

<ResponseField name="webhookId" type="string">
  The webhook id you are subscribing the vehicle to.
</ResponseField>

<ResponseExample>
  ```json ResponseExample
  {
      "vehicleId": "dc6ea99e-57d1-4e41-b129-27e7eb58713e",
      "webhookId": "9b6ae692-60cc-4b3e-89d8-71e7549cf805"
  }   
  ```
</ResponseExample>


# Unsubscribe

DELETE /vehicles/{id}/webhooks/{webhook_id}
Unsubscribe a vehicle from a webhook.

## Request

**Header**

<ParamField header="Authorization" type="string" initialValue="Bearer {application_management_token}" required>
  In the format `Bearer {application_management_token}`. You can find your `application_management_token` under
  your Application Configuration in Dashboard.
</ParamField>

**Path**

<Snippet file="api-reference/path-vehicle-id.mdx" />

<ParamField path="webhook_id" type="string" initialValue="9b6ae692-60cc-4b3e-89d8-71e7549cf805" required>
  The [webhook id](api-reference/management/all-vehicles) you are unsubscribing the vehicle from.
</ParamField>

<RequestExample>
  <Snippet file="api-reference/core-sdk-methods/unsubscribe-webhook.mdx" />
</RequestExample>

## Response

<ResponseField name="status" type="string">
  Status of the request.
</ResponseField>

<ResponseExample>
  ```json Example Response
  {
      "status": "success"
  }
  ```
</ResponseExample>


# 2022 Releases



## January 5, 2022

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

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

<CodeGroup>
  ```Node Node
  const amperage = vehicle.request('GET', 'tesla/charge/ammeter');
  ```

  ```Python Python
  amperage = vehicle.request("GET", "tesla/charge/ammeter")
  ```

  ```Java Java
  SmartcarVehicleRequest request = new SmartcarVehicleRequest.Builder()
    .method("GET")
    .path("tesla/charge/ammeter")
    .build();
  VehicleResponse amperage = vehicle.request(request);
  ```

  ```Ruby Ruby
  amperage = vehicle.request("GET", "tesla/charge/ammeter")
  ```
</CodeGroup>

## March 7, 2022

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

## 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:

```json
{
  "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"
  }
}
```

## 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).

## 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:

VEHICLE\_STATE:CHARGE\_FAULT

## June 8, 2022

Smartcar is now compatible with Nissan vehicles 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:

*   GET `/tesla/compass`
*   GET `/tesla/speedometer`

## August 24, 2022

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

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

## September 22, 2022

The following brand-specific endpoint is now available for Tesla vehicles in Canada, the United States, and our supported European countries:

*   <a href="/api-reference/tesla/get-charge-ammeter">POST /tesla/charge/ammeter</a>

## November 30, 2022

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

## December 29, 2022

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


# 2023 Releases



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

## 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:

[RATE\_LIMIT:VEHICLE](https://smartcar.com/docs/errors/v2.0/rate-limit/#vehicle)

## 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).

<Frame caption="Error Page">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/changelog/march14-2023-error-page.png" />
</Frame>

c. server\_error which is thrown if there is not another Connect error specified.

More documentation on error handling can be found [here](https://smartcar.com/docs/integration-guide/test-your-integration/test-errors/#1-connect-errors).

## March 6, 2023

The disconnect endpoint now supports the use of management API token (MAT) for authorization purposes. Documentation can be found [here](https://smartcar.com/docs/api#delete-disconnect)

## May 10, 2023

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

## June 7, 2023

Smartcar is now compatible with Hyundai vehicles in Canada.

## June 5, 2023

Test mode supports the following email format with any password to generate an account with multiple vehicles:

`<number>-vehicles@smartcar.com`

## July 26, 2023

The following brand-specific endpoints are now available for Tesla vehicles in Canada, the United States, and our supported European countries:

*   GET `/tesla/charge/records`
*   GET `/tesla/charge/records/billing`

## July 19, 2023

Smartcar is now compatible with Mercedes-Benz vehicles in our supported European countries.

## July 12, 2023

The following brand-specific endpoints are now available for Tesla vehicles in Canada, the United States, and our supported European countries:

*   GET `/tesla/charge/schedule`
*   POST ` /tesla/charge/schedule`
*   GET `/tesla/climate/cabin`
*   POST ` /tesla/climate/cabin`
*   GET `/tesla/climate/defroster`
*   POST ` /tesla/climate/defroster`
*   GET `/tesla/climate/steering_wheel`
*   POST ` /tesla/climate/steering_wheel`

## August 22, 2023

The following brand-specific endpoints are now available for Nissan vehicles in the United States:

*   GET /nissan/charge/schedule
*   PUT /nissan/charge/schedule

## August 17, 2023

The following endpoints are now available to manage vehicle connections:

*   GET Vehicle Connections
*   DELETE Vehicle Connections

## August 9, 2023

<img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/changelog/charge_schedule.png" />

The following brand-specific endpoints are now available for Ford and Lincoln vehicles in Canada, the United States, and our supported European countries:

*   GET ford/charge/schedule\_by\_location
*   PUT ford/charge/schedule\_by\_location
*   GET lincoln/charge/schedule\_by\_location
*   PUT lincoln/charge/schedule\_by\_location

## September 21, 2023

Introducing Vehicle Management! With this initial release you're able to see and manage
vehicles connected to your applications from within the [Smartcar Dashboard](https://dashboard.smartcar.com/login).

<Frame type="simple">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/changelog/vehicleMgmtDashboard.png" />
</Frame>

<br />

<br />

<sub>
  <sup>
    Logos and brand names are for identification purposes only and do not
    indicate endorsement of or affiliation with Smartcar.
  </sup>
</sub>

## September 19, 2023

[Charge Records](/api-reference/bmw/get-charge-records) is now available as a make specific endpoint for BMW and MINI in Canada, the United States, and our supported European countries.

## September 06, 2023

<img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/changelog/lock_status.png" />

Lock Status is now available as a Core endpoint and supported by the following makes:

*   Tesla (Global)
*   Ford (Global)
*   Kia (Global)
*   Jaguar (Global)
*   Land Rover (Global)
*   BMW (Global)
*   MINI (Global)
*   Lincoln (US)
*   Toyota (US)
*   Lexus (US)

In addition to the lock status of the vehicle, Smartcar will also return the open status of doors, sunroof, windows, based on what the vehicle supports.

## October 19, 2023

<Frame type="simple">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/changelog/charge_limit_bmw_mini.png" />
</Frame>

BMW and MINI EVs are now compatible with the following endpoints globally:

*   [Get Charge Limit](/api-reference/evs/get-charge-limit)
*   [Set Charge Limit](/api-reference/evs/set-charge-limit)

## October 5, 2023

<Frame type="simple">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/changelog/hyundai_eu.png" />
</Frame>

Smartcar is now compatible with Hyundai in supported European countries.

## October 3, 2023

<Frame type="simple">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/changelog/mazda_porsche_eu.png" />
</Frame>

Smartcar is now compatible with Mazda and Porsche in supported European countries.

## November 15, 2023

<Frame type="simple">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/changelog/cupra_eu.png" />
</Frame>

Smartcar is now compatible with CUPRA in supported European countries.


# April 2024 Releases



## April 25, 2024

<Frame type="simple">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/changelog/tesla-charge-battery.png" />
</Frame>

The following make specific endpoints are now available for Tesla across all supported regions:

*   [GET /tesla/charge](/api-reference/tesla/get-charge)
*   [GET /tesla/battery](/api-reference/tesla/get-battery)

### Additional Releases

Suggested user messages are now included as part of API error responses for you to easily surface resolution steps to vehicle owners. See our [error documentation](/errors/overview) for more details.

## April 9, 2024

<Frame type="simple">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/changelog/country-management.png" />
</Frame>

Country Management is now available for Connect! Easily manage what countries are enabled for your application on Dashboard.

### Additional Releases

The `user` parameter is now available when [building the Connect URL](/connect/redirect-to-connect) to pass a unique identifier for a vehicle owner to track and aggregate analytics across their Connect sessions for your application.


# August 2024 Releases



## August 19, 2024

Support for the following endpoints are now available for the MG brand in Europe:

*   [VIN](/api-reference/get-vin)
*   [Odometer](/api-reference/get-odometer)
*   [Lock Status](/api-reference/get-lock-status)
*   [Lock/Unlock](/api-reference/control-lock-unlock)
*   [Tire Pressure](/api-reference/get-tire-pressure)
*   [GET Charge Limit](/api-reference/get-charge-limit)
*   [POST Charge Limit](/api-reference/set-charge-limit)
*   [Battery Level](/api-reference/get-battery-level)
*   [Battery Capacity](/api-reference/get-battery-capacity)

## August 9, 2024

Smartcar is now compatible with the **Honda Prologue**, **Subaru Solterra** and the **Acura ZDX** in supported regions.

### Additional Releases

The following brands now support [Control Charge](/api-reference/control-charge), [Battery Level](/api-reference/get-battery-level), [Battery Capacity](/api-reference/evs/get-battery-capacity) and [Charge Status](/api-reference/get-charge-status):

*   Jeep, Fiat and Alfa Romeo (US, Canada and Europe)
*   Chevrolet, Cadillac and GMC (US and Canada)
*   RAM and Dodge (US and Canada)
*   Porsche (US and Europe)
*   Mazda (US and Europe)
*   Renault (Europe)
*   Nissan (Europe)

## August 6, 2024

Smartcar is now compatible with Dacia in Europe.

Support for the following endpoints are now available for the MG brand in Europe:

*   [Vehicle Info](/api-reference/get-vehicle-info)
*   [Location](/api-reference/get-location)
*   [Control Charge](/api-reference/control-charge)
*   [State of Charge](/api-reference/get-battery-level)
*   [Charging Status](/api-reference/get-charge-status)


# February 2024 Releases



## February 14, 2024

<Frame type="simple">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/changelog/subaru-us.png" />
</Frame>

Smartcar is now compatible with Subaru in the US.

### Additional Releases

The following endpoints are now available for Tesla vehicles globally:

*   [Control Charge Port](/api-reference/tesla/control-charge-port)
*   [Control Frunk](/api-reference/tesla/control-frunk)
*   [Control Trunk](/api-reference/tesla/control-trunk)

## February 8, 2024

<Frame type="simple">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/changelog/eu-fuel.png" />
</Frame>

The [GET /fuel](/api-reference/get-fuel-tank) endpoint is now available for the following brands in supported European countries:

| <div style={{ width:150 }} /> | <div style={{ width:150 }} /> | <div style={{ width:150 }} /> | <div style={{ width:150 }} /> |
| ----------------------------- | ----------------------------- | ----------------------------- | ----------------------------- |
| Audi                          | Hyundai                       | Mercedes-Benz                 | Skoda                         |
| BMW                           | Jaguar                        | MINI                          | Vauxhall                      |
| Citroen                       | Kia                           | Opel                          | Volkswagen                    |
| DS                            | Land Rover                    | Peugeot                       | Volvo                         |
| Ford                          | Mazda                         | Renault                       |                               |


# July 2024 Releases



## July 31, 2024

Connect Insights is now available!

<Frame type="simple">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/changelog/connect-insights.png" />
</Frame>

*   Each Connect flow launched for the previous two weeks is available in the Smartcar Dashboard with a variety of ways to search for specific Connect launches.
*   Enterprise customers have access to funnel analysis so they can understand their conversion rates in the Connect flow.

## July 30, 2024

Test and Simulated mode have been combined into a singular mode; Simulated.

If a simulated vehicle is enabled, we will return data following the selected trip. If the simulated vehicle doesn't support the requested endpoint, randomized data will be returned.

If no simulated vehicle is enabled for, we will return data as if a simulated vehicle with "Day Commute" was selected. If the simuday commute doesn't support the requested endpoint, randomized data will be returned.

## July 25, 2024

The Smartcar Dashboard now supports Google authentication.

## July 3, 2024

The following endpoints are now available for Tesla:

*   [Get User Info](/api-reference/tesla/get-user-info)
*   [Get User access](/api-reference/tesla/get-user-access)


# June 2024 Releases



## June 24, 2024

<Frame type="simple">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/changelog/dynamic-brand-filtering.png" />
</Frame>

You can now customize which bands show up in Connect from the [Dashboard](https://dashboard.smartcar.com/). Easily manage which brands your users can connect to based on engine type or endpoint.

## June 20, 2024

The following Brand Specific Endpoint is now available for Audi:

*   [Get Charge Status](/api-reference/audi/get-charge)

## June 5, 2024

The following endpoints are now available for Audi:

*   [Get Charge Limit](/api-reference/evs/get-charge-limit)
*   [Set Charge Limit](/api-reference/evs/set-charge-limit)
*   [Control Charge](/api-reference/evs/control-charge)
*   [Lock Status](/api-reference/get-lock-status)


# March 2024 Releases



## March 6, 2024

<Frame type="simple">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/changelog/moo.png" />
</Frame>

Organization access for Teams is now available on Dashboard. Check out our docs page on [Teams](/help/teams) for details.

### Additional Releases

The following endpoint is now available for Tesla vehicles globally:

*   [Virtual Key Status](/api-reference/tesla/get-virtual-key-status)


# May 2024 Releases



## May 10, 2024

The following endpoint is now available for Ford, Lincoln, Toyota, Lexus, Mazda and Volkswagen (US) vehicles:

*   [GET /service/history](/api-reference/get-service-records)

## May 8, 2024

The following make specific endpoint is now available for Tesla across all supported regions:

*   [GET /tesla/alerts](/api-reference/tesla/get-alerts)


# October 2024 Releases



## October 8, 2024

The Smartcar Dashboard now indicates which vehicles are subscribed to webhooks through the main Vehicles table.

## October 10, 2024

The Smartcar Dashboard now indicates which webhooks a vehicle is  subscribed to. From the Vehicles table, click into the three dot menu to view vehicle details. From here, navigate to the new Webhooks tab!


# September 2024 Releases



## September 25, 2024

[Dynamic Webhooks](/getting-started/tutorials/webhooks-dynamic) are now in early access for Enterprise customers! Please request access from the Webhooks tab on the Smartcar Dashboard!

## September 30, 2024

[Multi-Factor Authentication](/getting-started/dashboard-mfa) is available to offer an additional layer of security for the Smartcar Dashboard.


# Latest Releases



## November 1, 2024

A new [System Status](https://smartcar.com/docs/api-reference/get-system-status) endpoint is available for early access. This endpoint returns a list of vehicle components and their health state for FCA and GM makes.

## November 5, 2024

Ford's authentication process has been updated to require the use of SDKs. Our [Connect SDKs](https://smartcar.com/docs/connect/connect-sdks) have been updated to redirect to Ford's site to handle the authentication process when the user logs in.


# Country Selection

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.

You can override this behaviour by passing a country feature flag in your Connect URL in the form `country:{country_code}`.

Your feature flag should contain the [two-character ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)
of the country that your user is located in.

<Tip>
  Our SDKs provide ways for you to add this as part of the the various `authUrlBuilder` or `getAuthUrl` methods.
</Tip>

```plaintext Connect URL w/ country feature flag
https://connect.smartcar.com/oauth/authorize?
response_type=code
&client_id=8229df9f-91a0-4ff0-a1ae-a1f38ee24d07
&scope=read_odometer read_vehicle_info
&redirect_uri=https://example.com/home
&flags=country:GB
```

Alternatively, your users can manually change their country and language on Connect's preamble screen:

<Frame caption="Country selector dropdown on the Preamble screen in Connect" type="simple">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/connect/countrySelector.png" />
</Frame>


# Connect Flows

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.

<Tabs>
  <Tab title="Default" defaultOpen="true">
    When you launch Connect, users will be able to select the brand of their vehicle from a list before they enter their credentials and grant access to your application.

    <Frame caption="Default Smartcar Connect Flow">
      <img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/default-connect-flow.png" />
    </Frame>
  </Tab>

  <Tab title="Authorizing a Single Vehicle">
    In some cases you may only want to connect to a single vehicle, even if there are more than one on your user's connected services account. Smartcar provides two ways for you to do this:

    *   Single Select
    *   Single Select with VIN

    ### Single Select

    Limits the user's selection on the permissions screen to a single car if there are multiple vehicles on their connected services account. Notice that check-boxes turn into radio buttons, and the call to action wording changes slightly.

    <Frame caption="Grant Screen - Single Select without VIN">
      <img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/single-selection.png" />
    </Frame>

    To enable Single Select, you can pass `single_select=true` as URL parameter when launching Smartcar Connect.

    ### Single Select with VIN

    In addition, if you know the user’s VIN ahead of time you can pass this over to us in the connect URL. In doing so:

    1.  Smartcar  decodes the VIN to get the brand and send the user to the appropriate login form directly
    2.  If the owner has more than one vehicle on their connected services account, we’ll only show the VIN that was passed to us on the permission grant screen.

    <Frame caption="Single Select /w VIN: Preamble > Brand’s Login Form > Grant Screen  - no vehicle choice">
      <img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/single-select.png" />
    </Frame>

    To enable Single Select with VIN, you can pass `single_select=true` and `single_select_vin=true` as URL parameters when launching Smartcar Connect.
  </Tab>

  <Tab title="Bypassing the Brand Selection Screen">
    ### Brand Select

    Instead of having users go through the brand selector screen, you can pass us a brand in the Connect URL and send the user to the appropriate login form directly  .

    <Frame caption="Brand Select">
      <img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/brand-select.png" />
    </Frame>

    To enable Brand Select, you can pass `make` as URL parameter when launching Connect. For example, `make=TESLA`
  </Tab>
</Tabs>


# Modes



<Tip>
  If no mode is specified, Connect will launch in `live` mode by default.
</Tip>

| Mode      | Description                                                                                                          |
| --------- | -------------------------------------------------------------------------------------------------------------------- |
| live      | Launches Connect in live mode allowing a user to login in with a real connected services account.                    |
| simulated | Launches Connect in simulated mode allowing developer to connect to vehicles created on Dashboard via the Simulator. |


# Auth Code Exchange



To interact with the Smartcar API, you will need to exchange your authorization code for an access token. The authorization code represents a user’s consent, but cannot be used to make requests to a vehicle. Instead, it must be exchanged for an access token. An example request is provided to the right.

<Snippet file="authorization/auth-code-exchange.mdx" />


# SDKs for Connect

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

For mobile or single page web apps, you can use one of our frontend SDKs. Please note that our frontend SDKs only handle
integrating Connect into your application. You will still need to use a backend SDK to manage tokens and make API requests to vehicles.

<Snippet file="sdks/connect-sdk-card-group.mdx" />

For server-side rendered applications, you can use one of our backend SDKs:

<Snippet file="sdks/api-sdk-card-group.mdx" />

<br />

<Tip>
  Don't see an SDK for your language? No problem!
  As long as you can build a URL and handle http requests, you're good to go.
</Tip>


# Dashboard Configuration



## Registration

To get started, register your application with Smartcar by navigating to our [dashboard](https://dashboard.smartcar.com/login).

After registration, your application will be assigned a `CLIENT_ID` and a `CLIENT_SECRET`. The `CLIENT_SECRET` must be kept safe and used only in exchanges between your application’s server and Smartcar’s <Tooltip tip="https://connect.smartcar.com">authorization server</Tooltip>.

## Redirect URIs

To authorize with Smartcar, you’ll need to provide one or more redirect URIs. The user will be redirected to the specified URI upon authorization. On redirect, the URI will contain an authorization `code` query parameter that must be exchanged with Smartcar’s authorization server for an `ACCESS_TOKEN`.

The redirect URIs must match one of the following formats:

| Protocol       | Format                                                                                   | Example                                                                        |
| -------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| HTTP           | a localhost URI with protocol `http://`                                                  | `http://localhost:8000`                                                        |
| HTTPS          | a URI with protocol `https://`                                                           | `https://myapplication.com`                                                    |
| JavaScript SDK | `https://javascript-sdk.smartcar.com/v2/redirect?app_origin={localhost-or-HTTPS-origin}` | `https://javascript-sdk.smartcar.com/v2/redirect?app_origin=https://myapp.com` |
| Custom-scheme  | `sc{clientId}://{hostname-with-optional-path-component-or-TLD}`                          | `sc4a1b01e5-0497-417c-a30e-6df6ba33ba46://callback`                            |

<Note>HTTP is allowed only for testing purposes on localhost</Note>

### Javascript SDK

The JavaScript SDK redirect is used along with the JavaScript SDK library. For more details and examples on the redirect usage, see the [SDK documentation](https://github.com/smartcar/javascript-sdk).

### Custom-scheme

Custom-scheme URIs are used for mobile applications. They must begin with `sc{clientId}` and can have an optional path or TLD. See the OAuth reference on redirect URIs.


# Handle the Response

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 parameter. In the case of on error, we'll provide an error and description as parameters instead.

## Success

<ResponseField name="code">
  An authorization code used to obtain your initial `ACCESS_TOKEN`. The auth `code` expires after **10 minutes**.
</ResponseField>

<Snippet file="response-connect-state.mdx" />

```http Success
HTTP/1.1 302 Found
Location: https://example.com/home?
code=90abecb6-e7ab-4b85-864a-e1c8bf67f2ad
&state=0facda3319
```

## Error

For a detailed description of these errors, please see our [errors page](/errors/overview).

<ResponseField name="error">
  The type of error
</ResponseField>

<ResponseField name="error_description">
  A detailed description of what caused the error
</ResponseField>

<Snippet file="response-connect-state.mdx" />

```http Error
HTTP/1.1 302 Found
Location: https://example.com/home?
error=access_denied
&error_description=User+denied+access+to+application.
&state=0facda3319
```

<Info>
  In addition to the error code and description, Smartcar will return the following parameters when a
  user tries to authorize an incompatible vehicle in Connect.
</Info>

<ResponseField name="vin">
  Can be returned for errors where the vehicle is incompatible.
</ResponseField>

<ResponseField name="make">
  The manufacturer of the vehicle.
</ResponseField>

<ResponseField name="model">
  The model of the vehicle.
</ResponseField>

<ResponseField name="year">
  The year of production of the vehicle.
</ResponseField>


# Handle the Response

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.

## Success

<ResponseField name="vehicle_id">
  Unique identifier for a vehicle on Smartcar’s platform.
</ResponseField>

<Snippet file="response-connect-state.mdx" />

```http Success
HTTP/1.1 302 Found
Location: https://example.com/home?
vehicle_id=sc4a1b01e5-0497-417c-a30e-6df6ba33ba46
&state=0facda3319
```

## Error

For a detailed description of these errors, please see our [errors page](/errors/overview).

<ResponseField name="error">
  The type of error
</ResponseField>

<ResponseField name="error_description">
  A detailed description of what caused the error
</ResponseField>

<Snippet file="response-connect-state.mdx" />

```http Error
HTTP/1.1 302 Found
Location: https://example.com/home?
error=access_denied
&error_description=User+denied+access+to+application.
&state=0facda3319
```


# Redirect to Connect



There will be times when a user updates credentials to their connected services account. When this happens, the user will need to go through Connect
again to update your authorization through Smartcar.

You can do this with a streamlined Connect flow using a special re-auth URL with the parameters below.

<Tip>
  The [`AUTHENTICATION_FAILED`]() API error contains a partially constructed re-authentication URL in the `resolution.url` field.
</Tip>

<br />

<ParamField path="client_id" type="string" required>
  The application’s unique identifier.
</ParamField>

<ParamField path="redirect_uri" type="string" required>
  The URI a user will be redirected to after authorization. This value **must** match one of the redirect URIs set in the credentials tab of the dashboard.
</ParamField>

<ParamField path="response_type" type="string" required>
  This value must be set to `vehicle_id`.
</ParamField>

<ParamField path="vehicle_id" type="string" required>
  The id of the vehicle you are reauthenticating.
</ParamField>

<ParamField path="state" type="string">
  An optional value included as a query parameter in the redirect\_uri back to your application. This value is often used to identify a user and/or prevent cross-site request forgery
</ParamField>

<ParamField query="user" type="string">
  Specify a unique identifier for the vehicle owner to track and aggregate analytics across Connect sessions for each vehicle owner on Dashboard.

  Note: Use the `state` parameter in order to identify the user at your callback URI when receiving an authorization or error code after the user exits the Connect flow.
</ParamField>

<RequestExample>
  ```http Connect URL Example
  HTTP/1.1 302 Found
  Location: https://connect.smartcar.com/oauth/reauthenticate?
    response_type=vehicle_id
    &client_id=8229df9f-91a0-4ff0-a1ae-a1f38ee24d07
    &vehicle_id=sc4a1b01e5-0497-417c-a30e-6df6ba33ba46
    &redirect_uri=https://example.com/home
    &state=0facda3319
  ```
</RequestExample>


# Build the Connect URL



Construct the Smartcar Connect redirect with the parameters below. Launching this link will send users through the Smartcar Connect flow.

<Tip>
  For mobile or single-page web applications you can use one of our [frontend SDKs](/connect/connect-sdks), or for server-side rendered applications you can use one of
  our [backend SDKs](/connect/connect-sdks). Alternatively, you can build the Connect URL manually.
</Tip>

<br />

{/* <Tip>
  You can use the `required:` prefix for `permissions` in the `scope` parameter to help filter out vehicles 
  on your users connected services account. You can read more [here](/api-reference/permissions#required-permissions).
</Tip> */}

<ParamField query="client_id" type="string" required>
  The application’s unique identifier. This is available on the credentials tab of the dashboard
</ParamField>

<ParamField query="redirect_uri" type="string" required>
  The URI a user will be redirected to after authorization. This value must match one of the redirect URIs set in the credentials tab of the dashboard
</ParamField>

<ParamField query="response_type" type="string" required>
  This value must be set to `code`. OAuth2 outlines multiple authorization types. Smartcar Connect utilizes the “Authorization Code” flow.
</ParamField>

<ParamField query="scope" type="[permissions]" required>
  A space-separated list of permissions that your application is requesting access to. The valid permission names can be found in the permissions section. A permission is optional by default. It can be made required by adding the required: prefix to the permission name, e.g. required:read\_odometer. Please refer to the integration guide in our docs for more information.
</ParamField>

<ParamField query="state" type="string">
  An optional value included as a query parameter in the `REDIRECT_URI` back to your application. This value is often used to identify a user and/or prevent cross-site request forgery
</ParamField>

<ParamField query="approval_prompt" default="auto" type="string">
  An optional value that sets the behavior of the approval dialog displayed to the user.
  Defaults to `auto` and will only display the approval dialog if the user has not previously approved the scope.
  Set this to `force` to ensure the approval dialog is always shown to the user even if they have previously approved the same scope.
</ParamField>

<ParamField query="mode" default="live" type="ENUM">
  <Expandable title="modes" defaultOpen="true">
    <ResponseField name="simulated" type="string">
      Simulated mode lets you make requests to a vehicle created using the Vehicle Simulator to receive realistic responses from specific makes, models, years, and various states of the vehicle.

      Should the selected simulator not support the desired endpoint randomized data will be returned instead.
    </ResponseField>

    <ResponseField name="live" type="string">
      Live mode should be used when connecting to a real vehicle.
    </ResponseField>
  </Expandable>
</ParamField>

<ParamField query="make" type="string">
  Allows users to bypass the Brand Selector screen. Valid `makes` can be found in the [makes](/api-reference/makes) section on API reference.
  The `single_select_vin` parameter takes precedence over this parameter.
</ParamField>

<ParamField query="single_select" type="bool" default="false">
  Sets the vehicle selection behavior of the grant dialog. If set to true, then the user is only allowed to select a single vehicle. Please refer to the Single Select section for more information.
</ParamField>

<ParamField query="single_select_vin" type="string">
  Sets the behavior of the permissions screen in Smartcar Connect.
  When using `single_select_vin`, you need to pass in the VIN (Vehicle Identification Number) of a specific vehicle into the `single_select_vin` parameter.
  Additionally, you need to set the `single_select` parameter to `true`.
  Smartcar Connect will then let the user authorize **only the vehicle with that specific VIN**.
  The `single_select_vin` parameter takes precedence over the `make` parameter.
  Please refer to the Single Select section for more information.
</ParamField>

<ParamField query="flags" type="[flags]">
  A space separated list of feature flags in the form `{flag}:{value}`.

  <Expandable title="flags">
    <ResponseField name="country" type="ENUM">
      The two-character ISO country code of the country that your user is located in. You can set the default country for Connect on Dashboard

      If no flag is passed or set as default on Dashboard, Smartcar will use the devices IP to set an appropriate country.

      This flag determines what brands are listed on the Brand Selector screen in Connect e.g. Renault is available in Europe, but not the US.
    </ResponseField>
  </Expandable>
</ParamField>

<ParamField query="remember_creds" type="bool">
  Disable remembering a user's authorization on subsequent login sessions. This feature is enabled by default and can only be disabled (by setting the parameter to false) in simulated mode.
</ParamField>

<ParamField query="user" type="string">
  Specify a unique identifier for the vehicle owner to track and aggregate analytics across Connect sessions for each vehicle owner on Dashboard.

  Note: Use the `state` parameter in order to identify the user at your callback URI when receiving an authorization or error code after the user exits the Connect flow.
</ParamField>

<RequestExample>
  ```http Example Connect URL
  HTTP/1.1 302 Found
  Location: https://connect.smartcar.com/oauth/authorize?
  response_type=code
  &client_id=8229df9f-91a0-4ff0-a1ae-a1f38ee24d07
  &scope=read_odometer read_vehicle_info read_location
  &redirect_uri=https://example.com/home
  &state=0facda3319
  ```
</RequestExample>


# Overview

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

## Storing access tokens

### Default and Brand Select Connect Flow

By default tokens are scoped to the user's connceted services account.

<Note>This means that if there are multiple vehicles
on the account - and they are selected at the time of authorization, the access token is valid for all those vehicle Ids.</Note>

To manage this, we recommend using the [Smartcar User Id](/api-reference/management/user) to link tokens to your corresponding user id. The diagram below
will also allow multiple users to connect to vehicles on the same account.

<Frame type="simple">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/connect/StandardFlowDBDiagram.png" />
</Frame>

### Single Select Connect Flow

When using the Single Select flow, tokens are strictly scoped to the vehicle that was authorized for that Connect session.
This means that if a user connects multiple vehicles under the same connected services account, each vehicle id will be tied
to its own set of tokens.

<Frame type="simple">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/connect/ConnectMatchDBDiagram.png" />
</Frame>

## Token expiry

Access tokens are valid for 2 hours, while refresh tokens are valid for 60 days. You can use the corresponding refresh token to fetch a new token pair
once an access token has expired.

In order to maintain access to a vehicle without having a user go through Connect again, you'll want to make sure the refresh token never expires.
Whenever you fetch a new token pair, we will return a **new access and refresh token**.

Prior to expiry, access tokens will remain valid until their expiry when fetching a new token pair. Refresh tokens on the other hand are invalidated
1 minute after they're used.

To avoid common 401 Authentication errors, please ensure you are **persisting both the access and refresh token** we return whenever you fetch a new pair.

<Tip>
  In addition to any logic that checks access token expiry when making an API request, we strongly recommend having another job that periodically
  checks for refresh tokens that are close to expiry and refreshes them.
</Tip>


# Refreshing Refresh Tokens

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

Depending on your application logic, there may be cases where you don't end up fetching a fresh access token for more than 60 days.
If this is the case, you should fetch a new token pair before the 60 days are up so the user doesn’t need to go through Connect again.

This will give you a newly minted access token **and** refresh token.

<Snippet file="authorization/token-exchange.mdx" />


# Refreshing Access Tokens

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

<Snippet file="authorization/token-exchange.mdx" />


# What is Connect?



Smartcar Connect is the fastest and most transparent way to collect user consent. Before you can make API requests to a car, your customer needs to link the vehicle to your app. It’s a simple process for your users to enroll their vehicles:

1.  Select the car brand
2.  Sign in
3.  Give consent

<Frame caption="Default Smartcar Connect Flow">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/default-connect-flow.png" />
</Frame>

From your app, you'll [redirect your users to Connect](/connect/redirect-to-connect), and [handle the response](/connect/handle-the-response) once the user completes or exits the Connect flow. You'll receive a `code` that you'll use to [exchange](/connect/auth-code-exchange) for an access token to start making requests to their vehicle(s).

We have designed Connect in compliance with the OAuth2 authorization protocol, safely handling all user information.

Connect comes with robust configurations to fit your needs and frontend [SDKs](/connect/connect-sdks) for faster integration.


# Authentication Errors

Thrown when there is an issue with your authorization header.

# `NULL`

The authorization header is missing or malformed, or it contains invalid or expired authentication credentials (e.g. access token, client ID, client secret). Please check for missing parameters, spelling and casing mistakes, and other syntax issues.

```json
{
  "type": "AUTHENTICATION",
  "code": null,
  "description": "The authorization header is missing or malformed, or it contains invalid or expired authentication credentials. Please check for missing parameters, spelling and casing mistakes, and other syntax issues.",
  "docURL": "https://smartcar.com/docs/errors/api-errors/authentication-errors",
  "statusCode": 401,
  "requestId": "5dea93a1-3f79-4246-90c5-89610a20471b",
  "resolution": { "type": null } 
}
```

### Suggested Resolution

You can resolve this error by referring to our API reference and ensuring that you pass all the parameters as specified. If you are certain that your request is well-formed, please try refreshing your access token.

### Troubleshooting Steps

Refer to our API reference and ensure that you use the correct authentication mechanism for your request

*   Check constants like Bearer and Basic for spelling mistakes.
*   If you make a request to a vehicle endpoint, verify that your access token grants you access to the correct vehicle. You can do so by making a request to the /vehicles endpoint and ensuring that the correct vehicle ID is included in the returned response.
*   If you have refreshed your access token, make sure that it persists and that you use your new token to make your request.


# Billing Errors

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

# `VEHICLE_LIMIT`

You have exceeded your active vehicle limit for the current billing period. Please log in to the [Smartcar dashboard](https://dashboard.smartcar.com/login)
and visit the Billing tab to learn more.

```json VEHICLE_LIMIT
{
  "type": "BILLING",
  "code": "VEHICLE_LIMIT",
  "description": "You have exceeded your active vehicle limit for the current billing period. Please log into the Smartcar dashboard and visit the Billing tab to learn more.",
  "docURL": "https://smartcar.com/docs/errors/api-errors/billing-errors#vehicle-limit",
  "statusCode": 430,
  "requestId": "5dea93a1-3f79-4246-90c5-89610a20471b",
  "resolution": { "type": "CONTACT_SUPPORT" },
}
```

### Troubleshooting Steps

To resolve this error, please [contact us](mailto:support@smartcar.com) to upgrade your plan and increase your vehicle limit.
Please note that you won’t be able to make requests to additional vehicles until the end of the current billing period or until you have upgraded your plan.

# `INVALID_PLAN`

The feature you are trying to use is not included in your current pricing plan. Please visit our pricing page to learn more about our plans and features.

```json INVALID_PLAN
{
  "type": "BILLING",
  "code": "INVALID_PLAN",
  "description": "The feature you are trying to use is not included in your current pricing plan. Please visit our pricing page to learn more about our plans and features.",
  "docURL": "https://smartcar.com/docs/errors/api-errors/billing-errors#invalid-plan",
  "statusCode": 430,
  "requestId": "5dea93a1-3f79-4246-90c5-89610a20471b",
  "resolution": { "type": "CONTACT_SUPPORT" } 
}
```

### Troubleshooting Steps

If you have checked our pricing page and believe that the feature you are trying to use is included in your plan,
please [contact us](mailto:support@smartcar.com) and we’ll be happy to assist you.

# `VEHICLE_REQUEST_LIMIT`

You have exceeded the number of API requests that are allowed for **this** vehicle in the current billing period.
Please log in to the [Smartcar dashboard](https://dashboard.smartcar.com/login) and visit the Billing tab to learn more.

```json VEHICLE_REQUEST_LIMIT
{
  "type": "BILLING",
  "code": "VEHICLE_REQUEST_LIMIT",
  "description": "You have exceeded the number of API requests that are allowed for this vehicle in the current billing period. Please log into the Smartcar dashboard and visit the Billing tab to learn more.",
  "docURL": "https://smartcar.com/docs/errors/api-errors/billing-errors#vehicle-request-limit",
  "statusCode": 430,
  "requestId": "5dea93a1-3f79-4246-90c5-89610a20471b",
  "resolution": { "type": "CONTACT_SUPPORT" } 
}
```

### Troubleshooting Steps

To resolve this error, please [contact us](mailto:support@smartcar.com) to upgrade your plan and increase your vehicle limit.
Please note that you won’t be able to make additional requests to this vehicle until the end of the current billing period or until you have upgraded your plan.

# `ACCOUNT_SUSPENDED`

Your Smartcar account is past due and has been suspended.
Please reach out to our finance team to resolve this issue.

```json ACCOUNT_SUSPENDED
{
  "type": "BILLING",
  "code": "ACCOUNT_SUSPENDED",
  "description": "Your Smartcar account is past due and has been suspended. Please reach out to our finance team to resolve this issue.",
  "docURL": "https://smartcar.com/docs/errors/api-errors/billing-errors#account-suspended",
  "statusCode": 430,
  "requestId": "5dea93a1-3f79-4246-90c5-89610a20882a",
  "resolution": { "type": "FINANCE" } 
}
```

### Troubleshooting Steps

To resolve this error, please [contact us](mailto:finance@smartcar.com) to pay past due invoices.
Please note that you won’t be able to make any requests until you have resolved this issue.


# Compatibility Errors

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

# `MAKE_NOT_COMPATIBLE`

Smartcar is not yet compatible with this vehicle’s make in the country you specified.

```json
{
  "type": "COMPATIBILITY",
  "code": "MAKE_NOT_COMPATIBLE",
  "description": "Smartcar is not yet compatible with this vehicle’s make in the country you specified.",
  "docURL": "https://smartcar.com/docs/errors/api-errors/compatibility-errors#make-not-compatible",
  "statusCode": 501,
  "requestId": "5dea93a1-3f79-4246-90c5-89610a20471b",
  "resolution": { "type": null } 
}
```

**Suggested User Messaging**<br />
`<your app name>` is not yet able to connect to your car brand.

<br />

# `PLATFORM_NOT_CAPABLE`

You're connected to the vehicle using an OEM integration that does not support this endpoint. This can be a result of the OEM migrating to a newer API or requiring vehicle owners to migrate to a new application they have released.

```json
{
  "type": "COMPATIBILITY",
  "code": "PLATFORM_NOT_CAPABLE",
  "description": "You're connected to the vehicle using an OEM integration that does not support this endpoint.",
  "docURL": "https://smartcar.com/docs/errors/api-errors/compatibility-errors#platform-not-capable",
  "statusCode": 501,
  "requestId": "5dea93a1-3f79-4246-90c5-89610a20471b",
  "resolution": { "type": "REAUTHENTICATE" } 
}
```

**Troubleshooting Steps**<br />
For Tesla vehicles please have the owner re-authenticate using the latest Tesla authorization flow.

<br />

# `SMARTCAR_NOT_CAPABLE`

Smartcar does not yet support this feature for this vehicle.

```json
{
  "type": "COMPATIBILITY",
  "code": "SMARTCAR_NOT_CAPABLE",
  "description": "Smartcar does not yet support this feature for this vehicle.",
  "docURL": "https://smartcar.com/docs/errors/api-errors/compatibility-errors#smartcar-not-capable",
  "statusCode": 501,
  "requestId": "5dea93a1-3f79-4246-90c5-89610a20471b",
  "resolution": { "type": null } 
}
```

**Troubleshooting Steps**<br />
Please check that the vehicles make and engine type support the feature you are trying to use.

Please contact us to learn when this feature will become available.
If you have a vehicle that supports this feature and would like to help out, check out Smartcar’s Research Fleet.

<br />

# `VEHICLE_NOT_CAPABLE`

This error occurs when a physical limitation makes the vehicle incapable of performing your request
(e.g. battery electric vehicles are incapable of responding to read fuel requests).

```json
{
  "type": "COMPATIBILITY",
  "code": "VEHICLE_NOT_CAPABLE",
  "description": "The vehicle is incapable of performing your request.",
  "docURL": "https://smartcar.com/docs/errors/api-errors/compatibility-errors#vehicle-not-capable",
  "statusCode": 501,
  "requestId": "5dea93a1-3f79-4246-90c5-89610a20471b",
  "resolution": { "type": null } 
}
```

**Suggested User Messaging**<br />
Your car is unable to perform this request.

<br />


# Connected Services Account Errors

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

# `ACCOUNT_ISSUE`

Action needed in the user’s connected services account. The user needs to log in and complete an outstanding task in their connected services account.

Examples:

*   The user needs to accept the connected services app’s Terms of Service.
*   The user has created but not yet fully activated their connected services account.
*   If you've received this error while testing with Vehicle Simulator, it likely means a simulation has not been started for the vehicle. Visit the Simulator tab in the Smartcar Dashboard to start a simulation for the vehicle.

```json
{
  "type": "CONNECTED_SERVICES_ACCOUNT",
  "code": "ACCOUNT_ISSUE",
  "description": "Action needed in the user’s connected services account. Please prompt the user to log into their connected services account and complete any outstanding tasks.",
  "docURL": "https://smartcar.com/docs/errors/api-errors/connected-service-errors#account-issue",
  "statusCode": 400,
  "requestId": "5dea93a1-3f79-4246-90c5-89610a20471b",
  "resolution": { "type": null },
  "suggestedUserMessage": "Action required in your connected services account. Please log into your connected services app or web portal and complete any outstanding tasks (e.g. finish activating your account or accept the Terms of Service)." 
}
```

### Suggested resolution

The user can resolve this error by logging into their connected services account and completing any outstanding tasks.

### Troubleshooting steps

*   Prompt the user to log into their connected services account using the app or web portal.
*   Prompt the user to try triggering an action on their car, e.g. locking the doors or flashing the lights.
*   At this point, the app should prompt the user to complete their outstanding task.

### Suggested user message

> Action required in your connected services account. Please log into your connected services app or web portal and complete any outstanding tasks (e.g. finish activating your account or accept the Terms of Service).

***

# `AUTHENTICATION_FAILED`

Smartcar was unable to authenticate with the user’s connected services account. This error usually occurs when the user has updated their connected
services account credentials and not yet re-authenticated in Smartcar Connect. The user should re-authenticate using Smartcar Connect.

```json
{
  "type": "CONNECTED_SERVICES_ACCOUNT",
  "code": "AUTHENTICATION_FAILED",
  "description": "Smartcar was unable to authenticate with the user’s connected services account. Please prompt the user to re-authenticate using Smartcar Connect.",
  "docURL": "https://smartcar.com/docs/errors/api-errors/connected-service-errors#authentication-failed",
  "statusCode": 400,
  "requestId": "5dea93a1-3f79-4246-90c5-89610a20471b",
  "resolution": { 
    "type":  "REAUTHENTICATE", 
    "url": "https://connect.smartcar.com/oauth/reauthenticate?response_type=vehicle_id&client_id=8229df9f-91a0-4ff0-a1ae-a1f38ee24d07&vehicle_id=sc4a1b01e5-0497-417c-a30e-6df6ba33ba46",
  } 
  "suggestedUserMessage": "Your car got disconnected from <app name>. Please use this link to re-connect your car: <link to Smartcar Connect>."
}
```

### Suggested resolution

Please provide the user with a link to Smartcar Connect Re-authentication and prompt them to re-connect their vehicle.
The resolution field contains a partially constructed URL for Smartcar Connect Re-authentication, please see the API reference for more detail.

### Suggested user message

> Your car got disconnected from \<app name>. Please use this link to re-connect your car: \<link to Smartcar Connect>.

***

# `NO_VEHICLES`

No vehicles found in the user’s connected services account. The user might not yet have added their vehicle to their account, or they might not yet have activated connected services for the vehicle.

```json
{
  "type": "CONNECTED_SERVICES_ACCOUNT",
  "code": "NO_VEHICLES",
  "description": "No vehicles found in the user’s connected services account. Please prompt the user to add their vehicle to their connected services account and re-authenticate using Smartcar Connect.",
  "docURL": "https://smartcar.com/docs/errors/api-errors/connected-service-errors#no-vehicles",
  "statusCode": 400,
  "requestId": "5dea93a1-3f79-4246-90c5-89610a20471b",
  "resolution": { "type": null } 
  "suggestedUserMessage": "Your car got disconnected from <app name>. Please use this link to re-connect your car: <link to Smartcar Connect>."
}
```

### Suggested resolution

Please provide the user with a link to Smartcar Connect Re-authentication and prompt them to re-connect their vehicle.
The resolution field contains a partially constructed URL for Smartcar Connect Re-authentication, please see the API reference for more detail.

### Troubleshooting Steps

*   Prompt the user to log into their connected services account using the app or web portal.
*   Prompt the user to check whether there are any vehicles listed in their account.
*   If there are no vehicles listed, prompt the user to add their vehicle.
*   If there are one or more vehicles listed, this means that none of the vehicles have had their connected services activated. Prompt the user to activate connected services for at least one vehicle.
*   Provide the user with a link to Smartcar Connect and prompt them to re-connect their vehicle.

### Suggested user message

> Your car got disconnected from \<app name>. Please use this link to re-connect your car: \<link to Smartcar Connect>.

***

# `PERMISSION`

This error occurs when a vehicle owner had initially granted Smartcar access to their OEM account, but has since revoked it via the OEM's management portal.

```json
{
  "type": "CONNECTED_SERVICES_ACCOUNT",
  "code": "PERMISSION",
  "description": "The vehicle owner has revoked Smartcar’s access to their OEM account.",
  "docURL": "https://smartcar.com/docs/errors/api-errors/connected-service-errors#permission",
  "statusCode": 400,
  "requestId": "5dea93a1-3f79-4246-90c5-89610a20471b",
  "resolution": {
	  "type" : "REAUTHENTICATE"
  }
}
```

### Suggested resolution

For Tesla Owners:

*   Prompt the vehicle owner to go through the Connect flow again or use our [reauthentication flow](/help/oem-integrations/tesla/developers#stand-alone-flow) to streamline the process.

***

# `SUBSCRIPTION`

The vehicle’s connected services subscription is inactive or does not support the requested API endpoint.

```json
{
  "type": "CONNECTED_SERVICES_ACCOUNT",
  "code": "SUBSCRIPTION",
  "description": "The vehicle’s connected services subscription is inactive or does not support the requested API endpoint.",
  "docURL": "https://smartcar.com/docs/errors/api-errors/connected-service-errors#subscription",
  "statusCode": 400,
  "requestId": "5dea93a1-3f79-4246-90c5-89610a20471b",
  "resolution": { "type": null },
  "suggestedUserMessage": "Your car’s connected services subscription has either expired or it doesn’t support the necessary features to connect to <app name>. Please activate your subscription or contact us to upgrade your subscription."
}
```

### Suggested resolution

The user can resolve this error by logging into their connected services account and either (re-)activating their subscription or purchasing the required subscription package.

### Troubleshooting Steps

If you don’t know which subscription package the user needs to purchase, please contact our team for help.

### Suggested user message

> Your car’s connected services subscription has either expired or it doesn’t support the necessary features to connect to \<app name>. Please activate your subscription or contact us to upgrade your subscription.

***

# `VEHICLE_MISSING`

This vehicle is no longer associated with the user’s connected services account. The user might have removed it from their account.
The user needs to log into their connected services account and either re-add the vehicle or re-activate its subscription.

If you've received this error while testing with Vehicle Simulator, it likely means the simulated vehicle has not been found in your application. Visit the Simulator tab in the Smartcar Dashboard to create a simulated vehicle to test with.

```json
{
  "type": "CONNECTED_SERVICES_ACCOUNT",
  "code": "VEHICLE_MISSING",
  "description": "This vehicle is no longer associated with the user’s connected services account. Please prompt the user to re-add the vehicle to their account.",
  "docURL": "https://smartcar.com/docs/errors/api-errors/connected-service-errors#vehicle-missing",
  "statusCode": 400,
  "requestId": "5dea93a1-3f79-4246-90c5-89610a20471b",
  "resolution": { "type": null },
  "suggestedUserMessage": "Your car’s connected services subscription has either expired or it doesn’t support the necessary features to connect to <app name>. Please activate your subscription or contact us to upgrade your subscription."
}
```

### Suggested resolution

The user can resolve this issue by logging into their connected services account and either re-adding the vehicle or re-activating its subscription.

If the user wishes to disconnect their vehicle from your app, please make a request to our Disconnect endpoint and refrain from making API requests to this vehicle in the future.

### Troubleshooting Steps

*   Prompt the user to log into their connected services account using the app or web portal.
*   Prompt the user to check whether the vehicle is listed under their account.
*   If the vehicle is not listed, prompt the user to add the vehicle to their account.
*   If the vehicle is listed, prompt the user to activate the vehicle’s connected services subscription.

### Suggested user message

> This car is no longer associated with your connected services account. Please log into your account and re-add this car.

***

# `VIRTUAL_KEY_REQUIRED`

The vehicle owner has granted your application access to the vehicle through Smartcar. However, additional steps are needed on the owners part in order to perform this specific request.

```json
{
  "type": "CONNECTED_SERVICES_ACCOUNT",
  "code": "VIRTUAL_KEY_REQUIRED",
  "description": "The vehicle owner needs to grant additional access to Smartcar in order to perform this request.",
  "docURL": "https://smartcar.com/docs/errors/api-errors/connected-service-errors#virtual-key-required",
  "statusCode": 400,
  "requestId": "5dea93a1-3f79-4246-90c5-89610a20471b",
  "resolution": {
	  "type" : "ACTION_REQUIRED",
	  "url" : "https://www.tesla.com/_ak/smartcar.com"
  }
  "suggestedUserMessage": "In order to perform this request you’ll need to add a Third-Party Virtual key to your vehicle. Please open this link on the phone with your Tesla App to complete this step."
}
```

### Suggested resolution

For Tesla Owners:

*   The vehicle owner needs to add Smartcar’s Third-Party Virtual Key. As of late 2023, Tesla is starting to require virtual keys for Third-Party applications to perform commands.
*   In order to issue commands, please prompt the vehicle owner to add Smartcar’s Third-Party virtual key: [https://www.tesla.com/\_ak/smartcar.com](https://www.tesla.com/_ak/smartcar.com)

### Troubleshooting steps

*   Please direct the vehicle owner to add Smartcar’s [Third-Party Virtual Key (tesla.com)](https://www.tesla.com/_ak/smartcar.com) in order to allow your application to issue commands to the vehicle.

### Suggested user message

> In order to perform this request you’ll need to add a Third-Party Virtual key to your vehicle. Please open [this](https://www.tesla.com/_ak/smartcar.com) link on the phone with your Tesla App to complete this step.


# Permission Errors

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

# `NULL`

Your application has insufficient permissions to access the requested resource. Please prompt the user to re-authenticate using Smartcar Connect.

If you receive this error while testing with Vehicle Simulator, it is likely because the simulated vehicle has not yet been connected to your application, or your application doesn't have access to the requested permission.
Visit the Simulator documentation to learn how to connect the vehicle to your application.

```json
{
  "type": "PERMISSION",
  "code": null,
  "description": "Your application has insufficient permissions to access the requested resource. Please prompt the user to re-authenticate using Smartcar Connect.",
  "docURL": "https://smartcar.com/docs/errors/api-errors/permission-errors#null",
  "statusCode": 403,
  "requestId": "5dea93a1-3f79-4246-90c5-89610a20471b",
  "resolution": { "type": "REAUTHENTICATE" }  
}
```

### Suggested Resolution

You can resolve this error by ensuring that the scope parameter contains all the permissions that your application requires and prompting the user to re-authenticate using Smartcar Connect.

### Troubleshooting Steps

*   Ensure that the scope parameter contains all the permissions that your application requires.
*   Ensure that you spell all permission names in the scope parameter correctly.
*   Prompt the user to re-authenticate using Smartcar Connect.


# Rate Limit Errors

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

# `SMARTCAR_API`

Your application has exceeded its rate limit. Please retry your request in a few minutes.

```json
{
  "type": "RATE_LIMIT",
  "code": "SMARTCAR_API",
  "description": "Your application has exceeded its rate limit. Please retry your request in a few minutes.",
  "docURL": "https://smartcar.com/docs/errors/api-errors/rate-limit-errors#smartcar-api",
  "statusCode": 429,
  "requestId": "5dea93a1-3f79-4246-90c5-89610a20471b",
  "resolution": { "type": "RETRY_LATER" },
  "suggestedUserMessage": "Your vehicle is temporarily unable to connect to <app name>. Please be patient while we’re working to resolve this issue."
}
```

### Suggested resolution

You can resolve this error by refraining from making API requests for a certain period of time.
If your application automatically retries requests for certain errors, please disable automatic retries or implement a backoff period to retry certain requests less frequently.

### Troubleshooting steps

If you believe that you received this error by mistake and your application didn’t actually exceed its rate limit, please contact us and we’ll be happy to assist you.

### Suggested user message

> Your car is temporarily unable to connect to \<app name>. Please be patient while we’re working to resolve this issue.

***

# `VEHICLE`

You have reached the throttling rate limit for this vehicle. Please see the `retry-after` header (seconds) for when to retry the request.

This limit is in place to prevent excessive vehicle requests that could:

*   Lead to 12v battery drain.
*   Trigger UPSTREAM:RATE\_LIMIT errors that prevent you from making requests for a longer period of time.

```json
{
  "type": "RATE_LIMIT",
  "code": "VEHICLE",
  "description": "You have reached the throttling rate limit for this vehicle. Please see the retry-after header for when to retry the request.",
  "docURL": "https://smartcar.com/docs/errors/api-errors/rate-limit-errors#vehicle",
  "statusCode": 429,
  "requestId": "5dea93a1-3f79-4246-90c5-89610a20471b",
  "resolution": { "type": "RETRY_LATER" },
  "suggestedUserMessage": "Your vehicle is temporarily unable to connect to <app name>. Please be patient while we’re working to resolve this issue."
 
}
```

### Suggested resolution

You can resolve this error by refraining from making API requests. Please see the retry-after header for when to try again. If your application automatically retries requests for certain errors, please disable them for this one.

### Suggested user message

> Your car is temporarily unable to connect to \<app name>. Please be patient while we’re working to resolve this issue.

***


# Resource Not Found

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

# `PATH`

The requested resource does not exist. Please check the URL and try again.

```json
{
  "type": "RESOURCE_NOT_FOUND",
  "code": "PATH",
  "description": "The requested resource does not exist. Please check the URL and try again.",
  "docURL": "https://smartcar.com/docs/errors/api-errors/resource-errors#pathh",
  "statusCode": 404,
  "requestId": "5dea93a1-3f79-4246-90c5-89610a20471b",
  "resolution": { "type": null },
  "suggestedUserMessage": "Your vehicle is temporarily unable to connect to <app name>. Please be patient while we’re working to resolve this issue."
}
```

### Suggested Resolution

You can resolve this error by referring to our API reference and ensuring that you use the correct URL for your request.

### Troubleshooting Steps

*   Ensure that you spell all static parts of the URL correctly.
*   Ensure that you use the correct URL path parameters (e.g. vehicle ID).
*   Ensure that you use the correct HTTP method.

***

# `VERSION`

The requested resource does not exist. Your request either does not specify a version number or it specifies a version number that is not supported by this resource.

```json
{
  "type": "RESOURCE_NOT_FOUND",
  "code": "VERSION",
  "description": "The requested resource does not exist. Please check your specified version number and try again.",
  "docURL": "https://smartcar.com/docs/errors/api-errors/resource-errors#version",
  "statusCode": 404,
  "requestId": "5dea93a1-3f79-4246-90c5-89610a20471b",
  "resolution": { "type": null },
  "suggestedUserMessage": "Your vehicle is temporarily unable to connect to <app name>. Please be patient while we’re working to resolve this issue."
}
```

### Suggested Resolution

You can resolve this error by referring to our API reference and ensuring that you specify v2.0 in the URL path (e.g. [https://api.smartcar.com/v2.0/vehicles](https://api.smartcar.com/v2.0/vehicles)). Version 1 has been sunset and is no longer supported.


# Server Errors

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

# `INTERNAL`

An internal Smartcar error has occurred. Our team has been notified and is working to resolve this issue.

```json
{
  "type": "SERVER",
  "code": "INTERNAL",
  "description": "An internal Smartcar error has occurred. Our team has been notified and is working to resolve this issue.",
  "docURL": "https://smartcar.com/docs/errors/api-errors/server-errors#internal",
  "statusCode": 500,
  "requestId": "5dea93a1-3f79-4246-90c5-89610a20471b",
  "resolution": { "type": "RETRY_LATER" },
  "suggestedUserMessage": "Your car is temporarily unable to connect to <app name>. Please be patient while we’re working to resolve this issue." 
}
```

### Suggested Resolution

Please contact us to learn more about the error and our steps to resolve it.

### Suggested User Message

> Your car is temporarily unable to connect to \<app name>. Please be patient while we’re working to resolve this issue.

***

# `RECORD_NOT_FOUND`

Smartcar is unable to locate a battery capacity record for this vehicle. Depending on the make of the vehicle, battery capacity may depend on upstream sources to fulfil a request if it is not directly provided by the OEM.

If you’re seeing this error then the OEM doesn’t provide all the data we aim to provide in our response and we were unable to locate this information from other sources.

```json
{
  "type": "SERVER",
  "code": "RECORD_NOT_FOUND",
  "description": "Smartcar was unable to locate a battery capacity record for this vehicle.",
  "docURL": "https://smartcar.com/docs/errors/api-errors/server-errors#record-not-found",
  "statusCode": 500,
  "requestId": "5dea93a1-3f79-4246-90c5-89610a20471b",
  "resolution": { "type": "CONTACT_SUPPORT" },
  "suggestedUserMessage": "Your car is temporarily unable to connect to <app name>. Please be patient while we’re working to resolve this issue." 
}
```

### Suggested Resolution

Please reach out to support to see if we are able to update capacity data for the vehicle.

### Suggested User Message

> Your car is temporarily unable to connect to \<app name>. Please be patient while we’re working to resolve this issue.

***

# `MULTIPLE_RECORDS_FOUND`

Smartcar is unable to locate a battery capacity record for this vehicle. Depending on the make of the vehicle, battery capacity may depend on upstream sources to fulfil a request if it is not directly provided by the OEM.

If you’re seeing this error then the OEM doesn’t provide all the data we aim to provide in our response and we were unable to find a specific match. Please see the error response `detail` field for possible matches.

```json
{
	"statusCode": 500,
	"type": "SERVER",
	"code": "MULTIPLE_RECORDS_FOUND",
	"description": "Smartcar found multiple battery capacity records for this vehicle.",
	"docURL": "https://smartcar.com/docs/errors/api-errors/server-errors#multiple-records-found",
	"resolution": {
		"type": "CONTACT_SUPPORT"
	},
	"suggestedUserMessage": "Your car is temporarily unable to connect to <app name>. Please be patient while we’re working to resolve this issue.",
	"detail": [
		{
			"capacities": [83.9, 83.9, 70.2]
		}
	],
	"requestId": "9c8dd6fa-f9d7-4d18-9fdd-2255f6cd8613"
}
```

### Suggested Resolution

For battery capacity errors please check the detail field of the error response for a list of possible options and reach out support if you need us to update the capacity value for a specific vehicle.

### Suggested User Message

> Your car is temporarily unable to connect to \<app name>. Please be patient while we’re working to resolve this issue.


# Upstream Errors

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

# `INVALID_DATA`

One of Smartcar’s upstream sources provided data that is malformed, invalid, or logically invalid (e.g. 65535 psi for tire pressure).

```json
{
  "type": "UPSTREAM",
  "code": "INVALID_DATA",
  "description": "Smartcar received invalid data from an upstream source. Please retry your request at a later time.",
  "docURL": "https://smartcar.com/docs/errors/api-errors/upstream-errors#invalid-data",
  "statusCode": 502,
  "requestId": "5dea93a1-3f79-4246-90c5-89610a20471b",
  "resolution": { "type": "RETRY_LATER" },
  "suggestedUserMessage": "Your car is temporarily unable to connect to <app name>. Please be patient while we’re working to resolve this issue." 
}
```

### Suggested resolution

You can resolve this error by retrying your request at a later time.

### Suggested user message

> Your car is temporarily unable to connect to \<app name>. Please be patient while we’re working to resolve this issue.

***

# `KNOWN_ISSUE`

Smartcar received an error from an upstream source. This error usually occurs when an upstream source experiences an error that we have previously investigated and categorized as a known issue.

```json
{
  "type": "UPSTREAM",
  "code": "KNOWN_ISSUE",
  "description": "Smartcar received an error from an upstream source. Please retry your request at a later time.",
  "docURL": "https://smartcar.com/docs/errors/api-errors/upstream-errors#known-issue",
  "statusCode": 502,
  "requestId": "5dea93a1-3f79-4246-90c5-89610a20471b",
  "resolution": { "type": "RETRY_LATER" },
  "suggestedUserMessage": "Your car is temporarily unable to connect to <app name>. Please be patient while we’re working to resolve this issue." 
}
```

### Suggested resolution

You can resolve this error by retrying your request at a later time.

### Suggested user message

> Your car is temporarily unable to connect to \<app name>. Please be patient while we’re working to resolve this issue.

***

# `NO_RESPONSE`

One of Smartcar’s upstream sources failed to respond. This error usually occurs when one of Smartcar’s upstream sources is experiencing issues and is currently unavailable.
This error can also occur when a specific vehicle in located in an area with weak cellular reception and fails to respond to your request in a timely manner.

```json
{
  "type": "UPSTREAM",
  "code": "NO_RESPONSE",
  "description": "One of Smartcar’s upstream sources failed to respond. Please retry your request at a later time.",
  "docURL": "https://smartcar.com/docs/errors/api-errors/upstream-errors#no-response",
  "statusCode": 502,
  "requestId": "5dea93a1-3f79-4246-90c5-89610a20471b",
  "resolution": { "type": "RETRY_LATER" },
  "suggestedUserMessage": "Your car is temporarily unable to connect to <app name>. Please be patient while we’re working to resolve this issue."
}
```

### Suggested resolution

You can resolve this error by retrying your request at a later time.

### Suggested user message

> Your car is temporarily unable to connect to \<app name>. Please be patient while we’re working to resolve this issue.

***

# `RATE_LIMIT`

Your application’s requests have exceeded this vehicle’s rate limit.

```json
{
  "type": "UPSTREAM",
  "code": "NO_RESPONSE",
  "description": "One of Smartcar’s upstream sources failed to respond. Please retry your request at a later time.",
  "docURL": "https://smartcar.com/docs/errors/api-errors/upstream-errors#rate-limit",
  "statusCode": 502,
  "requestId": "5dea93a1-3f79-4246-90c5-89610a20471b",
  "resolution": { "type": "RETRY_LATER" },
  "suggestedUserMessage": "Your car is temporarily unable to connect to <app name>. Please be patient while we’re working to resolve this issue."
}
```

### Suggested resolution

You can resolve this error by refraining from making API requests to this specific vehicle for a period of time.
If your application automatically retries requests, please disable automatic retries or implement a backoff period to retry less frequently.

### Suggested user message

> Your car is temporarily unable to connect to \<app name>. Please be patient while we’re working to resolve this issue.

***

# `UNKNOWN_ISSUE`

Smartcar received an unknown error from an upstream source. This error usually occurs when one of Smartcar’s upstream sources experiences an error that we have not yet investigated or mitigated.

There are several reasons why we might not have investigated this error yet:

*   The feature or vehicle make is still in Early Access.
*   This error does not occur very frequently.
*   This is the first time we have received this error.

```json
{
  "type": "UPSTREAM",
  "code": "UNKNOWN_ISSUE",
  "description": "Smartcar received an unknown error from an upstream source. Please retry your request at a later time and contact us if the issue persists.",
  "docURL": "https://smartcar.com/docs/errors/api-errors/upstream-errors#unknown-issue",
  "statusCode": 502,
  "requestId": "5dea93a1-3f79-4246-90c5-89610a20471b",
  "resolution": { "type": "RETRY_LATER" },
  "suggestedUserMessage": "Your car is temporarily unable to connect to <app name>. Please be patient while we’re working to resolve this issue."
}
```

### Suggested resolution

Given the broad range of situations that can cause this error, you might or might not be able to resolve this error by retrying your request at a later time.
If you retry your request and the issue persists, please contact us to help you mitigate this error.

### Suggested user message

> Your car is temporarily unable to connect to \<app name>. Please be patient while we’re working to resolve this issue.

***


# Validation Errors

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

# `NULL`

Request invalid or malformed. Please check for missing parameters, spelling and casing mistakes, and other syntax issues.

```json
{
  "type": "VALIDATION",
  "code": null,
  "description": "Request invalid or malformed. Please check for missing parameters, spelling and casing mistakes, and other syntax issues.",
  "docURL": "https://smartcar.com/docs/errors/api-errors/validation-errors#null",
  "statusCode": 400,
  "requestId": "5dea93a1-3f79-4246-90c5-89610a20471b",
  "resolution": { "type": null },
  "suggestedUserMessage": "Your car is temporarily unable to connect to <app name>. Please be patient while we’re working to resolve this issue."
}
```

### Suggested resolution

You can resolve this error by referring to our API reference and ensuring that you pass all the parameters as specified.

### Troubleshooting Steps

*   Ensure that you spell and case all parameters correctly.

*   Ensure that your request has the correct content-type (i.e. application/json or application/x-www-form-urlencoded).

*   Ensure that your request has the correct URL and HTTP method.

### Suggested user message

> Your car is temporarily unable to connect to \<app name>. Please be patient while we’re working to resolve this issue.

***

# `PARAMETER`

Your request is formatted correctly, but one or more of the provided parameters is incorrect.

```json
{
  "type": "VALIDATION",
  "code": null,
  "description": "Your request is formatted correctly, but one or more of the provided parameters is incorrect.",
  "docURL": "https://smartcar.com/docs/errors/api-errors/validation-errors#parameter",
  "statusCode": 400,
  "requestId": "5dea93a1-3f79-4246-90c5-89610a20471b",
  "resolution": { "type": null },
  "suggestedUserMessage": "Your car is temporarily unable to connect to <app name>. Please be patient while we’re working to resolve this issue." 
}
```

### Suggested resolution

You can resolve this error by referring to our API reference and ensuring that you pass all the parameters as specified.

For Ford or Lincoln vehicles:

*   Please check the coordinates provided for setting a charge schedule are associated with a saved charging location for this vehicle.

### Suggested user message

> Your car is temporarily unable to connect to \<app name>. Please be patient while we’re working to resolve this issue.


# Vehicle State 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.

# `ASLEEP`

The vehicle is in a sleep state and temporarily unable to perform your request. Either the vehicle has been inactive for a certain period of time (time periods vary between makes and models) or the user has manually triggered the vehicle’s sleep state.

```json
{
  "type": "VEHICLE_STATE",
  "code": "ASLEEP",
  "description": "The vehicle is in a sleep state and temporarily unable to perform your request.",
  "docURL": "https://smartcar.com/docs/errors/api-errors/vehicle-state-errors#asleep",
  "statusCode": 409,
  "requestId": "5dea93a1-3f79-4246-90c5-89610a20471b",
  "resolution": { "type": null },
  "suggestedUserMessage": "Your vehicle is in a sleep state. This request was not sent to preserve battery life. "
}
```

### Suggested resolution

The vehicle is in a sleep state and temporarily unable to perform your request.

### Troubleshooting Steps

*   Prompt the user to start the vehicle’s engine (required) and to drive the vehicle for a short distance (optional).
*   Wait for a few minutes and retry your request.
*   Ensure that the vehicle’s 12-volt battery is sufficiently charged.

### Suggested user message

> Your car is temporarily unable to connect to \<app name>. To re-establish the connection, please start your car and take it for a short drive.

***

# `CHARGING_IN_PROGRESS`

The vehicle is currently charging and unable to perform your request. This error usually occurs when you make a request to the start charge endpoint while the vehicle is already charging.

```json
{
  "type": "VEHICLE_STATE",
  "code": "CHARGING_IN_PROGRESS",
  "description": "The vehicle is currently charging and unable to perform your request.",
  "docURL": "https://smartcar.com/docs/errors/api-errors/vehicle-state-errors#charging-in-progress",
  "statusCode": 409,
  "requestId": "5dea93a1-3f79-4246-90c5-89610a20471b",
  "resolution": { "type": null },
  "suggestedUserMessage": "Your vehicle is already charging."
}
```

### Suggested resolution

You usually don’t need to resolve this error. If you believe that this error should not have occurred, please follow the troubleshooting steps below.

### Troubleshooting Steps

*   Prompt the user to stop charging their vehicle and/or unplug the charger.
*   Wait for a few minutes and retry your request.

### Suggested user message

> Your car is already charging.

***

# `CHARGING_PLUG_CONNECTED`

The vehicle is connected to an EV charger and unable to perform your request.

```json
{
  "type": "VEHICLE_STATE",
  "code": "CHARGING_PLUG_CONNECTED",
  "description": "The vehicle is connected to an EV charger and unable to perform your request.",
  "docURL": "https://smartcar.com/docs/errors/api-errors/vehicle-state-errors#charging-plug-connected",
  "statusCode": 409,
  "requestId": "5dea93a1-3f79-4246-90c5-89610a20471b",
  "resolution": { "type": null },
  "suggestedUserMessage": "We’re unable to issue the command because the vehicle is currently plugged in."
}
```

### Suggested resolution

The user can resolve this error by unplugging the vehicle.

### Suggested user message

> We're unable to issue the command because the vehicle is currently plugged in. Please ensure that you have unplugged the vehicle from an EV charger.

***

# `CHARGING_PLUG_NOT_CONNECTED`

The vehicle is not connected to an EV charger and unable to perform your request. This error usually occurs when you make a request to the start charge endpoint
but the vehicle’s charge port does not have an EV charger plugged into it.

If testing an electric vehicle with Vehicle Simulator, you will receive this error when attempting a start or stop charge request while the vehicle is in a parked
or driving state (not charging).

```json
{
  "type": "VEHICLE_STATE",
  "code": "CHARGING_PLUG_NOT_CONNECTED",
  "description": "The vehicle is not connected to an EV charger and unable to perform your request.",
  "docURL": "https://smartcar.com/docs/errors/api-errors/vehicle-state-errors#charging-plug-not-connected",
  "statusCode": 409,
  "requestId": "5dea93a1-3f79-4246-90c5-89610a20471b",
  "resolution": { "type": null },
  "suggestedUserMessage": "Your vehicle is not plugged in."
}
```

### Suggested resolution

The user can resolve this error by plugging an EV charger into the vehicle’s charge port.

### Troubleshooting Steps

*   Prompt the user to plug an EV charger into the vehicle’s charge port.
*   If this doesn’t resolve the issue, prompt the user to ensure that the EV charger is connected to a working power source, that it isn’t faulty, and that it is compatible with the user’s vehicle. For example, prompt the user to try out other EV chargers and to check the vehicle’s owner manual for a list of compatible chargers.

### Suggested user message

> Your car isn’t able to start charging. Please ensure that you have plugged an EV charger into your car’s charge port.

***

# `DOOR_OPEN`

The vehicle could not perform your request because one or more of its doors are open. This error usually occurs when you make a request to the lock endpoint while one or more of the vehicle’s doors stand open.

```json
{
  "type": "VEHICLE_STATE",
  "code": "DOOR_OPEN",
  "description": "The vehicle could not perform your request because one or more of its doors are open.",
  "docURL": "https://smartcar.com/docs/errors/api-errors/vehicle-state-errors#door-open",
  "statusCode": 409,
  "requestId": "5dea93a1-3f79-4246-90c5-89610a20471b",
  "resolution": { "type": null },
  "suggestedUserMessage": "Your vehicle was unable to lock. Please ensure that all doors and the trunk are fully closed."
}
```

### Suggested resolution

The user can resolve this error by fully closing all of the vehicle’s doors and the trunk.

### Troubleshooting Steps

*   Prompt the user to ensure that there is nothing preventing the doors from fully closing and/or locking properly.
*   Prompt the user to ensure that the vehicle’s trunk is fully closed.

### Suggested user message

> Your car was unable to lock. Please ensure that all doors and the trunk are fully closed.

***

# `FULLY_CHARGED`

The vehicle is unable to perform your request because its EV battery is fully charged. This error usually occurs when you make a request to the start charge endpoint while the vehicle is already fully charged.

```json
{
  "type": "VEHICLE_STATE",
  "code": "FULLY_CHARGED",
  "description": "The vehicle is unable to perform your request because its EV battery is fully charged.",
  "docURL": "https://smartcar.com/docs/errors/api-errors/vehicle-state-errors#fully-charged",
  "statusCode": 409,
  "requestId": "5dea93a1-3f79-4246-90c5-89610a20471b",
  "resolution": { "type": null },
  "suggestedUserMessage": "Your vehicle is already fully charged."
}
```

### Suggested user message

> Your car is already fully charged.

***

# `NOT_CHARGING`

The vehicle is unable to perform your request because it is not currently charging. This error usually occurs when you request information about a vehicle’s charge session while the battery is not charging.

```json
{
  "type": "VEHICLE_STATE",
  "code": "NOT_CHARGING",
  "description": "The vehicle is unable to perform your request because it is not currently charging.",
  "docURL": "https://smartcar.com/docs/errors/api-errors/vehicle-state-errors#not-charging",
  "statusCode": 409,
  "requestId": "5dea93a1-3f79-4246-90c5-89610a20471b",
  "resolution": { "type": null },
  "suggestedUserMessage": "Please ensure that you have plugged an EV charger into your car’s charge port and the vehicle is charging."
}
```

### Suggested resolution

You can resolve this error by having the user start a charge session or by sending a start charge request if the vehicle supports that capability.

### Troubleshooting Steps

*   Prompt the user to start charging their vehicle.
*   Wait for a few minutes and retry your request.

### Suggested user message

> Please ensure that you have plugged an EV charger into your car’s charge port and the vehicle is charging.

***

# `CHARGE_FAULT`

The vehicle is connected to an EV charger but cannot perform the request because:

*   the charger is not providing any current
*   there is a conflict with another charging schedule

```json
{
  "type": "VEHICLE_STATE",
  "code": "CHARGE_FAULT",
  "description": "The vehicle is connected to an EV charger but cannot perform the request because 1) the charger is not providing any current, or 2) there is a conflict with another charging schedule.",
  "docURL": "https://smartcar.com/docs/errors/api-errors/vehicle-state-errors#charge-fault",
  "statusCode": 409,
  "requestId": "5dea93a1-3f79-4246-90c5-89610a20471b",
  "resolution": { "type": null },
  "suggestedUserMessage": "Your vehicle is unable to start or stop charging because of a conflict with the vehicle's charging schedule."
}
```

### Suggested resolution

The user can resolve this error by:

*   Disabling any schedules that control when the charger can supply current and charge the vehicle.
*   Ensuring that the charging cable is securely connected to the vehicle.
*   Disabling any charge schedules on the vehicle’s infotainment system or connected service application.
*   Disabling any departure timers on the vehicle’s infotainment system or connected service application.
*   Removing the vehicle from other charge scheduling services.

### Troubleshooting Steps

*   Prompt the user to start charging their vehicle.
*   Wait for a few minutes and retry your request.

### Suggested user message

> Your car is unable to start or stop charging because of a conflict with your vehicle’s charging schedule. Please check that:
>
> *   You have disabled any schedules that control when your charger is able to supply current to and charge the vehicle.
> *   The charging cable is securely connected to your vehicle.
> *   You have disabled any charge schedules on your vehicle’s infotainment system or connected service application.
> *   You have disabled any departure timers on your vehicle’s infotainment system or connected service application.
> *   Your vehicle is not connected to any other charge scheduling services.

***

# `HOOD_OPEN`

The vehicle is unable to perform your request because its hood is open. This error usually occurs when you make a request to the lock endpoint while the vehicle’s hood stands open.

```json
{
  "type": "VEHICLE_STATE",
  "code": "HOOD_OPEN",
  "description": "The vehicle is unable to perform your request because its hood is open.",
  "docURL": "https://smartcar.com/docs/errors/api-errors/vehicle-state-errors#hood-open",
  "statusCode": 409,
  "requestId": "5dea93a1-3f79-4246-90c5-89610a20471b",
  "resolution": { "type": null },
  "suggestedUserMessage": "Your vehicle was unable to lock. Please ensure that the vehicle's hood is fully closed."
}
```

### Suggested resolution

The user can resolve this error by ensuring that the vehicle’s hood is fully closed.

### Suggested user message

> Your car was unable to lock. Please ensure that your car’s hood is fully closed.

***

# `IGNITION_ON`

The vehicle was unable to perform your request because its engine is running. Depending on the vehicle’s make and model, this error can occur for a variety of API endpoints.

```json
{
  "type": "VEHICLE_STATE",
  "code": "IGNITION_ON",
  "description": "The vehicle was unable to perform your request because its engine is running.",
  "docURL": "https://smartcar.com/docs/errors/api-errors/vehicle-state-errors#ignition-on",
  "statusCode": 409,
  "requestId": "5dea93a1-3f79-4246-90c5-89610a20471b",
  "resolution": { "type": null },
  "suggestedUserMessage": "Your vehicle is currently running."
}
```

### Suggested resolution

The user can resolve this error by turning off their vehicle. You can also resolve this error by retrying your request at a later time.

### Suggested user message

> Your car is temporarily unable to connect to \<app name> because its engine is running. To re-establish the connection, please turn off your car’s engine.

***

# `IN_MOTION`

The vehicle is currently in motion and unable to perform your request. Depending on the vehicle’s make and model, this error can occur for a variety of API endpoints. The lock/unlock endpoint is a common example.

If testing with Vehicle Simulator, you will receive this error when attempting a lock/unlock request while the vehicle is in a driving state along the simulation.

```json
{
  "type": "VEHICLE_STATE",
  "code": "IN_MOTION",
  "description": "The vehicle is currently in motion and unable to perform your request.",
  "docURL": "https://smartcar.com/docs/errors/api-errors/vehicle-state-errors#in-motion",
  "statusCode": 409,
  "requestId": "5dea93a1-3f79-4246-90c5-89610a20471b",
  "resolution": { "type": null },
  "suggestedUserMessage": "Your vehicle is unable to perform the request while in motion."
}
```

### Suggested resolution

The user can resolve this error by parking their car and turning off the engine. You can also resolve this error by retrying your request at a later time.

### Suggested user message

> Your car is in motion and temporarily unable to connect to \<app name>. To re-establish the connection, please park your car and turn off its engine.

***

# `REMOTE_ACCESS_DISABLED`

The vehicle is unable to perform your request because the user has disabled remote access for connected services.

```json
{
  "type": "VEHICLE_STATE",
  "code": "REMOTE_ACCESS_DISABLED",
  "description": "The vehicle is unable to perform your request because the user has disabled remote access for connected services.",
  "docURL": "https://smartcar.com/docs/errors/api-errors/vehicle-state-errors#remote-access-disabled",
  "statusCode": 409,
  "requestId": "5dea93a1-3f79-4246-90c5-89610a20471b",
  "resolution": { "type": null },
  "suggestedUserMessage": "Your vehicle is unable to perform the request as remote access is disabled or unavailable."
}
```

### Suggested resolution

The user can resolve this error by re-enabling remote access inside their vehicle. If the user is unsure how to enable remote access for connected services, prompt them to refer to their vehicle’s owner manual for more details.

### Suggested user message

> Your car is temporarily unable to connect to \<app name>. To re-establish the connection, please make sure that remote access for connected services is enabled inside your car. Please refer to your car’s owner manual for more details.

***

# `TRUNK_OPEN`

The vehicle is unable to perform your request because its trunk is open. This error usually occurs when you make a request to the lock endpoint while the vehicle’s trunk and/or front trunk are open.

```json
{
  "type": "VEHICLE_STATE",
  "code": "TRUNK_OPEN",
  "description": "The vehicle is unable to perform your request because its trunk is open.",
  "docURL": "https://smartcar.com/docs/errors/api-errors/vehicle-state-errors#trunk-open",
  "statusCode": 409,
  "requestId": "5dea93a1-3f79-4246-90c5-89610a20471b",
  "resolution": { "type": null },
  "suggestedUserMessage": "Your vehicle was unable to open the trunk because it is already open."
}
```

### Suggested resolution

The user can resolve this error by closing the vehicle’s trunk and/or front trunk.

### Suggested user message

> Your car was unable to lock. Please ensure that your car’s trunk (and front trunk) is closed.

***

# `UNKNOWN`

The vehicle was unable to perform your request due to an unknown issue. This error occurs when the vehicle is in a state that makes it unable to perform your request, and we are unable to determine which state the vehicle is in.

If testing an electric vehicle with Vehicle Simulator, you will receive this error when attempting a stop charge request while the vehicle is in a charging state.

```json
{
  "type": "VEHICLE_STATE",
  "code": "UNKNOWN",
  "description": "The vehicle was unable to perform your request due to an unknown issue.",
  "docURL": "https://smartcar.com/docs/errors/api-errors/vehicle-state-errors#unknown",
  "statusCode": 409,
  "requestId": "5dea93a1-3f79-4246-90c5-89610a20471b",
  "resolution": { "type": "RETRY_LATER" },
  "suggestedUserMessage": "Your vehicle is temporarily unable to connect due to an unknown issue. Please be patient while we’re working to resolve this issue."
}
```

### Suggested resolution

Please retry your request at a later time.

### Suggested user message

> Your car is temporarily unable to connect to \<app name>. Please be patient while we’re working to resolve this issue.

***

# `UNREACHABLE`

The vehicle was unable to perform your request because it is currently unreachable. This error usually occurs when the vehicle is in a location with poor cellular reception (e.g. a parking garage or underground parking).

If testing with Vehicle Simulator, you will receive this error when attempting a lock/unlock or start/stop charge request while the simulation is paused or completed.

```json
{
  "type": "VEHICLE_STATE",
  "code": "UNREACHABLE",
  "description": "The vehicle was unable to perform your request because it is currently unreachable.",
  "docURL": "https://smartcar.com/docs/errors/api-errors/vehicle-state-errors#unreachable",
  "statusCode": 409,
  "requestId": "5dea93a1-3f79-4246-90c5-89610a20471b",
  "resolution": { "type": null },
  "suggestedUserMessage": "Your vehicle is currently unreachable. Ensure the vehicle has adequate mobile coverage."
}
```

### Suggested resolution

The user can resolve this error by moving the vehicle to a location with better cellular reception. You can also resolve this error by retrying your request at a later time.

### Suggested user message

> Your car is temporarily unable to connect to \<app name>. To re-establish the connection, please move your car to a location with a better cell phone signal.

***

# `VEHICLE_OFFLINE_FOR_SERVICE`

The vehicle was unable to perform your request because it is currently in service mode. Service mode temporarily limits or disables the vehicle’s remote capabilities.

```json
{
  "type": "VEHICLE_STATE",
  "code": "VEHICLE_OFFLINE_FOR_SERVICE",
  "description": "The vehicle was unable to perform your request because it is currently in service mode.",
  "docURL": "https://smartcar.com/docs/errors/api-errors/vehicle-state-errors#vehicle-offline-for-service",
  "statusCode": 409,
  "requestId": "5dea93a1-3f79-4246-90c5-89610a20471b",
  "resolution": { "type": null },
  "suggestedUserMessage": "Your vehicle is in service mode and temporarily unable to perform this task."
}
```

### Suggested resolution

Please retry your request at a later time.

### Suggested user message

> Your car is in service mode and temporarily unable to connect to \<app name>. Please try again later.

***

# `LOW_BATTERY`

The vehicle was unable to perform your request because the 12v or high voltage battery is too low.

```json
{
  "type": "VEHICLE_STATE",
  "code": "LOW_BATTERY",
  "description": "The vehicle was unable to perform your request because the 12v or high voltage battery is too low.",
  "docURL": "https://smartcar.com/docs/errors/api-errors/vehicle-state-errors#low-battery",
  "statusCode": 409,
  "requestId": "5dea93a1-3f79-4246-90c5-89610a20471b",
  "resolution": { "type": "RETRY_LATER" },
  "suggestedUserMessage": "Your vehicle battery is too low to perform this task."
}
```

### Suggested resolution

Please retry your request at a later time.

*   For EVs ensure that the battery is topped up to at least 60% SoC.
*   Ensure that the vehicle’s 12-volt battery is sufficiently charged. Taking the vehicle on a short drive can help.

### Suggested user message

> \<app name> was unable to connect to your car because its battery is too low. Please ensure the battery is charged and try again later.

***


# Access Denied

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

| Parameter           | Required | Description                        |
| ------------------- | -------- | ---------------------------------- |
| `error`             | `true`   | `access_denied`                    |
| `error_description` | `true`   | User denied access to application. |

```http Example redirect uri
HTTP/1.1 302 Found
Location: https://example.com/home
?error=access_denied
&error_description=User+denied+access+to+application
```

## Testing

To test this error, launch Smartcar Connect in test mode and select “Deny access” on the permissions screen.

<Frame caption="Access Denied">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/api-reference/access_denied.png" />
</Frame>

We recommend handling this error by re-prompting the user to authorize their vehicle and adding a message like in the example below.

<Frame caption="Access Denied Message">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/api-reference/access_denied_message.png" />
</Frame>


# Configuration

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

| Parameter           | Required | Description                                                       |
| ------------------- | -------- | ----------------------------------------------------------------- |
| `error`             | `true`   | `configuration_error`                                             |
| `error_description` | `true`   | There has been an error in the configuration of your application. |
| `status_code`       | `true`   | The status code of the error encountered in Connect               |
| `error_message`     | `true`   | The error message seen by the user                                |

```http Example redirect uri
HTTP/1.1 302 Found
Location: https://example.com/callback
?error=configuration_error
&error_description=There%20has%20been%20an%20error%20in%20the%20configuration%20of%20your%20application.&status_code=400
&error_message=You%20have%20entered%20a%20test%20mode%20VIN.%20Please%20enter%20a%20VIN%20that%20belongs%20to%20a%20real%20vehicle.
```

On redirect, Connect will return the status code and message of the error that they encountered. This will be triggered if:

*   A user tried to directly navigate to a page that is past their current step in Connect (ie. going directly from the Preamble screen to the Permission Grants screen by directly going to connect.smartcar.com/grant).
*   A user is trying to use Single Select in live mode with a test mode VIN or with a simulated VIN in a non-simulated mode.
*   A user is trying to use Single Select with an invalid mock VIN.
*   A validation error occurs when trying to check compatibility by VIN.

These cases will trigger the following error and give the user the ability to “Exit” Connect.

<Frame caption="Error Page">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/api-reference/error_page.png" />
</Frame>


# Invalid Subscription

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.

| Parameter          | Required | Description                                                  |   |
| ------------------ | -------- | ------------------------------------------------------------ | - |
| error              | true     | invalid\_subscription                                        |   |
| error\_description | true     | User does not have an active connected vehicle subscription. |   |

```http Example redirect uri
HTTP/1.1 302 Found
Location: https://example.com/callback
?error=invalid_subscription
&error_description=User%20does%20not%20have%20an%20active%20connected%20vehicle%20subscription
```

Smartcar will direct the user to the connected services website to (re-)activate their subscription. However, a user may choose to return back to your application instead, like in the example below.

<Frame caption="No Subscription">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/api-reference/no_subscription.png" />
</Frame>

## Testing

To test this error, launch Smartcar Connect in test mode and log in with the email [smartcar@invalid-subscription.com](mailto:smartcar@invalid-subscription.com) and any password. If you use Single Select, please see the table below for a simulated VIN.

| Email                                                                         | VIN               |
| ----------------------------------------------------------------------------- | ----------------- |
| [smartcar@invalid-subscription.com](mailto:smartcar@invalid-subscription.com) | 0SCAUDI0155C49A95 |

In the event of an `AUTHENTICATION_FAILED`, the user will need to be prompted to re-connect their vehicle. Smartcar Connect Re-authentication makes the process of re-authenticating a user much more seamless. In addition, the `AUTHENTICATION_FAILED` error provides a partially constructed URL for the re-authentication flow inside the resolution object.


# No Vehicles

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

| Parameter          | Required | Description                                                  |   |
| ------------------ | -------- | ------------------------------------------------------------ | - |
| error              | true     | no\_vehicles                                                 |   |
| error\_description | true     | User does not have an active connected vehicle subscription. |   |

```http Example redirect uri
HTTP/1.1 302 Found
Location: https://example.com/callback
?error=no_vehicles&error_description=No%20vehicles%20found.%20Please%20add%20vehicles%20to%20your%20account%20and%20try%20again.
```

The error is triggered when a user logs into their connected services account and is shown to have no vehicles listed like in the example below for BMW.

<Frame caption="No Vehicle Error">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/api-reference/no_vehicle_error.png" />
</Frame>

The user has the option to add vehicles or return to your application.


# OEM Login Cancelled

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

| Parameter           | Required | Description                                          |
| ------------------- | -------- | ---------------------------------------------------- |
| `error`             | `true`   | `oem_cancelled_login`                                |
| `error_description` | `true`   | The user did not complete authorization with the OEM |

```http Example redirect uri
HTTP/1.1 302 Found
Location: https://example.com/callback
?error=oem_cancelled_login
&the%20user%20did%20not%20complete%20authorization%20with%20the%20OEM
```

<Frame caption="OEM Login Cancelled">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/errors/connect-errors/oem-cancelled.png" />
</Frame>


# User returned to application

This error occurs when a user leaves the Connect flow after hitting **Back to application** before granting your application access to their vehicle.

| Parameter           | Required | Description                                                     |
| ------------------- | -------- | --------------------------------------------------------------- |
| `error`             | `true`   | `user_manually_returned_to_application`                         |
| `error_description` | `true`   | The user exited Connect before granting your application access |

There are cases where a user may wish to exit Connect before granting your application access to their vehicle. In these cases, if the user hits **Back to application** instead of closing out the window, Smartcar will return this error to your callback URI. Below are places in the Connect flow users can return to your application.

<Tabs>
  <Tab title="Missing Permissions">
    <Frame caption="Vehicle Incompatible">
      <img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/errors/connect-errors/r2a-additional-permissions.png" />
    </Frame>
  </Tab>

  <Tab title="MFA Entry">
    <Frame caption="Vehicle Incompatible">
      <img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/errors/connect-errors/r2a-mfa-entry.png" />
    </Frame>
  </Tab>

  <Tab title="PIN Entry">
    <Frame caption="Vehicle Incompatible">
      <img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/errors/connect-errors/r2a-pin-entry.png" />
    </Frame>
  </Tab>
</Tabs>


# Server

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

| Parameter          | Required | Description                                |
| ------------------ | -------- | ------------------------------------------ |
| error              | true     | server\_error                              |
| error\_description | true     | Unexpected server error. Please try again. |

```http Example redirect uri
HTTP/1.1 302 Found
Location: https://example.com/callback
?error=configuration_error
&error_description=There%20has%20been%20an%20error%20in%20the%20configuration%20of%20your%20application.&status_code=400
&error_message=You%20have%20entered%20a%20test%20mode%20VIN.%20Please%20enter%20a%20VIN%20that%20belongs%20to%20a%20real%20vehicle.
```

<Note>
  We only show the “Exit” button if a redirect URI is available. If there is a failure before the validation of the redirect URI,  we are unable to include the “Exit” button on the Error page. In those cases, we would not be able to report the `status_code` and `error_message` back to the developer, but they will still be available on screen in the Error page.
</Note>

<Frame caption="Server Error">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/errors/connect-errors/server-error.png" />
</Frame>


# Vehicle Incompatible

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

| Parameter           | Required | Description                           |
| ------------------- | -------- | ------------------------------------- |
| `error`             | `true`   | `vehicle_incompatible`                |
| `error_description` | `true`   | The user’s vehicle is not compatible. |
| `make`              | `false`  | The manufacturer of the vehicle.      |
| `vin`               | `false`  | The VIN of the vehicle.               |

In order to be compatible, a vehicle must:

*   Have the hardware required for internet connectivity
*   Belong to the makes and models Smartcar is compatible with
*   Be capable of the required permissions that your application is requesting access to
*   If the user’s vehicle is incompatible, Smartcar will let the user know and offer them to share their vehicle’s VIN, make, model, and year with your application.

This error is triggered when a user selects an unspported make, or selects "I don't see my brand..." and then hits "Back to application"

<Frame caption="Vehicle Incompatible">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/errors/connect-errors/vehicle-incompatible.png" />
</Frame>

We recommend that your application provides a flow for incompatible vehicles like in the example below.

<Frame caption="Vehicle Incompatible">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/api-reference/vehicle_incompatible.png" />
</Frame>

<br />

<Info>
  Note: This error will never occur if your application uses the Compatibility API. The Compatibility API verifies the compatibility of a vehicle before the user enters Smartcar Connect.
</Info>

To test this error, launch Smartcar Connect in test mode and log in with the email [smartcar@vehicle-incompatible.com](mailto:smartcar@vehicle-incompatible.com) and any password.

If you use Single Select, please see the table below for a simulated VIN.

| Email                                                                         | VIN               |
| ----------------------------------------------------------------------------- | ----------------- |
| [smartcar@vehicle-incompatible.com](mailto:smartcar@vehicle-incompatible.com) | 0SCAUDI012FE3B132 |


# Overview

A comprehensive breakout of all Smartcar errors.

# Connect Errors

Connect errors are returned as a parameter in the redirect from Connect.

### Access Denied

| <div style={{ width:400 }} />                                                                       | <div style={{ width:300 }} /> Code                     |
| --------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| This error occurs when a user denies your application access to the requested scope of permissions. | [access\_denied](/errors/connect-errors/access-denied) |

### Invalid Subscription

| <div style={{ width:400 }} />                                                                                                                                             | <div style={{ width:300 }} /> Code                                   |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| 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](/errors/connect-errors/invalid-subscription) |

### Configuration Error

| <div style={{ width:400 }} />                                                                                          | <div style={{ width:300 }} /> Code                                 |
| ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| This error occurs when the user has encountered an Error page in Connect and has chosen to return to your application. | [configuration\_error](/errors/connect-errors/configuration-error) |

### No Vehicles

| <div style={{ width:400 }} />                                                                                                   | <div style={{ width:300 }} /> Code                 |
| ------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| This error occurs when a vehicle owner has a connected services account, but there are no vehicles associated with the account. | [no\_vehicles](/errors/connect-errors/no-vehicles) |

### Vehicle Incompatible

| <div style={{ width:400 }} />                                                                 | <div style={{ width:300 }} /> Code                                   |
| --------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| This error occurs when a user tries to authorize an incompatible vehicle in Smartcar Connect. | [vehicle\_incompatible](/errors/connect-errors/vehicle-incompatible) |

### Server Error

| <div style={{ width:400 }} />                                         | <div style={{ width:300 }} /> Code                   |
| --------------------------------------------------------------------- | ---------------------------------------------------- |
| If there is a server error, the user will return to your application. | [server\_error](/errors/connect-errors/server-error) |

<br />

# API Errors

API errors are returned from requests made via Smartcar API.

### Authentication

| <div style={{ width:400 }} />                                  | <div style={{ width:300 }} /> Code                    |
| -------------------------------------------------------------- | ----------------------------------------------------- |
| Thrown when there is an issue with your authorization headers. | [NULL](/errors/api-errors/authentication-errors#null) |

### Billing

| <div style={{ width:400 }} />                                                               | <div style={{ width:300 }} /> Code                                                                                                                                                                                                                                                                                              |
| ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Thrown when limits have been reached based on your plan or if the feature is not available. | [INVALID\_PLAN](/errors/api-errors/billing-errors#invalid-plan)<br /><br />[VEHICLE\_LIMIT](/errors/api-errors/billing-errors#vehicle-limit)<br /><br />[VEHICLE\_REQUEST\_LIMIT](/errors/api-errors/billing-errors#vehicle-request-limit)<br /><br />[ACCOUNT\_SUSPENDED](/errors/api-errors/billing-errors#account-suspended) |

### Compatibility

| <div style={{ width:400 }} />                                          | <div style={{ width:300 }} /> Code                                                                                                                                                                                                                                                     |
| ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Thrown when Smartcar does not support a make or feature for a vehicle. | [MAKE\_NOT\_COMPATIBLE](/errors/api-errors/compatibility-errors#make-not-compatible)<br /><br />[SMARTCAR\_NOT\_CAPABLE](/errors/api-errors/compatibility-errors#smartcar-not-capable)<br /><br />[VEHICLE\_NOT\_CAPABLE](/errors/api-errors/compatibility-errors#vehicle-not-capable) |

### Connected Services Account

| <div style={{ width:400 }} />                                           | <div style={{ width:300 }} /> Code                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Thrown when there are issues with the user's connected service account. | [ACCOUNT\_ISSUE](/errors/api-errors/connected-service-errors#account_issue)<br /><br />[AUTHENTICATION\_FAILED](/errors/api-errors/connected-service-errors#authentication-failed)<br /><br />[NO\_VEHICLES](/errors/api-errors/connected-service-errors#no-vehicles)<br /><br />[SUBSCRIPTION](/errors/api-errors/connected-service-errors#subscription)<br /><br />[VEHICLE\_MISSING](/errors/api-errors/connected-service-errors#vehicle-missing) |

### Permission

| <div style={{ width:400 }} />                                                                                   | <div style={{ width:300 }} /> Code                |
| --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
| Thrown when you make a requests to an endpoint associated with permissions not yet granted to your application. | [NULL](/errors/api-errors/permission-errors#null) |

### Rate Limit

| <div style={{ width:400 }} />                                      | <div style={{ width:300 }} /> Code                                                                                                    |
| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
| Thrown when there is an issue with the frequency of your requests. | [SMARTCAR\_API](/errors/api-errors/rate-limit-errors#smartcar-api)<br /><br />[VEHICLE](/errors/api-errors/rate-limit-errors#vehicle) |

### Resource Not Found

| <div style={{ width:400 }} />                | <div style={{ width:300 }} /> Code                                                                                            |
| -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| Thrown if the requested path does not exist. | [PATH](/errors/api-errors/resource-errors#path)<br /><br /> [VERSION](/errors/api-errors/resource-errors#version)<br /><br /> |

### Server

| <div style={{ width:400 }} />                                                             | <div style={{ width:300 }} /> Code                    |
| ----------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| Thrown when Smartcar runs into an unexpected issue and was unable to process the request. | [INTERNAL](/errors/api-errors/server-errors#internal) |

### Upstream

| <div style={{ width:400 }} />                                 | <div style={{ width:300 }} /> Code                                                                                                                                                                                                                                                                                                                                         |
| ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Thrown when the OEM or vehicle failed to process the request. | [INVALID\_DATA](/errors/api-errors/upstream-errors#invalid-data)<br /><br />[KNOWN\_ISSUE](/errors/api-errors/upstream-errors#known-issue)<br /><br />[NO\_RESPONSE](/errors/api-errors/upstream-errors#no-response)<br /><br />[RATE\_LIMIT](/errors/api-errors/upstream-errors#rate-limit)<br /><br />[UNKNOWN\_ISSUE](/errors/api-errors/upstream-errors#unknown-issue) |

### Validation

| <div style={{ width:400 }} />                                       | <div style={{ width:300 }} /> Code                                                                                       |
| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| Thrown if there is an issue with the format of the request or body. | [NULL](/errors/api-errors/validation-errors#null)<br /><br />[PARAMETER](/errors/api-errors/validation-errors#parameter) |

### Vehicle State

| <div style={{ width:400 }} />                                                                                                                              | <div style={{ width:300 }} /> Code                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 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. | [ASLEEP](/errors/api-errors/vehicle-state-errors#asleep)<br /><br />[CHARGING\_IN\_PROGRESS](/errors/api-errors/vehicle-state-errors#charging-in-progress)<br /><br />[CHARGING\_PLUG\_NOT\_CONNECTED](/errors/api-errors/vehicle-state-errors#charging-plug-not-connected)<br /><br />[DOOR\_OPEN](/errors/api-errors/vehicle-state-errors#door-open)<br /><br />[FULLY\_CHARGED](/errors/api-errors/vehicle-state-errors#fully-charged)<br /><br />[NOT\_CHARGING](/errors/api-errors/vehicle-state-errors#not-charging)<br /><br />[CHARGE\_FAULT](/errors/api-errors/vehicle-state-errors#charge-fault)<br /><br />[HOOD\_OPEN](/errors/api-errors/vehicle-state-errors#hood-open)<br /><br />[IGNITION\_ON](/errors/api-errors/vehicle-state-errors#ignition-on)<br /><br />[IN\_MOTION](/errors/api-errors/vehicle-state-errors#in-motion)<br /><br />[REMOTE\_ACCESS\_DISABLED](/errors/api-errors/vehicle-state-errors#remote-access-disabled)<br /><br />[TRUNK\_OPEN](/errors/api-errors/vehicle-state-errors#trunk-open)<br /><br />[UNKNOWN](/errors/api-errors/vehicle-state-errors#unknown)<br /><br />[UNREACHABLE](/errors/api-errors/vehicle-state-errors#unreachable)<br /><br />[VEHICLE\_OFFLINE\_FOR\_SERVICE](/errors/api-errors/vehicle-state-errors#vehicle-offline-for-service) |


# Testing Errors

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

## Connect Errors

You can use the following emails to test a subset of Connect errors:

| Error                  | Email                                                                         | VIN               |
| ---------------------- | ----------------------------------------------------------------------------- | ----------------- |
| `invalid_subscription` | [smartcar@invalid-subscription.com](mailto:smartcar@invalid-subscription.com) | 0SCAUDI0155C49A95 |
| `vehicle_incompatible` | [smartcar@vehicle-incompatible.com](mailto:smartcar@vehicle-incompatible.com) | 0SCAUDI012FE3B132 |

Visit the [Connect Errors](/errors/overview#connect-errors) page for more details.

## API Errors

You can use use the following emails to test these API error types:

*   `COMPATIBILITY`
*   `CONNECTED_SERVICES_ACCOUNT`
*   `UPSTREAM`
*   `VEHICLE_STATE`

| Type                         | Code                          | Email                                                                                                                                    | VIN               |
| ---------------------------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
| `COMPATIBILITY`              | `MAKE_NOT_COMPATIBLE`         | [COMPATIBILITY.MAKE\_NOT\_COMPATIBLE@smartcar.com](mailto:COMPATIBILITY.MAKE_NOT_COMPATIBLE@smartcar.com)                                | 0SCLR000270BE6600 |
| `COMPATIBILITY`              | `SMARTCAR_NOT_CAPABLE`        | [COMPATIBILITY.SMARTCAR\_NOT\_CAPABLE@smartcar.com](mailto:COMPATIBILITY.SMARTCAR_NOT_CAPABLE@smartcar.com)                              | 0SCLR0002DC18F57F |
| `COMPATIBILITY`              | `VEHICLE_NOT_CAPABLE`         | [COMPATIBILITY.VEHICLE\_NOT\_CAPABLE@smartcar.com](mailto:COMPATIBILITY.VEHICLE_NOT_CAPABLE@smartcar.com)                                | 0SCLR00024C7CDF7A |
| `CONNECTED_SERVICES_ACCOUNT` | `ACCOUNT_ISSUE`               | [CONNECTED\_SERVICES\_ACCOUNT.ACCOUNT\_ISSUE@smartcar.com](mailto:CONNECTED_SERVICES_ACCOUNT.ACCOUNT_ISSUE@smartcar.com)                 | 0SCLR00026BAAA136 |
| `CONNECTED_SERVICES_ACCOUNT` | `AUTHENTICATION_FAILED`       | [CONNECTED\_SERVICES\_ACCOUNT.AUTHENTICATION\_FAILED@smartcar.com](mailto:CONNECTED_SERVICES_ACCOUNT.AUTHENTICATION_FAILED@smartcar.com) | 0SCLR00021D803C7B |
| `CONNECTED_SERVICES_ACCOUNT` | `NO_VEHICLES`                 | [CONNECTED\_SERVICES\_ACCOUNT.NO\_VEHICLES@smartcar.com](mailto:CONNECTED_SERVICES_ACCOUNT.NO_VEHICLES@smartcar.com)                     | 0SCLR00027671837B |
| `CONNECTED_SERVICES_ACCOUNT` | `SUBSCRIPTION`                | [CONNECTED\_SERVICES\_ACCOUNT.SUBSCRIPTION@smartcar.com](mailto:CONNECTED_SERVICES_ACCOUNT.SUBSCRIPTION@smartcar.com)                    | 0SCLR0002B9BAF29F |
| `CONNECTED_SERVICES_ACCOUNT` | `VEHICLE_MISSING`             | [CONNECTED\_SERVICES\_ACCOUNT.VEHICLE\_MISSING@smartcar.com](mailto:CONNECTED_SERVICES_ACCOUNT.VEHICLE_MISSING@smartcar.com)             | 0SCLR00024E29EEBD |
| `UPSTREAM`                   | `INVALID_DATA`                | [UPSTREAM.INVALID\_DATA@smartcar.com](mailto:UPSTREAM.INVALID_DATA@smartcar.com)                                                         | 0SCLR000298A0A649 |
| `UPSTREAM`                   | `KNOWN_ISSUE`                 | [UPSTREAM.KNOWN\_ISSUE@smartcar.com](mailto:UPSTREAM.KNOWN_ISSUE@smartcar.com)                                                           | 0SCLR0002A8760B72 |
| `UPSTREAM`                   | `NO_RESPONSE`                 | [UPSTREAM.NO\_RESPONSE@smartcar.com](mailto:UPSTREAM.NO_RESPONSE@smartcar.com)                                                           | 0SCLR0002C23E43AB |
| `UPSTREAM`                   | `UNKNOWN_ISSUE`               | [UPSTREAM.UNKNOWN\_ISSUE@smartcar.com](mailto:UPSTREAM.UNKNOWN_ISSUE@smartcar.com)                                                       | 0SCLR0002D4878901 |
| `VEHICLE_STATE`              | `ASLEEP`                      | [VEHICLE\_STATE.ASLEEP@smartcar.com](mailto:VEHICLE_STATE.ASLEEP@smartcar.com)                                                           | 0SCLR0002E8896323 |
| `VEHICLE_STATE`              | `CHARGING_IN_PROGRESS`        | [VEHICLE\_STATE.CHARGING\_IN\_PROGRESS@smartcar.com](mailto:VEHICLE_STATE.CHARGING_IN_PROGRESS@smartcar.com)                             | 0SCLR000221F1E672 |
| `VEHICLE_STATE`              | `CHARGING_PLUG_NOT_CONNECTED` | [VEHICLE\_STATE.CHARGING\_PLUG\_NOT\_CONNECTED@smartcar.com](mailto:VEHICLE_STATE.CHARGING_PLUG_NOT_CONNECTED@smartcar.com)              | 0SCLR0002CBFC7C21 |
| `VEHICLE_STATE`              | `DOOR_OPEN`                   | [VEHICLE\_STATE.DOOR\_OPEN@smartcar.com](mailto:VEHICLE_STATE.DOOR_OPEN@smartcar.com)                                                    | 0SCLR0002F8BD90B8 |
| `VEHICLE_STATE`              | `FULLY_CHARGED`               | [VEHICLE\_STATE.FULLY\_CHARGED@smartcar.com](mailto:VEHICLE_STATE.FULLY_CHARGED@smartcar.com)                                            | 0SCLR00029CD9D894 |
| `VEHICLE_STATE`              | `HOOD_OPEN`                   | [VEHICLE\_STATE.HOOD\_OPEN@smartcar.com](mailto:VEHICLE_STATE.HOOD_OPEN@smartcar.com)                                                    | 0SCLR000219CD4A2C |
| `VEHICLE_STATE`              | `IGNITION_ON`                 | [VEHICLE\_STATE.IGNITION\_ON@smartcar.com](mailto:VEHICLE_STATE.IGNITION_ON@smartcar.com)                                                | 0SCLR00021D49E58A |
| `VEHICLE_STATE`              | `IN_MOTION`                   | [VEHICLE\_STATE.IN\_MOTION@smartcar.com](mailto:VEHICLE_STATE.IN_MOTION@smartcar.com)                                                    | 0SCLR00024F6EE640 |
| `VEHICLE_STATE`              | `REMOTE_ACCESS_DISABLED`      | [VEHICLE\_STATE.REMOTE\_ACCESS\_DISABLED@smartcar.com](mailto:VEHICLE_STATE.REMOTE_ACCESS_DISABLED@smartcar.com)                         | 0SCLR0002588A5CC1 |
| `VEHICLE_STATE`              | `TRUNK_OPEN`                  | [VEHICLE\_STATE.TRUNK\_OPEN@smartcar.com](mailto:VEHICLE_STATE.TRUNK_OPEN@smartcar.com)                                                  | 0SCLR00023C607FDB |
| `VEHICLE_STATE`              | `UNKNOWN`                     | [VEHICLE\_STATE.UNKNOWN@smartcar.com](mailto:VEHICLE_STATE.UNKNOWN@smartcar.com)                                                         | 0SCLR0002E6CC0314 |
| `VEHICLE_STATE`              | `UNREACHABLE`                 | [VEHICLE\_STATE.UNREACHABLE@smartcar.com](mailto:VEHICLE_STATE.UNREACHABLE@smartcar.com)                                                 | 0SCLR000247EBF067 |
| `VEHICLE_STATE`              | `VEHICLE_OFFLINE_FOR_SERVICE` | [VEHICLE\_STATE.VEHICLE\_OFFLINE\_FOR\_SERVICE@smartcar.com](mailto:VEHICLE_STATE.VEHICLE_OFFLINE_FOR_SERVICE@smartcar.com)              | 0SCLR0002AF1D71A1 |


# Dashboard Configurations



## Configuring Connect

From the dashboard, you can specify which brands you'd like to present to your customers and in which order.
This changes apply only when launching Connect in [default mode](/connect/advanced-config/flows).

<Frame type="glass">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/dashboard-connect.png" />
</Frame>


# Dashboard Multi-Factor Authentication (MFA)



## Configuring Multi-Factor Authentication

From the settings gear, you can access User Security, which supports Multi-Factor Authentication (MFA). Enable MFA and scan with your preferred authenticator app such as Google Authenticator or 1Password.

Once enabled, each following login will require the use of your authenticator app to provide a unique code for login.

MFA can be disabled for your user at any time, though the authenticator app will be required to disable MFA.

<Frame type="glass">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/dashboard-mfa.png" />
</Frame>


# Dashboard Overview

All you need to know about the Smartcar Dashboard

You can sign up for a Smartcar account [here](https://dashboard.smartcar.com/signup).
The Smartcar Dashboard allows you to manage your application configurations, connected vehicles and billing settings.
As well as invite team members, create simulated vehicles and set up webhooks.

<Frame type="glass">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/dashboard-overview.png" />
</Frame>


# 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 region, make, model and year as well as the vehicle state to test with. Watch your simulated vehicle travel in real-time from the Smartcar Dashboard as you test API requests from your application with realistic vehicle data responses.

<Frame type="glass">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/dashboard-simulator.png" />
</Frame>

## 1. Create a simulated vehicle

#### Create a simulated vehicle

Begin by logging into the Smartcar Dashboard and navigating to the Simulator tab. Choose your region and select a Smartcar-compatible vehicle using the Make, Model, and Year dropdowns. Or, use the VIN search feature to create a simulated vehicle of the same Make, Model and Year as the VIN entered, as long as the vehicle is compatible with Smartcar. Please note the VIN search is only available for US-based VINs at this time.

#### Review the vehicle capabilities

Confirm the vehicle's supported capabilities includes those you wish to test.

#### Select a vehicle state

Select from one of three available vehicle states for your simulated vehicle. The states vary in duration from 8 to 24 hours and include driving, charging, and parked vehicle states for a wide range of test scenarios.

## 2. Connect your app to the simulated vehicle

Once you've selected a vehicle and state, you are ready to connect the simulated vehicle to your application for testing.

Grab the simulated vehicle credentials
On the simulation screen, you will find a Connect Credentials button that will open a modal containing the simulated vehicle's credentials. You will need these to connect your app and vehicle using Smartcar Connect.

#### Launch Smartcar Connect in simulated mode

When launching Smartcar Connect, pass in the query parameter mode=simulated to enable simulated mode and ensure you can connect to your newly created simulated vehicle. Smartcar's SDKs provide a convenient option to facilitate this:

<CodeGroup>
  ```js Node
  const client = new smartcar.AuthClient({
    clientId: CLIENT_ID,
    clientSecret: CLIENT_SECRET,
    redirectUri: REDIRECT_URI,
    mode: "simulated",
  });
  ```

  ```python Python
  client = smartcar.AuthClient(
    client_id=CLIENT_ID,
    client_secret=CLIENT_SECRET,
    redirect_uri=REDIRECT_URI,
    mode="simulated"
  )
  ```

  ```java Java
  AuthClient authClient = new AuthClient.Builder()
    .clientId(CLIENT_ID)
    .clientSecret(CLIENT_SECRET)
    .redirectUri(REDIRECT_URI)
    .mode("simulated")
    .build();
  ```

  ```ruby Ruby
  client = Smartcar::AuthClient.new({
    client_id: CLIENT_ID,
    client_secret: CLIENT_SECRET,
    redirect_uri: REDIRECT_URI,
    mode: "simulated"
  })
  ```
</CodeGroup>

#### Log into a connected services account

After launching Smartcar Connect, select the brand that matches your simulated vehicle and enter the credentials pulled from the Smartcar Dashboard simulation screen on the brand login page. You will then be prompted to grant access to your selected permissions.

Upon completing the Smartcar Connect flow, return to the Smartcar Dashboard. It may take up to a minute to reflect that your vehicle is now connected. Once connected, the vehicle ID will appear next to the vehicle's VIN near the top of the simulation screen.

## 3. Start the simulation and begin testing

Once the vehicle is connected to your application, you are ready to start the simulation and begin making API requests to the simulated vehicle.

### Start the simulation

In the Smartcar Dashboard on the simulation screen for your selected simulated vehicle, start the simulation by pressing the Play button. You have the option to pause, resume or restart the simulation at any time. Additional controls you have over the simulation:

#### Control the simulation speed

You can control the simulation's speed in case you would like to test the vehicle at various stages at a faster or slower pace.

#### Change the simulation stage

Once the simulation has started, you can jump to any stage of the simulation in the event you would like to test the vehicle in a particular state.

#### Set the API response latency

Control the response latency of any API requests you make to the simulated vehicle.

`Ideal` - API responses are returned immediately upon request.

`Realistic` - API responses are delayed a certain amount of time based on average API response latency statistics that Smartcar has gathered for each supported brand.

A breakdown of estimated response latencies can be viewed by clicking on the ‘View latencies’ link directly underneath the Request Latency dropdown in the Dashboard. Please note latency estimates may not be available for all brands. In these cases, the Realistic setting will return immediate responses -- same as Ideal.

#### Change the vehicle state

You can select a different vehicle state for your simulated vehicle at any time. Select the Edit icon in the `Trip type` card on the simulation screen.

### Send an API request to the simulated vehicle

The Smartcar API will return realistic data matching the current state of the simulated vehicle as displayed on the simulation screen. Note that if you've selected Realistic API response latency, the data returned to your application may appear somewhat delayed.


# Charging Station Utilization

This guide explains how to use the Smartcar API to enhance charging station discoverability by leveraging vehicle data such as state of charge,  battery level, range, and location. These capabilities allow developers to help EV drivers find nearby charging stations based on real-time vehicle data.

## Prerequisites: Creating your application

Before implementing the Smartcar API for charging station discoverability,
ensure you have:

*   Created a Smartcar Account and registered your application to obtain your
    `client_id` and `client_secret`.
*   Set up Smartcar Connect Flow to authenticate and authorize users.

<Note> For more details, refer to the [Getting Started
Guide](/getting-started/introduction). </Note>

## Smartcar API Endpoints for charging station discoverability

Use the following Smartcar API endpoints to help drivers locate nearby charging
stations based on their vehicle’s current range and location.

### 1. Determine EV Range

Once a vehicle is authorized via Smartcar’s Connect flow, you can use the
vehicle’s access token to retrieve the current battery level and range through
the [GET /battery](/api-reference/evs/get-battery-level) endpoint.

```curl Range Remaining and SoC
    GET /vehicles/{vehicle_id}/battery
```

```json Example Response
{
    "percentRemaining": 0.3,
    "range": 40.5
}
```

### 2. Retrieve Vehicle Location

To locate nearby charging stations based on the vehicle’s current location, use
the [GET /location](/api-reference/get-location) endpoint.

```curl Location
    GET /vehicles/{vehicle_id}/location
```

```json Example Response
{
    "latitude": 37.4292,
    "longitude": -122.1381
}
```

### 3. Calculate Distance to Charging Stations

Once you have the vehicle's location, compare it with nearby charging stations’
coordinates. Charging station locations can be sourced from a Charge Point
Operator (CPO) or through third-party services such as Google’s Places API.
Calculate the distance and estimated time to reach these stations using Google’s
Distance Matrix API or a similar service.

*   Sourcing Charging Station Data: While Smartcar provides vehicle location data,
    you’ll need to source station coordinates from a CPO database or third-party API
    like Google’s Places API.
*   Distance Calculation: Use Google’s Distance Matrix API to compute the travel
    distance and time, factoring in real-time traffic conditions and travel modes.
    This process helps drivers locate the nearest available charging stations in
    real time, offering a smooth and integrated experience.

This process helps drivers locate the nearest available charging stations in
real time, offering a smooth and integrated experience.

### 4. Send Destination to Vehicle Navigation (Optional)

Once you’ve identified the nearest charging station, guide the driver to the
location. Depending on the vehicle’s capabilities, there are two options for
navigation:

1.  **Mobile Navigation Apps**: For vehicles that don’t support in-dash
    navigation, dispatch the destination coordinates to a mobile app (e.g., Google
    Maps, Apple Maps). This ensures drivers can still navigate using their
    smartphone..
2.  **Send to in-dash navigation**: For vehicles that support in-dash
    navigation, Smartcar allows you to send destination coordinates directly to the
    onboard system. This allows for seamless, in-vehicle routing. You can check
    which brands support this feature by visiting the Supported Brands section.

Use [Send Destination](/api-reference/send-destination-to-vehicle) for supported
vehicles to send coordinates to the vehicle's navigation.

```curl Send Destination
    POST /vehicles/navigation/destination
    {
        "latitude": 37.4292,
        "longitude": -122.1381
    }
```

## FAQs

<AccordionGroup>
  <Accordion title="Does this use case require regular polling or scheduled polling?">
    Scheduled polling is recommended for passive monitoring of vehicle data. For
    real-time use cases, such as finding the nearest charging station based on
    current range and location, sending requests on-demand is more efficient.
  </Accordion>

  <Accordion
    title="What additional data sources are needed besides the
    SmartcarAPI?"
  >
    To locate nearby charging stations, you will need external data sources to
    locate nearby charging stations. This data can be sourced from Charge Point
    Operators (CPOs) or third-party services like Google’s Places API. You may
    also use public databases such as the National Renewable Energy Laboratory
    (NREL) API for detailed information on charging station availability and
    locations.

    You may also wish to use Google’s Distance Matrix API to help
    calculate drive distance and time based on real-time traffic conditions.
  </Accordion>

  <Accordion title="Is the Smartcar API charger-agnostic?">
    Yes, Smartcar’s API enables integration with any charging station network by
    providing vehicle data through our platform.
  </Accordion>
</AccordionGroup>


# Plan Your Integration



There are 3 main steps to integrate Smartcar into your application to make API requests to vehicles:

1.  Launch Connect to get consent from the vehicle owner
2.  Fetch an access token
3.  Make a request to the vehicle

## The architecture that's right for you

[Smartcar Connect](/connect/what-is-connect) is Smartcar’s [OAuth 2.0](https://oauth.net/2/) authorization flow. It is your users’ first and only touchpoint with Smartcar. After a user enters the Smartcar Connect
flow and authorizes their vehicle(s), your application is able to make requests to the Smartcar API. Those requests allow your application to retrieve information and send commands to the
user’s vehicle(s), such as reading the odometer and unlocking the doors.

<Tip>
  Depending on your web or mobile application architecture, you can implement the Smartcar Connect flow in different ways.
</Tip>

<Tabs>
  <Tab title="Mobile Application">
    <Frame type="simple">
      <img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/integration-overview/MobileArchitecture.png" />
    </Frame>

    <Steps>
      <Step title="User launches Connect">
        Using the Smartcar iOS SDK or the Smartcar Android SDK, your application launches Smartcar Connect in a browser view. The user logs in with the username and password of their vehicle’s connected services account and grants your application access to their vehicle.
      </Step>

      <Step title="User logs in to their vehicle's connected services account">
        The browser view gets redirected to a special custom-scheme `REDIRECT_URI`. For more details on how to configure a custom-scheme `REDIRECT_URI`, see our API reference.
      </Step>

      <Step title="Smartcar redirects the user back to your application">
        Once the user has completed the Smartcar Connect flow, the completion handler in the iOS or Android SDK is invoked with the authorization code.
      </Step>

      <Step title="Call your back-end service">
        Your mobile application sends the authorization `code` to its back-end service.
      </Step>

      <Step title="Fetch your first tokens">
        In order to exchange the authorization `code` for an `ACCESS_TOKEN`, your application makes a request to the Smartcar API. This request must contain the authorization code along with your application’s `CLIENT_ID` and `CLIENT_SECRET`.
      </Step>

      <Step title="Store your tokens">
        In response, Smartcar returns an `ACCESS_TOKEN` and a `REFRESH_TOKEN`. These should be stored in your application’s database.
      </Step>

      <Step title="Make an API request">
        Using the `ACCESS_TOKEN`, your application can now make API requests to the user’s vehicle.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Single-Page Application">
    <Frame type="simple">
      <img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/integration-overview/SPAArchitecture.png" />
    </Frame>

    <Steps>
      <Step title="User launches Connect">
        Using the [Smartcar JavaScript SDK](https://github.com/smartcar/javascript-sdk), your application launches Smartcar Connect in a pop-up window. The user logs in with the username and password of their vehicle’s connected services account and grants your application access to their vehicle. If you are interested in building a web application that uses Node for API access, check out our [starter applications on Github](https://github.com/smartcar/starter-app-react-node).
      </Step>

      <Step title="User logs in to their vehicle's connected services account">
        The user’s browser gets redirected to a special Smartcar-hosted `REDIRECT_URI`. For more details on how to configure a Smartcar-hosted `REDIRECT_URI`, see our [API reference](/api-reference).
      </Step>

      <Step title="Smartcar redirects the user back to your application">
        Once the user has completed the Smartcar Connect flow, the `onComplete` callback in the JavaScript SDK is invoked with the authorization `code`.
      </Step>

      <Step title="Call your back-end service">
        Your application front end sends the authorization `code` to its back-end service.
      </Step>

      <Step title="Fetch your first tokens">
        In order to exchange the authorization `code` for an `ACCESS_TOKEN`, your application makes a request to the Smartcar API. This request must contain the authorization code along with your application’s `CLIENT_ID` and `CLIENT_SECRET`.
      </Step>

      <Step title="Store your tokens">
        In response, Smartcar returns an `ACCESS_TOKEN` and a `REFRESH_TOKEN`. These should be stored in your application’s database.
      </Step>

      <Step title="Make an API request">
        Using the `ACCESS_TOKEN`, your application can now make API requests to the user’s vehicle.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Server-side Rendered Application">
    <Frame type="simple">
      <img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/integration-overview/ServerSideArchitecture.png" />
    </Frame>

    <Steps>
      <Step title="User launches Connect">
        You can use your preferred language framework for a server-side setup as long as you use [OAuth2 Retrieval protocol](https://oauth.net/2/). In this case:

        1.  Your application redirects the user’s browser to Smartcar Connect.
        2.  The user logs in with the username and password of their vehicle’s connected services account.
        3.  The user grants your application access to their vehicle.
      </Step>

      <Step title="Smartcar redirects the user back to your application">
        The Smartcar Connect flow is now complete and the user’s browser gets redirected to a specified `REDIRECT_URI`. Your application’s server, which is listening at the `REDIRECT_URI`, retrieves the authorization `code` from query parameters in the `REDIRECT_URI`.
      </Step>

      <Step title="Fetch your first tokens">
        In order to exchange the authorization `code` for an `ACCESS_TOKEN`, your application makes a request to the Smartcar API. This request must contain the authorization `code` along with your application’s `CLIENT_ID` and `CLIENT_SECRET`.
      </Step>

      <Step title="Store your tokens">
        In response, Smartcar returns an `ACCESS_TOKEN` and a `REFRESH_TOKEN`. These should be stored in your application’s database.
      </Step>

      <Step title="Make an API request">
        Using the `ACCESS_TOKEN`, your application can now make API requests to the user’s vehicle.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Let's get building

Now you have an idea of how Smartcar works, take a look at one of our Getting Started guides in the tutorials section to get connected to a vehicle.

{/* <Frame type="simple" caption="Smartcar Connect">
  <img src="/images/integration-overview/StandardFlow.png" />
</Frame> */}

{/* ## 2. Adapt Smartcar Connect to your use case

### Fit Smartcar Connect into the user journey

To increase conversions and maximize your users’ satisfaction, it is crucial to launch Smartcar Connect at the right moment in your product’s user journey.

We recommend prompting the user to connect their car through Smartcar Connect while they are onboarding their vehicle to your application for the first time.

### Standard: Let the user connect one or more vehicles

In the standard Smartcar Connect flow, the user selects their car brand and logs in with the username and password of their vehicle’s connected services account. On the next screen, the user can see all vehicles associated with their account. The user can select one or multiple of these vehicles and grant your application access to them.



We recommend using the standard Smartcar Connect flow whenever you don’t yet know the make or VIN of your user’s vehicle(s). If you know the make or VIN of your user’s vehicle(s), we recommend personalizing the Smartcar Connect flow in the following ways:

### Optional: Skip the car brand selection screen

If you know the make of your user’s vehicle(s) prior to launching Smartcar Connect, we recommend using [Brand Select](https://smartcar.com/docs/api#brand-select). Brand Select causes the user to automatically skip the car brand selection screen. Instead, the user lands directly on their vehicle brand’s login screen. This speeds up the onboarding experience and increases conversions.

<Frame type="glass">
  <img src="/images/ConnectDirect.png" />
</Frame>

### Optional: Check a vehicle’s eligibility before launching Smartcar Connect

If you know the VIN of your user’s vehicle prior to launching Smartcar Connect, we recommend using the [Compatibility API](/api-reference). The Compatibility API lets you verify a vehicle’s eligibility before sending a user through Smartcar Connect. That way, your application will show Smartcar Connect to users with compatible vehicles only.

<Info>
  The Compatibility API is only available for vehicles sold in the United
  States.
</Info>

### Optional: Make sure the user connects the right vehicle

If you know the VIN of your user’s vehicle prior to launching Smartcar Connect, we recommend using [Single Select](https://smartcar.com/docs/api#single-select). Single Select causes the user to skip the car brand selection screen. It also limits them to connecting only the vehicle with that specific VIN, even if the user has registered multiple vehicles under the same connected services account. This simplifies the user experience and guarantees that the user connects the right vehicle to your application.

<Frame type="glass">
  <img src="/images/ConnectMatch.png" />
</Frame>

## 3. Set optional and/or required permissions

When [redirecting a user to Smartcar Connect](https://smartcar.com/docs/api#smartcar-connect), you need to include a `scope` parameter that indicates which permissions your application requests access to. Every vehicle endpoint has a permission name associated with it. For example, the permission name for the [/fuel endpoint](/api-reference/EVs/EV-charging-limit) is `read_fuel`. Please see our [API reference](/api-reference) for a full list of all permission names.

### Optional permissions

Not all vehicles are capable of all permissions. For example, Tesla vehicles aren’t capable of the `read_fuel` permission, because they don’t have fuel tanks. In order to handle this smoothly, all permissions that your application requests access to in Smartcar Connect are optional by default.

For example, let’s assume that your app requests access to the `read_location` and the `read_fuel` permissions. A user connects their Tesla vehicle through Smartcar Connect. The user is able to successfully authorize their vehicle, because both, the `read_location` and the `read_fuel` permission are optional. In the background, your application is granted permission to the `read_location` endpoint only, because the vehicle is incapable of the read_fuel permission.

In order to verify which permissions your application was granted access to, make a request to the [/permissions endpoint](/api-reference/vehicles/revoke-access):

<CodeGroup>

```java Node
const permissions = await vehicle.permissions();
console.log(permissions);
```

```python Python
response = vehicle.permissions()
print(response)
```

```java Java
ApplicationPermissions response = vehicle.permissions();
System.out.println(response);
```

```ruby Ruby
response = vehicle.permissions
puts response.permissions
```

</CodeGroup>

### Required permissions

If certain permissions are essential to your application’s use case, you can make them required by adding the `required`: prefix to each pertaining permission within the `scope` parameter (e.g. `required:read_fuel`). The user is then able to authorize a vehicle only if the vehicle is capable of all required permissions.

For example, let’s assume that you mark both `read_location` and `read_fuel` as required in the scope parameter. A user tries to connect their Tesla vehicle through Smartcar Connect. As Tesla vehicles are incapable of the read_fuel permission, the user isn’t able to successfully authorize their vehicle. Instead, Smartcar sends the vehicle_incompatible error back to your application.

<CodeGroup>

```java Node
const client = new smartcar.AuthClient({
  clientId: CLIENT_ID,
  clientSecret: CLIENT_SECRET,
  redirectUri: REDIRECT_URI,
});
const scope = ["required:read_location", "required:read_fuel"];
const authUrl = client.getAuthUrl(scope);
```

```python Python
client = smartcar.AuthClient(
  client_id=CLIENT_ID,
  client_secret=CLIENT_SECRET,
  redirect_uri=REDIRECT_URI,
)
scope = ['required:read_location', 'required:read_fuel']
auth_url = client.get_auth_url(scope=scope)
```

```java Java
AuthClient authClient = new AuthClient.Builder()
    .clientId(CLIENT_ID)
    .clientSecret(CLIENT_SECRET)
    .redirectUri(REDIRECT_URI)
    .build();
String[] scope = new String[]{"required:read_location", "required:read_fuel"};
String authUrl = authClient.authUrlBuilder(scope).build();
```

```ruby Ruby
client = Smartcar::AuthClient.new({
  client_id: CLIENT_ID,
  client_secret: CLIENT_SECRET,
  redirect_uri: REDIRECT_URI,
})
scope = %w(required:read_location required:read_fuel)
auth_url = client.get_auth_url(scope)
```

</CodeGroup> */}


# Introduction to Smartcar's API

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

<img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/smartcar-api.png" />

<CardGroup cols={3}>
  <Card title="Get Started" icon="play" href="/getting-started/integration-overview" icontype="duotone" />

  <Card title="Connect Docs" href="/connect/what-is-connect" icon="mobile" icontype="duotone" />

  <Card title="API Reference" href="/api-reference" icon="square-terminal" icontype="duotone" />

  <Card title="Tutorials" href="/getting-started/tutorials/ios" icon="graduation-cap" icontype="duotone" />

  <Card title="Handling Errors" href="/errors/overview" icon="cloud-exclamation" icontype="duotone" />

  <Card title="Help Center" href="/help/" icon="life-ring" icontype="duotone" />
</CardGroup>

Smartcar is the only car API built with the highest standard for privacy and security. We allow your application to communicate with millions of vehicles easily and securely while giving vehicle owners the choice of how they share their data.

Below are a few concepts to help you get familiar with Smartcar's API.

Let’s get building!

## What you need before you get started

Before making requests to a vehicle, the owner must grant your application permission to access their data. To request permission from the vehicle owner, you must present the Smartcar Connect flow to the user. To launch Smartcar Connect, you need to:

<Steps>
  <Step title="Get your credentials and configure your app">
    Register an application and get your `CLIENT_ID` and `CLIENT_SECRET`. Set a `REDIRECT_URI` to the path where Smartcar will redirect your users after they grant permission to your app. You can get these from the [Smartcar Dashboard](https://dashboard.smartcar.com/).
  </Step>

  <Step title="Launch Smartcar Connect">
    With your `CLIENT_ID` and `REDIRECT_URI` you can launch [Connect](/connect). This is how you and your users can add vehicles to your application.
  </Step>

  <Step title="Exchange and store your tokens">
    Once users authorize your app to access their vehicles, you receive a `code` that you can exchange for an `ACCESS_TOKEN` and `REFRESH_TOKEN`. Make sure to store these tokens in a secure place (like your application's database). You need the access token to make requests to the Smartcar API. More information can be found in our [Token Management Overview](https://smartcar.com/docs/connect/token-management/overview).
  </Step>
</Steps>


# Test Your Integration



Before launching your integration, use Smartcar’s simulated mode to quickly test your application.

If you prefer to control the vehicle type and receive consistent data in API responses, consider using Smartcar’s [Vehicle Simulator](/getting-started/dashboard/simulator)

If you are not testing with a simulated vehicle, Simulated mode will randomized data for every API request.

## Test successful API requests

### 1. Enabling simulated mode

When launching Smartcar Connect, pass in the query parameter `mode=simulated` to enable simulated mode. Smartcar’s SDKs provide a convenient option to facilitate this:

<CodeGroup>
  ```node Node
  const client = new smartcar.AuthClient({
    clientId: CLIENT_ID,
    clientSecret: CLIENT_SECRET,
    redirectUri: REDIRECT_URI,
    mode: 'simulated',
  });
  ```

  ```python Python
  client = smartcar.AuthClient(
    client_id=CLIENT_ID,
    client_secret=CLIENT_SECRET,
    redirect_uri=REDIRECT_URI,
    mode='simulated'
  )
  ```

  ```java Java
  AuthClient authClient = new AuthClient.Builder()
    .clientId(CLIENT_ID)
    .clientSecret(CLIENT_SECRET)
    .redirectUri(REDIRECT_URI)
    .mode("simulated")
    .build();
  ```

  ```ruby Ruby
  client = Smartcar::AuthClient.new({
    client_id: CLIENT_ID,
    client_secret: CLIENT_SECRET,
    redirect_uri: REDIRECT_URI,
    mode: 'simulated'
  })
  ```
</CodeGroup>

### 2. Log into a simulated connected services account

User your simulated vehicle credentials to log in, or select any vehicle brand and log in with any email address `(anything@anything.com)` and any password.

### 3. Send an API request to the simulated vehicle

Our API will return simulated data for each endpoint the simulated vehicle is able to provide, or randomized data for each other endpoint.

For example, a simulated Tesla will return battery capacity consistently, but will return randomized data if fuel level is requested.

See our API reference to learn more about the randomized data you should expect. If you use Single Select, use the below VIN and make a request as follows.

| Email                             | VIN               |
| --------------------------------- | ----------------- |
| `smartcar@successful-request.com` | 0SCAUDI037A5ADB1C |

<CodeGroup>
  ```node Node
  const scope = ["read_vehicle_info"]
  const options = singleSelect: {vin: '0SCAUDI037A5ADB1C'}
  authUrl = client.getAuthUrl(scope, options);
  ```

  ```python Python
  scope = ['read_vehicle_info']
  options = { single_select={'vin': '0SCAUDI037A5ADB1C'} }
  auth_url = client.get_auth_url(scope, options)
  ```

  ```java Java
  String authUrl = authClient.authUrlBuilder()
    .singleSelect(true)
    .singleSelectVin("0SCAUDI037A5ADB1C")
    .build();
  ```

  ```ruby Ruby
  scope = %w(read_vehicle_info)
  options = { "singleSelect": { vin: "0SCAUDI037A5ADB1C" } }
  auth_url = client.get_auth_url(scope, options)
  ```
</CodeGroup>

## Test successful API requests with specific VINs

If you need a test vehicle with a specific VIN, you can still use simulated mode. When logging into a test mode connected services account (step 2 above), follow this format for the email address:

`<VIN>@<compatibility level>.smartcar.com`

**VIN**: This can be any 17-character alphanumeric string. Note: This string does not need to be a real VIN. Smartcar does not perform any VIN-specific validations.

**Compatibility level**: This string determines which permissions the test mode vehicle is capable of. The following table contains all valid compatibility levels and their corresponding permissions:

| Compatibility level | Permissions                                          |
| ------------------- | ---------------------------------------------------- |
| compatible OR phev  | All permissions                                      |
| incompatible        | No permissions                                       |
| fuel                | Permissions that apply to a gasoline vehicle         |
| bev                 | Permissions that apply to a battery-electric vehicle |

To use Single Select in test mode with a specific VIN, follow step 3 above and replace the Smartcar-provided VIN with the VIN of your choice. Then follow the email format `<VIN>@<compatibility level>.smartcar.com` using the same VIN.

## Test with multiple vehicles

In some cases, you may want to test the Connect flow with an account that has more vehicles than our default test accounts to help ensure your application is paginating and fetching data for a large number of vehicles correctly. You can do this with the following email format in Test mode and any password:

`<number>-vehicles@smartcar.com`

Number: Any number from 1-999. Smartcar will show this many vehicles on the permission grant screen and return this many vehicles from the /vehicles endpoint, with pagination.


# Android Tutorial

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

<Warning>
  Our frontend SDKs handle getting an authorization code representing a vehicle owner's consent for your application to interact with their vehicle
  for the requested permissions. In order to make requests to a vehicle, please use one of our [backend SDKs](/api-reference/api-sdks).

  For security, token exchanges and requests to vehicles **should not** be made client side.
</Warning>

# Overview

<Frame type="simple">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/android/overview.png" />
</Frame>

<br />

1.  The Mobile Application launches a `Chrome Custom Tab` with Smartcar Connect to request access to a user’s vehicle.
    On Connect, the user logs in with their vehicle credentials and grants the Application access to their vehicle.
2.  The `Chrome Tab` is redirected to a specified `REDIRECT_URI` along with an authorization `code`.
    This will be the custom scheme set on the application. The Smartcar Android receives the authorization `code` in a view listening
    for the specified custom scheme URI, and passes it to the Mobile Application.
3.  The Mobile Application sends the received authorization `code` to the Application’s backend service.
4.  The Application sends a request to the Smartcar API. This request contains the authorization code along with the Application’s
    `CLIENT_ID` and `CLIENT_SECRET`.
5.  In response, Smartcar returns an `ACCESS_TOKEN` and a `REFRESH_TOKEN`.
6.  Using the `ACCESS_TOKEN`, the Application can now send requests to the Smartcar API. It can access protected resources and send commands
    to and from the user’s vehicle via the backend service.

# Prerequisites

*   [Sign up](https://dashboard.smartcar.com/signup) for a Smartcar account.
*   Make a note of your `CLIENT_ID` and `CLIENT_SECRET` from the **Configuration** section on the Dashboard.
*   Add a custom scheme redirect URI to your application configuration.
*   Add the `app_server` redirect URI from [Setup step 2.](/tutorials/android#setup) to your application configuration.

<Note>
  For Android, we require the custom URI scheme to be in the format of `sc` + `clientId` + `://` + `hostname`.
  For now, you can just set it to `sc` + `clientId` + `://exchange`.

  Please see our [Connect Docs](/connect/dashboard-config#redirect-uris) for more information.
</Note>

# Setup

1.  Clone our repo and install the required dependencies:
    ```bash
    $git clone https://github.com/smartcar/getting-started-android-sdk.git
    ```
    <Note>
      Do not “checkout from version control” with the Getting Started repo in Android Studio, as it will not open the proper module.
    </Note>

2.  Open `getting-started-android-sdk/tutorial` in Android Studio as an existing project and build from existing sources.
    Android Studio should automatically import the required dependencies and build gradle. We're setting `app_server` to `http://10.0.2.2:8000`
    to pass the authorization `code` from the [Handle the Response](/tutorials/android#handle-the-response) step later on in the tutorial to our backend.
    ```xml strings.xml
    <string name="smartcar_auth_scheme">sc[yourClientId]</string>
    <string name="client_id">[yourClientId]</string>
    <string name="app_server">http://10.0.2.2:8000</string>
    ```

# Build your Connect URL

1.  Instantiate a `smartcarAuth` object in the `onCreate` function of the `MainActivity`.
    ```java MainActivity.java
    // TODO: Authorization Step 1a: Initialize the Smartcar object
    private static String CLIENT_ID;
    private static String REDIRECT_URI;
    private static String[] SCOPE;
    private SmartcarAuth smartcarAuth;

    protected void onCreate(Bundle savedInstanceState) {
        ...
        
        // TODO: Authorization Step 1b: Initialize the Smartcar object
        CLIENT_ID = getString(R.string.client_id);
        REDIRECT_URI = getString(R.string.smartcar_auth_scheme) + "://" + getString(R.string.smartcar_auth_host);
        SCOPE = new String[]{"required:read_vehicle_info"};
        
        smartcarAuth = new SmartcarAuth(
            CLIENT_ID,
            REDIRECT_URI,
            SCOPE,
            true,
            new SmartcarCallback() {
                // TODO: Authorization Step 3b: Receive an authorization code
            }
        );
    }
    ```

<Info>
  The Android SDK does not support `simulated` mode at this time - only `test` and `live`.
  Feel free to set `testMode` to `false` where you instantiate your `SmartcarAuth` object to
  connect to a real vehicle.
</Info>

2.  The Android application will launch a Chrome Tab with Smartcar Connect to request access to a user’s vehicle.
    On Connect, the user logs in with the username and password for their vehicle’s connected services account and grants the application access to their vehicle.

    To launch Connect, we can use the `addClickHandler` function that our `smartcarAuth` object has access to.

    ```java MainActivity.java
    // TODO: Authorization Step 2: Launch Connect
    smartcarAuth.addClickHandler(appContext, connectButton);
    ```

# Registering your Custom Scheme

Once a user has authorized the application to access their vehicle, the user is redirected to the `REDIRECT_URI` with an authorization `code` as a query parameter.

Android applications use custom URI schemes to intercept calls and launch the relevant application. This is defined within the `AndroidManifest`.

```xml AndroidManifest.xml
<!-- TODO: Authorization Step 3a: Receive an authorization code -->
<activity android:name="com.smartcar.sdk.SmartcarCodeReceiver">
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data
            android:host="@string/smartcar_auth_host"
            android:scheme="@string/smartcar_auth_scheme" />
    </intent-filter>
</activity>
```

# Handle the response

Using the Android SDK, the application can receive the code in the `SmartcarCallback` object passed into the `SmartcarAuth` object.

```java MainActivity.java
smartcarAuth = new SmartcarAuth(
    CLIENT_ID,
    REDIRECT_URI,
    SCOPE,
    true,
    new SmartcarCallback() {
        // TODO: Authorization Step 3b: Receive an authorization code
        @Override
        public void handleResponse(final SmartcarResponse smartcarResponse) {
            Log.i("MainActivity", smartcarResponse.getCode());

            // TODO: Request Step 1: Obtain an access token

            //TODO: Request Step 2: Get vehicle information
        }
    }
);
```

# Launching Connect

Build your application in Android Studio and click on the **Connect your vehicle** button.

<Info>
  This tutorial configures Connect to launch in `test` mode by default.
  In `test` mode, any `username` and `password` is valid for each brand.
</Info>

Smartcar showcases all the permissions your application is asking for - `read_vehicle_info` in this case.
Once you have logged in and accepted the permissions, you should see your authorization `code` printed to your console.

# Getting your first access token

After receiving the authorization `code`, your iOS application must exchange it for an `ACCESS_TOKEN`. To do so, we can send
the code to a backend service. Let’s assume our backend service contains an endpoint `/exchange` that receives an authorization `code` as a query parameter and exchanges it for an `ACCESS_TOKEN`.

```swift ViewController.swift
// TODO: Obtain an access token
public void handleResponse(final SmartcarResponse smartcarResponse) {
    Log.i("MainActivity", smartcarResponse.getCode());

    final OkHttpClient client = new OkHttpClient();

    // TODO: Request Step 1: Obtain and access token

    // Request can not run on the Main Thread
    // Main Thread is used for UI and therefore can not be blocked
    new Thread(new Runnable() {
        @Override
        public void run() {
    
            // send request to exchange the auth code for the access token
            Request exchangeRequest = new Request.Builder()
                .url(getString(R.string.app_server) + "/exchange?code=" + smartcarResponse.getCode())
                .build();
        
            try {
                client.newCall(exchangeRequest).execute();
            } catch (IOException e) {
                e.printStackTrace();
            }
        }
    }).start();
}
```

<Warning>
  Notice that our backend service **does not** return the `ACCESS_TOKEN`.
  This is by design. For security, our frontend should never have access
  to the `ACCESS_TOKEN` and should always be stored in the backend.
</Warning>

# Getting data from a vehicle

Once the backend has the `ACCESS_TOKEN`, it can send requests to a vehicle using the Smartcar API. The Android app will
have to send a request to the backend service which in turn sends a request to Smartcar. We have to do this because
our frontend **does not** have the `ACCESS_TOKEN`.

Assuming our backend has a `/vehicle` endpoint that returns the information of a user’s vehicle, we can make this query in
our `completion callback` and start another `activity` to show the returned vehicle attributes.

```java MainActivity.java
public void handleResponse(final SmartcarResponse smartcarResponse) {
    ...
    
    // TODO: Request Step 2: Get vehicle information

    // send request to retrieve the vehicle info
    Request infoRequest = new Request.Builder()
        .url(getString(R.string.app_server) + "/vehicle")
        .build();
    
    try {
        Response response = client.newCall(infoRequest).execute();
    
        String jsonBody = response.body().string();
        JSONObject JObject = new JSONObject(jsonBody);
    
        String make = JObject.getString("make");
        String model = JObject.getString("model");
        String year = JObject.getString("year");
    
        Intent intent = new Intent(appContext, DisplayInfoActivity.class);
        intent.putExtra("INFO", make + " " + model + " " + year);
        startActivity(intent);
    } catch (IOException e) {
        e.printStackTrace();
    } catch (JSONException e) {
        e.printStackTrace();
    }
}
```

# Setting up your backend

Now that our frontend is complete, we will need to create a backend service that contains the logic for the `/exchange` and `/vehicle` endpoints.
You can use any of our backend SDKs below to set up the service starting from the **Obtaining an Access Token** step.

<Note>
  When setting up the environment variables for your  backend SDK, make sure to set `REDIRECT_URI` to the custom scheme
  used for this tutorial i.e. `sc + "clientId" + ://exchange`.
</Note>

<CardGroup cols={4}>
  <Card title="Java" icon="java" href="/tutorials/backend#getting-your-first-access-token" icontype="duotone" />

  <Card title="Node.js" href="/tutorials/backend#getting-your-first-access-token" icon="node-js" icontype="duotone" />

  <Card title="Python" icon="python" href="/tutorials/backend#getting-your-first-access-token" icontype="duotone" />

  <Card title="Ruby" href="/tutorials/backend#getting-your-first-access-token" icon="gem" icontype="duotone" />
</CardGroup>


# Backend SDK Tutorials

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

# Overview

<Frame type="simple">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/backend-sdks/overview.png" />
</Frame>

<br />

1.  The Application redirects the user to Smartcar Connect to request access to the user’s vehicle. In Connect,
    the user logs in with their vehicle credentials and grants the Application access to their vehicle.
2.  The user’s browser is redirected to a specified `REDIRECT_URI`. The Application Server, which is listening
    at the `REDIRECT_URI`, will retrieve the authorization code from query parameters sent to the `REDIRECT_URI`.
3.  The Application sends a request to the Smartcar API. This request contains the authorization `code` along with
    the Application’s `CLIENT_ID` and `CLIENT_SECRET`.
4.  In response, Smartcar returns an `ACCESS_TOKEN` and a `REFRESH_TOKEN`.
5.  Using the `ACCESS_TOKEN`, the Application can now send requests to the Smartcar API. It can access protected resources and send commands
    to and from the user’s vehicle via the backend service.

# Prerequisites

*   [Sign up](https://dashboard.smartcar.com/signup) for a Smartcar account.
*   Make a note of your `CLIENT_ID` and `CLIENT_SECRET` from the **Configuration** section on the Dashboard.
*   Add the following `REDIRECT_URI` to your application configuration: `http://localhost:8000/exchange`

# Setup

1.  Clone the repo for the SDK you want to use and install the required dependencies:
    <CodeGroup>
      ```bash Node
      $git clone https://github.com/smartcar/getting-started-express.git
      $cd getting-started-express/tutorial
      $npm install
      ```

      ```bash Python
      $git clone https://github.com/smartcar/getting-started-python-sdk.git
      $cd getting-started-python-sdk/tutorial
      $pip install -r requirements.txt
      ```

      ```bash Java
      $git clone https://github.com/smartcar/getting-started-java-sdk.git
      $cd getting-started-java-sdk/tutorial
      $gradlew build
      ```

      ```bash Ruby
      $git clone https://github.com/smartcar/getting-started-ruby-sdk.git
      $cd getting-started-ruby-sdk/tutorial
      $bundle install
      $ruby app.rb
      ```
    </CodeGroup>
2.  You will also have to set the following environment variables

<Warning>
  If you've used one of our frontend SDKs to integrate connect, you'll want to set the
  `SMARTCAR_REDIRECT_URI` environment variable to the URI you used for that application.
</Warning>

```bash
$export SMARTCAR_CLIENT_ID=<your-client-id>
$export SMARTCAR_CLIENT_SECRET=<your-client-secret>
$export SMARTCAR_REDIRECT_URI=http://localhost:8000/exchange
```

<Note>
  If you are using Windows, ensure you are appropriately setting environment variables for your shell.
  Please refer to [this post](https://stackoverflow.com/questions/9249830/how-can-i-set-node-env-production-on-windows/9250168#9250168) which details how to set environment variables on Windows.
</Note>

<br />

# Build your Connect URL

1.  Instantiate a `Smartcar` object in the constructor of the App component.
    <CodeGroup>
      ```js index.js
      const client = new smartcar.AuthClient({
          mode: 'simulated',
      });
      ```

      ```python main.py
      client = smartcar.AuthClient(mode='simulated')
      ```

      ```java Main.java
      String mode = "simulated";

      AuthClient client = new AuthClient.Builder()
      .mode(mode)
      .build();
      ```

      ```ruby index.rb
      @@client = Smartcar::AuthClient.new({
          mode: 'simulated',
      })
      ```
    </CodeGroup>

<Info>
  Feel free to set `mode` to `simulated` or `live` where you instantiate your `Smartcar` object to
  connect to a simulated or real vehicle.
</Info>

2.  A Server-side rendered application will redirect to Smartcar Connect to request access to a user’s vehicle.
    On Connect, the user logs in with the username and password for their vehicle’s connected services account
    and grants the application access to their vehicle.

    To launch Connect, we need to redirect the user to the appropriate URL. We can make use of the `AUTHORIZATION_URL`
    function in our Smartcar object and redirect the user to the URL to launch the Connect flow.

    <CodeGroup>
      ```js index.js
      app.get('/login', function(req, res) {
          const scope = ['read_vehicle_info'];
          const authUrl = client.getAuthUrl(scope);

          res.render('home', {
              url: authUrl,
          });
      });
      ```

      ```python main.py
      @app.route('/login', methods=['GET'])
      def login():
          scope = ['read_vehicle_info']
          auth_url = client.get_auth_url(scope)
          return redirect(auth_url)        
      ```

      ```java Main.java
      get("/login", (req, res) -> {
          // TODO: Authorization Step 2: Launch Smartcar authentication dialog
          String[] scope = {"read_odometer"};
          String link = client.authUrlBuilder(scope).build();
          res.redirect(link);
          return null;
      });
      ```

      ```ruby index.rb
      get "/login" do
          redirect @@client.get_auth_url(['required:read_vehicle_info'])
      end
      ```
    </CodeGroup>

<br />

# Handle the response

Once a user has authorized the application to access their vehicle, the user is redirected to the `REDIRECT_URI`
with an authorization `code` as a query parameter. In the previous section, we had set our `REDIRECT_URI` as `localhost:8000/exchange`.
Now, our server can be set up as follows to receive the authorization `code`.

<CodeGroup>
  ```js index.js
  app.get('/exchange', function(req, res) {
  const code = req.query.code;

  console.log(code);

  res.sendStatus(200);
  });
  ```

  ```python main.py
  @app.route('/exchange', methods=['GET'])
  def exchange():
      code = request.args.get('code')
      
      print(code)
      
      return '', 200      
  ```

  ```java Main.java
  get("/exchange", (req, res) -> {
      String code = req.queryMap("code").value();

      System.out.println(code);

      return "";
  });
  ```

  ```ruby index.rb
  get "/exchange" do
      code = params[:code]

      puts code

      "OK"
  end
  ```
</CodeGroup>

<br />

# Launching Connect

Let’s try authenticating a vehicle! Restart your server, open up your browser and go to `http://localhost:8000/login`

<CodeGroup>
  ```bash Node
  $node index.js
  ```

  ```bash Python
  $python main.py
  ```

  ```bash Java
  $./gradlew run
  ```

  ```bash Ruby
  $bundle exec ruby app.rb
  ```
</CodeGroup>

<br />

<Info>
  This tutorial configures Connect to launch in `test` mode by default.
  In `test` mode, any `username` and `password` is valid for each brand.
</Info>

Smartcar showcases all the permissions your application is asking for - `read_vehicle_info` in this case.
Once you have logged in and accepted the permissions, you should see your authorization `code` printed to your console.

<br />

# Getting your first access token

<Note>
  If you've used one of our frontend SDKs to integrate Connect, this is where you'll need to fetch your access token.
</Note>

In the previous section, we retrieved an authorization `code`. The application must exchange the code for an `ACCESS_TOKEN` to make a request.
After receiving the ACCESS\_TOKEN, the user can be redirected to the `/vehicle` route.

<CodeGroup>
  ```js index.js
  // Global variable to save our access_token
  let access;

  app.get('/exchange', async function(req, res) {
      const code = req.query.code;
      
      // Access our global variable and store our access tokens.
      // In a production app you'll want to store this in some 
      // kind of persistent storage
      access = await client.exchangeCode(code);
      res.redirect('/vehicle');
  });
  ```

  ```python main.py
  # Global variable to save our access_token
  access = None

  @app.route('/exchange', methods=['GET'])
  def exchange():
      code = request.args.get('code')

      # Access our global variable and store our access tokens.
      # In a production app you'll want to store this in some
      # kind of persistent storage
      global access

      access = client.exchange_code(code)
      return redirect('/vehicle')      
  ```

  ```java Main.java
  // Global variable to save our access_token
  private static String access;

  public static void main(String[] args) {

      get("/exchange", (req, res) -> {
          String code = req.queryMap("code").value();

          Auth auth = client.exchangeCode(code);
          
          // Access our global variable and store our access tokens.
          // In a production app you'll want to store this in some 
          // kind of persistent storage
          access = auth.getAccessToken();
          
          res.redirect("/vehicle");
          return null;
      })
  }
  ```

  ```ruby index.rb
  # Global variable to store the token
  @@token = ''

  get "/exchange" do
      code = params[:code]
      # Access our global variable and store our access tokens.
      # In a production app you'll want to store this in 
      # some kind of persistent storage
      @@token = @@client.exchange_code(code)[:access_token]
      redirect '/vehicle'
  end
  ```
</CodeGroup>

<br />

# Getting data from a vehicle

1.  Once the backend service or server-side application has the `ACCESS_TOKEN`, it can send requests to a vehicle using the Smartcar API.
    First we'll need to fetch the `vehicle_id`s associated with the `ACCESS_TOKEN`, then fetch vehicle attributes for one of them. After
    receiving the `vehicle_attributes` object, we can render it in a simple table on the page.
    <CodeGroup>
      ```js index.js
      app.get('/vehicle', async function(req, res) {
          // Get the smartcar vehicleIds associated with the access_token
          const { vehicles } = await smartcar.getVehicles(access.accessToken);
          
          // Instantiate the first vehicle in the vehicle id list
          const vehicle = new smartcar.Vehicle(vehicles[0], access.accessToken);

          // Make a request to Smartcar API
          const attributes = await vehicle.attributes();
          res.render('vehicle', {
              info: attributes, 
          });
      });
      ```

      ```python main.py
      @app.route('/vehicle', methods=['GET'])
      def get_vehicle():
          # Access our global variable to retrieve our access tokens
          global access
          
          # Get the smartcar vehicleIds associated with the access_token
          vehicles = smartcar.get_vehicles(access.access_token)
          vehicle_ids = vehicles.vehicles
          
          # Instantiate the first vehicle in the vehicle id list
          vehicle = smartcar.Vehicle(vehicle_ids[0], access.access_token)

          # Make a request to Smartcar API
          attributes = vehicle.attributes()
          return jsonify({
              "make": attributes.make,
              "model": attributes.model,
              "year": attributes.year    
          })
          '''
          {
              "make": "TESLA",
              "model": "Model S",
              "year": 2014
          }
          '''
      ```

      ```java Main.java
      get("/vehicle", (req, res) -> {

          // Get the smartcar vehicleIds associated with the access_token
          VehicleIds vehiclesResponse = Smartcar.getVehicles(access);
          String[] vehicleIds = vehiclesResponse.getVehicleIds();
          
          // Instantiate the first vehicle in the vehicle id list
          Vehicle vehicle = new Vehicle(vehicleIds[0], access);

          // Make a request to Smartcar API
          VehicleAttributes attributes = vehicle.attributes();
          System.out.println(gson.toJson(attributes));
          
          // {
          //     "id": "36ab27d0-fd9d-4455-823a-ce30af709ffc",
          //     "make": "TESLA",
          //     "model": "Model S",
          //     "year": 2014
          // }
          
          res.type("application/json");
          return gson.toJson(attributes);
      })
      ```

      ```ruby index.rb
      get "/vehicle" do
          code = params[:code]

          # Get the smartcar vehicleIds associated with the access_token
          vehicles =  Smartcar::Vehicle.get_vehicle(token: @@token)
          vehicle_ids = vehicles.vehicles
          
          # Instantiate the first vehicle in the vehicle id list
          vehicle = Smartcar::Vehicle.new(token: @@token, id: vehicle_ids.first)  
          
          # Get the vehicle_attributes object for vehicle
          vehicle_attributes = vehicle.attributes
          vehicle_attributes.slice(*%I(id make model year)).to_json
      end
      ```
    </CodeGroup>

2.  Restart your sever and head back to `http://localhost:8000/login` to go through Connect and make your first API request!
    <CodeGroup>
      ```bash Node
      $node index.js
      ```

      ```bash Python
      $python main.py
      ```

      ```bash Java
      $./gradlew run
      ```

      ```bash Ruby
      $bundle exec ruby app.rb
      ```
    </CodeGroup>


# iOS Tutorial

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

<Warning>
  Our frontend SDKs handle getting an authorization code representing a vehicle owner's consent for your application to interact with their vehicle
  for the requested permissions. In order to make requests to a vehicle, please use one of our [backend SDKs](/api-reference/api-sdks).

  For security, token exchanges and requests to vehicles **should not** be made client side.
</Warning>

<br />

# Overview

<Frame type="simple">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/ios/overview.png" />
</Frame>

<br />

1.  The Mobile Application launches a `SafariView` with Smartcar Connect to request access to a user’s vehicle.
    On Connect, the user logs in with their vehicle credentials and grants the Application access to their vehicle.
2.  The `SafariView` is redirected to a specified `REDIRECT_URI` along with an authorization `code`.
    This will be the custom scheme set on the application. The Smartcar iOS SDK receives the authorization `code` in a view listening
    for the specified custom scheme URI, and passes it to the Mobile Application.
3.  The Mobile Application sends the received authorization `code` to the Application’s back-end service.
4.  The Application sends a request to the Smartcar API. This request contains the authorization code along with the Application’s
    `CLIENT_ID` and `CLIENT_SECRET`.
5.  In response, Smartcar returns an `ACCESS_TOKEN` and a `REFRESH_TOKEN`.
6.  Using the `ACCESS_TOKEN`, the Application can now send requests to the Smartcar API. It can access protected resources and send commands
    to and from the user’s vehicle via the backend service.

# Prerequisites

*   [Sign up](https://dashboard.smartcar.com/signup) for a Smartcar account.
*   Make a note of your `CLIENT_ID` and `CLIENT_SECRET` from the **Configuration** section on the Dashboard.
*   Add a custom scheme redirect URI to your application configuration.
*   Add the `appServer` redirect URI from [Setup step 2](/tutorials/ios#setup) to your application configuration.

<Note>
  For iOS, we require the custom URI scheme to be in the format of `sc` + `clientId` + `://` + `hostname`.
  For now, you can just set it to `sc` + `clientId` + `://exchange`.

  Please see our [Connect Docs](connect/dashboard-config#redirect-uris) for more information.
</Note>

# Setup

1.  Clone our repo and install the required dependencies:
    ```bash
    $git clone https://github.com/smartcar/getting-started-ios-sdk.git
    $cd getting-started-ios-sdk/tutorial
    $pod install
    $open getting-started-ios-sdk.xcworkspace
    ```
2.  Set the following constants in `Constants.swift`. We're setting `appServer` to `http://localhost:8000` to pass the authorization `code` from
    the [Handle the Response](/tutorials/ios#handle-the-response) step later on in the tutorial to our backend.
    ```swift Constants.swift
    struct Constants {
        static let clientId = "<your-client-id>";
        static let appServer = "http://localhost:8000";
    }
    ```

# Build your Connect URL

1.  Instantiate a `SmartcarAuth` object in the `viewdidLoad` function of the `ViewController`.
    {/* Smartcar TODO: testMode: true --> mode: "test" and remove the Info box when the SDK gets updated!!! - Travis J.*/}
    ```swift ViewController.swift
    {/*  TODO: Authorization Step 1: Initialize the SmartcarAuth object */}
    appDelegate.smartcar = SmartcarAuth(
        clientId: Constants.clientId,
        redirectUri: "sc\(Constants.clientId)://exchange",
        testMode: true,
        scope: ["required:read_vehicle_info"],
        completion: completion
    )
    ```

<Info>
  The iOS SDK does not support `simulated` mode at this time - only `test` and `live`.
  Feel free to set `testMode: false` where you instantiate your `SmartcarAuth` object to
  connect to a real vehicle.
</Info>

2.  The iOS application will launch a `SafariView` with Connect to request access to a user’s vehicle.
    On Connect, the user logs in with the username and password for their vehicle’s connected services account
    and grants the application access to their vehicle.

    To launch Connect, we can use the `launchAuthFlow` function that our `SmartcarAuth` object has access to. We can place
    this within the `connectPressed` action function.

    ```swift ViewController.swift
    @IBAction func connectPressed(_ sender: UIButton) {
        {/* TODO: Authorization Step 2: Launch Connect */}
        let smartcar = appDelegate.smartcar!
        smartcar.launchAuthFlow(viewController: self)
    }
    ```

    <br />

# Registering your Custom Scheme

Once a user has authorized the application to access their vehicle, the user is redirected to the `REDIRECT_URI` with an authorization code as a query parameter.

iOS applications use custom URI schemes to intercept calls and launch the relevant application. This is defined within the `Info.plist`.

1.  Open up `Info.plist` and click on the grey arrow next to **URL types**.
2.  Next, click on the grey arrow next to the `Item 0` dictionary and `URL Schemes` array.
3.  Finally, set your `Item 0` string to the redirect URI you set up in the [Prerequisites](/tutorials/ios#prerequisites) section (i.e. 'sc' + clientId).

<Frame>
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/ios/info-plist.png" />
</Frame>

<br />

# Handle the response

1.  The iOS application will now receive the request in the `application:(_:open:options:)` function within the AppDelegate.
    ```swift AppDelegate.swift
    func application(_ application: UIApplication, open url: URL, options: [UIApplicationOpenURLOptionsKey : Any] = [:]) -> Bool {
        {/* TODO: Authorization Step 3a: Receive the authorization code */}
        window!.rootViewController?.presentedViewController?.dismiss(animated: true , completion: nil)
        smartcar!.handleCallback(with: url)
        
        return true
    }
    ```
2.  Using the iOS SDK, the application can receive the code in the `completion callback` passed into the `SmartcarAuth` object.
    ```swift AppDelegate.swift
    func completion(err: Error?, code: String?, state: String?) -> Any {
        {/* TODO: Authorization Step 3b: Receive the authorization code */}
        print(code!);
        {/* prints out the authorization code */}
    }
    ```

# Launching Connect

Build your application in XCode and click on the **Connect your vehicle** button.

<Info>
  This tutorial configures Connect to launch in `test` mode by default.
  In `test` mode, any `username` and `password` is valid for each brand.
</Info>

Smartcar showcases all the permissions your application is asking for - `read_vehicle_info` in this case.
Once you have logged in and accepted the permissions, you should see your authorization `code` printed to your console.

# Getting your first Access Token

After receiving the authorization `code`, your iOS application must exchange it for an `ACCESS_TOKEN`. To do so, we can send
the code to a backend service. Let’s assume our backend service contains an endpoint `/exchange` that receives an authorization `code` as a query parameter and exchanges it for an `ACCESS_TOKEN`.

```swift ViewController.swift
// TODO: Obtain an access token
Alamofire.request("\(Constants.appServer)/exchange?code=\(code!)", method: .get)
    .responseJSON {_ in}
```

<Warning>
  Notice that our backend service **does not** return the `ACCESS_TOKEN`.
  This is by design. For security, our frontend should never have access
  to the `ACCESS_TOKEN` and should always be stored in the backend.
</Warning>

# Getting data from a vehicle

Once the backend has the `ACCESS_TOKEN`, it can send requests to a vehicle using the Smartcar API. The iOS app will
have to send a request to the backend service which in turn sends a request to Smartcar. We have to do this because
our frontend **does not** have the `ACCESS_TOKEN`.

Assuming our backend has a `/vehicle` endpoint that returns the information of a user’s vehicle, we can make this query in
our `completion callback` and segue into another `view` to show the returned  vehicle attributes

```swift ViewController.swift
func completion(err: Error?, code: String?, state: String?) -> Any {

    // send request to exchange auth code for access token
    Alamofire.request("\(Constants.appServer)/exchange?code=\(code!)", method: .get).responseJSON {_ in

        // TODO: Request Step 2: Get vehicle information
        // send request to retrieve the vehicle info
        Alamofire.request("\(Constants.appServer)/vehicle", method: .get).responseJSON { response in
            print(response.result.value!)
            
            if let result = response.result.value {
                let JSON = result as! NSDictionary
                
                let make = JSON.object(forKey: "make")!  as! String
                let model = JSON.object(forKey: "model")!  as! String
                let year = String(JSON.object(forKey: "year")!  as! Int)
                
                let vehicle = "\(year) \(make) \(model)"
                self.vehicleText = vehicle
                
                self.performSegue(withIdentifier: "displayVehicleInfo", sender: self)
            }
        }
    }
    
    return ""
}
```

# Setting up your backend

Now that our frontend is complete, we will need to create a backend service that contains the logic for the `/exchange` and `/vehicle` endpoints.
You can use any of our backend SDKs below to set up the service starting from the **Obtaining an Access Token** step.

<Note>
  When setting up the environment variables for your  backend SDK, make sure to set `REDIRECT_URI` to the custom scheme
  used for this tutorial i.e. `sc + "clientId" + ://exchange`.
</Note>

<CardGroup cols={4}>
  <Card title="Java" icon="java" href="/tutorials/backend#getting-your-first-access-token" icontype="duotone" />

  <Card title="Node.js" href="/tutorials/backend#getting-your-first-access-token" icon="node-js" icontype="duotone" />

  <Card title="Python" icon="python" href="/tutorials/backend#getting-your-first-access-token" icontype="duotone" />

  <Card title="Ruby" href="/tutorials/backend#getting-your-first-access-token" icon="gem" icontype="duotone" />
</CardGroup>


# React Tutorial

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

<Warning>
  Our frontend SDKs handle getting an authorization code representing a vehicle owner's consent for your application to interact with their vehicle
  for the requested permissions. In order to make requests to a vehicle, please use one of our [backend SDKs](/api-reference/api-sdks).

  For security, token exchanges and requests to vehicles **should not** be made client side.
</Warning>

<br />

# Overview

<Frame type="simple">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/react/overview.png" />
</Frame>

<br />

1.  The Single-Page Application launches a pop-up window with Smartcar Connect to request access to a user’s vehicle.
    It does so by using the Smartcar JavaScript SDK. On Connect, the user logs in with the username and password for
    their vehicle’s connected services account and grants the Application access to their vehicle.
2.  The user’s browser is redirected to a specified Smartcar-hosted `REDIRECT_URI` - the Smartcar JavaScript SDK redirect page.
3.  The Smartcar JavaScript SDK redirect page will receive an authorization `code` as a query parameter. The redirect page will then
    send the code to the Single-Page Application’s `onComplete` callback using the `postMessage` web API. **This step is handled entirely
    by the JavaScript SDK.**
4.  The Single-Page Application sends the received authorization `code` to the Application’s backend service.
5.  The Application sends a request to the Smartcar API. This request contains the authorization code along with the Application’s
    `CLIENT_ID` and `CLIENT_SECRET`.
6.  In response, Smartcar returns an `ACCESS_TOKEN` and a `REFRESH_TOKEN`.
7.  Using the `ACCESS_TOKEN`, the Application can now send requests to the Smartcar API. It can access protected resources and send commands
    to and from the user’s vehicle via the backend service.

# Prerequisites

*   [Sign up](https://dashboard.smartcar.com/signup) for a Smartcar account.
*   Make a note of your `CLIENT_ID` and `CLIENT_SECRET` from the **Configuration** section on the Dashboard.
*   Add the special JavaScript SDK redirect URI to your application configuration.
*   Add the `REACT_APP_SERVER` redirect URI from [Setup step 2.](/tutorials/react#setup) to your application configuration.

<Note>
  To use the JavaScript SDK, we require the special redirect URI to provide a simpler flow to retrieve authorization codes.
  For this tutorial you can use the following:

  `https://javascript-sdk.smartcar.com/v2/redirect?app_origin=http://localhost:3000`
</Note>

# Setup

1.  Clone our repo and install the required dependencies:
    ```bash
    $git clone https://github.com/smartcar/getting-started-javascript-sdk-react.git
    $cd getting-started-javascript-sdk-react/tutorial
    $npm install
    ```
2.  Set the following environment variables. We will be setting up a server later for our React front-end to communicate with.
    For now, let’s assume our server is listening on `http://localhost:8000`.
    ```bash
    $export REACT_APP_CLIENT_ID=<your-client-id>
    $export REACT_APP_REDIRECT_URI= https://javascript-sdk.smartcar.com/v2/redirect?app_origin=http://localhost:3000
    $export REACT_APP_SERVER=http://localhost:8000
    ```

<Note>
  Note: If you are using Windows, ensure you are appropriately setting environment variables for your shell.
  Please refer to this post which details how to set environment variables on Windows.
</Note>

# Build your Connect URL

1.  Instantiate a `Smartcar` object in the `constructor` of the App component.
    ```js App.jsx
    constructor(props) {
    ...
    // TODO: Authorization Step 1: Initialize the Smartcar object
    this.smartcar = new Smartcar({
        clientId: process.env.REACT_APP_CLIENT_ID,
        redirectUri: process.env.REACT_APP_REDIRECT_URI,
        scope: ['required:read_vehicle_info'],
        mode: 'test',
        onComplete: this.onComplete,
    });
    }
    ```

<Snippet file="tutorials/info-mode-callout.mdx" />

2.  A single-page application will launch a pop-up window with Smartcar Connect to request access to a user’s vehicle.
    On Connect, the user logs in with the username and password for their vehicle’s connected services account and grants
    the application access to their vehicle.

    To launch Connect, we can use the `openDialog` function that our `Smartcar` object has access to. We can place this is
    an `onClick` handler of an HTML button.

    ```js App.jsx
    authorize() {
        // TODO: Authorization Step 2a: Launch Connect
        this.smartcar.openDialog({forcePrompt: true});
    }

    render() {
        // TODO: Authorization Step 2b: Render the Connect component
        return <Connect onClick={this.authorize} />;
    }
    ```

# Handle the response

1.  Once a user has authorized the application to access their vehicle, the user is redirected to the `redirect_uri` with an
    authorization code as a query parameter and the pop-up dialog is closed. Using the JavaScript SDK, the frontend can
    receive this `code` in the `onComplete` callback passed into the `Smartcar` object.
    ```js App.jsx
    onComplete(err, code, status) {
        //TODO: Authorization Step 3: Receive the authorization code
        console.log(code);
        //prints out the authorization code
    };
    ```

# Launching Connect

Restart your server, open up your browser and go to [http://localhost:3000/login](http://localhost:3000/login). You should be reciderect to Smartcar Connect.

<Info>
  This tutorial configures Connect to launch in `test` mode by default.
  In `test` mode, any `username` and `password` is valid for each brand.
</Info>

Smartcar showcases all the permissions your application is asking for - `read_vehicle_info` in this case.
Once you have logged in and accepted the permissions, you should see your authorization `code` printed to your console.

# Getting your first access token

After receiving the authorization code, the React application must exchange it for an `ACCESS_TOKEN`. To do so, we can send
the code to the backend service which we will implement in a bit. Until then, let’s assume our backend service contains
an endpoint `/exchange` that receives an authorization code as a query parameter and exchanges it for an `ACCESS_TOKEN`.

We can add this logic in our `onComplete` callback

```js App.jsx
onComplete(err, code, status) {
  // TODO: Request Step 1: Obtain an access token
  return axios
    .get(`${process.env.REACT_APP_SERVER}/exchange?code=${code}`);
}

```

# Getting data from a vehicle

Once the back-end has the `ACCESS_TOKEN`, it can send requests to a vehicle using the Smartcar API. The React app will
have to send a request to the backend service which in turn sends a request to Smartcar. We have to do this because
our frontend does not have the `ACCESS_TOKEN`.

Assuming our backend has a `/vehicle` endpoint that returns the information of a user’s vehicle, we can make this query in
our `completion callback` and and set the state of the React app with the returned vehicle attributes.

```js App.jsx
onComplete(err, code, status) {
  // TODO: Request Step 2a: Get vehicle information
  return axios
    .get(`${process.env.REACT_APP_SERVER}/exchange?code=${code}`)
    .then(_ => {
      return axios.get(`${process.env.REACT_APP_SERVER}/vehicle`);
    })
    .then(res => {
      this.setState({vehicle: res.data});
    });
}

```

Now that we have the vehicle attributes, we can render a simple Vehicle component that shows the vehicle attributes in a table.

```js App.jsx
render() {
  // TODO: Request Step 2b: Get vehicle information
  return Object.keys(this.state.vehicle).length !== 0 ? (
    <Vehicle info={this.state.vehicle} />
  ) : (
    <Connect onClick={this.authorize} />
  );
}
```

# Setting up your backend

Now that our frontend is complete, we will need to create a backend service that contains the logic for the `/exchange` and `/vehicle` endpoints.
You can use any of our backend SDKs below to set up the service starting from the **Obtaining an access token** step.

<Note>
  When setting up the environment variables for your  backend SDK, make sure to set `REDIRECT_URI` to the custom scheme
  used for this tutorial i.e. `https://javascript-sdk.smartcar.com/v2/redirect?app_origin=http://localhost:3000`.
</Note>

<CardGroup cols={4}>
  <Card title="Java" icon="java" href="/tutorials/backend#getting-your-first-access-token" icontype="duotone" />

  <Card title="Node.js" href="/tutorials/backend#getting-your-first-access-token" icon="node-js" icontype="duotone" />

  <Card title="Python" icon="python" href="/tutorials/backend#getting-your-first-access-token" icontype="duotone" />

  <Card title="Ruby" href="/tutorials/backend#getting-your-first-access-token" icon="gem" icontype="duotone" />
</CardGroup>


# Dynamic Webhooks (Early Access)

Dynamic webhooks make it incredibly easy to receive data from a vehicle at the optimal frequency supported by the OEM. Specifically, once a certain condition is met, you will be able to receive data more frequently from the vehicle to stay up-to-date with the state of the vehicle when it matters most to you.

## Prerequisites

For this tutorial it is recommended to have the following in place:

*   To receive webhooks you’ll need to set up a callback URI on your server.
*   To [**subscribe**](https://smartcar.com/docs/api-reference/webhooks/subscribe-webhook) a vehicle you’ll want to have [**Connect**](https://smartcar.com/docs/connect/dashboard-config) integrated into your application.

## Setting up a Dynamic Webhook

Navigate to **Webhooks** from the Smartcar Dashboard, select **+ Add webhook** and select **Dynamic** from the Webhooks config wizard.

<Frame>
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/tutorials/dynamic-webhooks/add-webhook.png" />
</Frame>

Name your webhook and specify a `callback URI`. Your `callback URI` is where Smartcar will send payloads from vehicles connected to your webhook. Click **Next**.

<Frame>
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/tutorials/dynamic-webhooks/name-webhook.png" />
</Frame>

Confirm everything looks good and hit **Add**.

<Frame>
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/tutorials/dynamic-webhooks/confirm-webhook.png" />
</Frame>

<br />

<Info>
  Currently Dynamic Webhooks only support returning data from the
  [location](/api-reference/get-location),
  [charge](/api-reference/evs/get-charge-status), and
  [battery](/api-reference/evs/get-battery-level) endpoints. Changes in data frequency
  are only supported based on the plugged in state for EVs.
</Info>

After adding your webhook, you’ll need to verify your callback URI. This is to ensure Smartcar is sending data to the correct place!

<Frame>
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/tutorials/dynamic-webhooks/verify-webhook.png" />
</Frame>

Please see our API reference on how to [verify a webhook](/api-reference/webhooks/callback-verification), or **Part II** on [this blog post](https://smartcar.com/blog/how-to-use-scheduled-webhooks#-part-ii-verify-webhook) for a more in depth guide.

## Subscribing vehicles to a webhook

Now you’ve got your webhook set up, you can subscribe vehicles to start getting data. If you haven’t done so already, please set up [Connect](http://localhost:3000/connect/dashboard-config) for your application.

After going through Connect and receiving your initial `access_token`, you’ll first want to hit the [All Vehicles](/api-reference/all-vehicles) endpoint to fetch the Smartcar `vehicle_ids` of the authorized vehicles.

<CodeGroup>
  <Snippet file="api-reference/core-sdk-methods/all-vehicles.mdx" />
</CodeGroup>

<br />

With your `access_token` and `webhook_id` you can hit the [Subscribe](/api-reference/webhooks/subscribe-webhook) endpoint for each `vehicle_id` to start receiving data.

<CodeGroup>
  <Snippet file="api-reference/core-sdk-methods/subscribe-webhook.mdx" />
</CodeGroup>

<br />

## Example payload

```json dynamicWebhook.json
{
  "version": "2.0",
  "webhookId": "865ca68d-a9b6-4d74-856e-605db0209eca",
  "eventName": "dynamic",
  "mode": "live",
  "payload": {
    "vehicles": [
      {
        "vehicleId": "00000000-0000-4000-A000-000000000000",
        "requestId": "25d743b8-14cf-4744-b067-bd8d7daf3f1a",
        "data": [
          {
            "path": "/battery",
            "code": 200,
            "body": {
              "range": 283.244544,
              "percentRemaining": 0.58
            },
            "headers": {
              "sc-data-age": "2024-09-20T21:58:06.000Z"
            }
          },
          {
            "path": "/charge",
            "code": 200,
            "body": {
              "isPluggedIn": false,
              "state": "NOT_CHARGING"
            },
            "headers": {
              "sc-data-age": "2024-09-20T21:58:06.000Z"
            }
          },
          {
            "path": "/location",
            "code": 200,
            "body": {
              "latitude": 37.4292,
              "longitude": 122.1381,
            },
            "headers": {
              "sc-data-age": "2024-09-20T21:58:48.000Z"
            }
          }
        ]
      }
    ]
  }
}
```

## FAQs

<AccordionGroup>
  <Accordion title="How often will I get data?">
    By default Smartcar will deliver data every hour from the time a vehicle is subscribed. From that point on, once we detect the relevant state changes we'll increase this to every 30 minutes, dropping back down to hourly once the state returns to what it was.

    Where more frequent data delivery is supported by an OEM, Smartcar will deliver data at those speeds. Please reach out to your Solutions Architect for more information.
  </Accordion>

  <Accordion title="Can I use the same callback URI for all my webhooks?">
    Yes! You can distinguish between webhook types based on the `eventName` field. Dynamic Webhooks will have `eventName` set to `dynamic`.
  </Accordion>

  <Accordion title="What happens if my webhook destination goes down temporarily?">
    Smartcar will attempt to resend payloads with an exponential backoff. Once your server is back online you'll continue to receive data from the vehicles.
  </Accordion>

  <Accordion title="I've stopped receiving events">
    *   Once a webhook is configured and a vehicle is subscrbied, we’ll begin sending data to your Callback URI.
        We’ll expect a 2xx response to each. In the event that we don’t receive a 2xx response, we’ll retry 6 times with exponential backoff.
        **If we continue not to receive a successful response, we’ll automatically disable your webhook.**
    *   If you haven't made any major changes to your callback URI, commonly our request payload may have hit the request size limit for you server.
  </Accordion>

  <Accordion title="What happens if a vehicle encounters an error? Will you retry?">
    Smartcar will attempt to get data from the vehicle with retries. However if we are unable to we'll return the relevant error response in the payload for that vehicle.

    For example, if a vehicle owner changes the credentials to their connected services account we'll return a [CONNECT\_SERVICES\_ACCOUNT:AUTHENTICATION\_FAILED](/errors/api-errors/connected-services-account-errors#authentication-failed) error prompting you to have the vehicle owner go through Connect again to reauthenticate their vehicle.
  </Accordion>

  <Accordion title="How do I unsubscribe a vehicle from a webhook?">
    To unsubscribe a vehicle you can hit the [unsubscribe](/api-reference/webhooks/unsubscribe-webhook) endpoint or [disconnect](/api-reference/management/delete-vehicle-connections) the vehicle from your application.
  </Accordion>
</AccordionGroup>


# Scheduled Webhooks

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.

This tutorial is split into four steps:

1.  Creating your webhook
2.  Verifying your callback URI
3.  Confirmation with a test payload
4.  Subscribing your first vehicle

# Prerequisites

For this tutorial it is recommended to have the following in place:

*   To receive webhooks you'll need to set up a callback URI on your server.
*   To [subscribe](/api-reference/webhooks/subscribe-webhook) a vehicle you'll want to have [Connect](/connect/dashboard-config) set up.

# Creating your first webhook

1.  Navigate to the **Webhooks** section of Dashboard and hit **+ Add Webhook**.
2.  Next, name your webhook, enter in your callback URI, and select **Scheduled** as the type.
    <Frame>
      <img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/webhooks-create-scheduled.png" />
    </Frame>
3.  After selecting the type, you'll need to:
    *   set how often you want receive data
    *   select which endpoints you want to receive data from
    *   select the units you want to receive data
    <Frame>
      <img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/webhooks-scheduled-settings.png" />
    </Frame>
4.  Once you're happy with the configuration, hit **Add Webhook** and move on to verifying your callback URI.

# Verifying your callback URI

After adding your webhook, you'll be prompted to verify it. After hitting **Verify this webhook** Smartcar will post a challenge request
to your callback URI to ensure we're sending payloads to the correct place.

<Frame>
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/webhooks-scheduled-verify.png" />
</Frame>

This is a **one time** event and will be in the following format where the `eventName` will be `verify`

```json verificationRequest.body
    {
        "version": "2.0",
        "webhookId": "<uuid>",
        "eventName": "verify",
        "payload": { "challenge": "<random-string>" }
    }
```

Upon receiving the request, your server will need respond to the challenge by hashing `payload.challenge` with your `APPLICATION_MANAGEMENT_TOKEN` to create a `SHA-256` based `HMAC`.

<Info>
  You can find your `APPLICATION_MANAGEMENT_TOKEN` in the Configuration section of Dashboard for your application.
</Info>

Return the hex-encoded hash as the value for `challenge` in your response body with a `2XX status code`.

```json verificationResponse.body
{
    "status" : 204,
    "headers" : {
        "Content-Type": "application/json"
    },
    "body" : {
        "challenge" : "{HMAC}"
    }
}
```

See the [callback verification](/api-reference/webhooks/callback-verification) section on our API Reference for more information.

# Confirmation with a test payload

Once verified you can send a test payload to your callback URI. Payloads from vehicles will have `eventName` set to `scheduled`.

<Note>
  The `mode` field will reflect the type of vehicle you've subscribed - either `live`, `test` or `simulated`.
</Note>

<CodeGroup>
  ```json Test Request Body
  {
    "version": "2.0",
    "webhookId": "6f9c7e43-2278-4a9b-b273-cdacab9ed83c",
    "eventName": "scheduled",
    "mode": "test",
    "payload": {
      "vehicles": [
        {
          "vehicleId": "1a9fdd59-b65e-4bf1-8264-5448812eac83",
          "requestId": "6c22cd5c-34df-48ae-ad90-b324170629be",
          "data": [
            {
              "path": "/",
              "code": 200,
              "body": {
                "id": "1a9fdd59-b65e-4bf1-8264-5448812eac83",
                "make": "BMW",
                "model": "i3 94 (+ REX)",
                "year": 2017
              },
              "headers": {}
            },
            {
              "path": "/fuel",
              "code": 200,
              "body": {
                "range": 44.12,
                "percentRemaining": 0.57,
                "amountRemaining": 1.32
              },
              "headers": {
                "sc-data-age": "2020-05-11T23:44:31.000Z",
                "sc-unit-system": "imperial"
              }
            },
            {
              "path": "/vin",
              "code": 200,
              "body": {
                "vin": "WBY1Z8C54HV550878"
              },
              "headers": {}
            }
          ],
          "timestamp": "2020-05-13T22:00:01.288Z"
        }
      ]
    }
  }
  ```

  ```json Test Request Headers
  {
  	"sc-signature": "61e60e2e149ccc0c63680ca3a9df09e071ea450dffc1f0e844f962f9df019b44",
  	"content-type": "application/json",
  	"user-agent": "Smartcar-Webhooks/2.0",
  }
  ```
</CodeGroup>

<br />

# Subscribing your first vehicle

Now you've got your webhook set up, you can subscribe vehicles to start getting data at your desired frequency.
If you haven't done so already, please set up the [Connect](connect/dashboard-config) for your application.

After receiving your initial `ACCESS_TOKEN` from the [auth code exchange](connect/auth-code-exchange) step for Connect,
you'll first want to hit the [All Vehicles](/api-reference/management/all-vehicles) endpoint to fetch the Smartcar
`vehicle_id`s of the authorized vehicles.

<CodeGroup>
  <Snippet file="api-reference/core-sdk-methods/all-vehicles.mdx" />
</CodeGroup>

<br />

With your `ACCESS_TOKEN` and `WEBHOOK_ID` you can hit the [Subscribe](/api-reference/webhooks/subscribe-webhook)
endpoint for each `vehicle_id` to start receiving data.

<CodeGroup>
  <Snippet file="api-reference/core-sdk-methods/subscribe-webhook.mdx" />
</CodeGroup>

<br />

# FAQs

<AccordionGroup>
  <Accordion title="When will I receive my first scheduled webhook?">
    Data will post to the endpoint depending on your selected cadence. For example:

    *   if a car is subscribed to an hourly interval webhook at 15:45 UTC, you'll get start to get data after 16:00UTC.
    *   if a car is subscribed to a monthly interval, we'll process the webhooks at 00:00UTC for the selected day.
  </Accordion>

  <Accordion title="Can I use an Event Based webhook to receive scheduled webhooks?">
    No, you'll need to set up a webhook for each webhook type.
  </Accordion>

  <Accordion title="Can I use the same callback URI for my webhooks?">
    Yes! You can distinguish between webhook types based on the `eventName` field - `scheduled` or `eventBased`.
  </Accordion>

  <Accordion title="I've stopped receiving events">
    *   Once a webhook is configured, we’ll begin sending events to your Callback URI on the cadence that you’ve chosen.
        We’ll expect a 2xx response to each. In the event that we don’t receive a 2xx response, we’ll retry 5 times over the next 10 minutes.
        **If we continue not to receive a successful response, we’ll automatically disable your webhook.**
    *   Check that your server didn't experience down time for more than 10 minutes recently resulting in 2XX responses not being sent back to Smartcar.
    *   If you haven't made any major changes to your callback URI, commonly our request payload may have hit the request size limit for you server.
  </Accordion>

  <Accordion title="Will I always receive payloads in line with my configured cadence?">
    While we aim for 1 to 5 minutes after your selected cadence, the delivery time largely depends on the number of vehicles you have subscribed as
    well as the average OEM latency. Smartcar will try to fulfill requests for your webhook within 15 minutes of the scheduled time. If we were unable
    to fulfill a request during that time, we'll try again over the course of subsequent 15 minute intervals and post them to your webhook.
  </Accordion>
</AccordionGroup>


# Testing with Postman

In this guide we'll go over how to use Vehicle Simulator to test out Smartcar using Postman.

## What is Postman?

Postman is a collaboration platform for API development. Postman's features simplify each step of building an API and streamline collaboration so you can create better APIs - faster.
You’ll need a few things to start making API calls with Smartcar and Postman:

*   [A Postman Account](https://identity.getpostman.com/signup?continue=https%3A%2F%2Fgo.postman.co%2Fbuild)
*   [Smartcar’s Postman Collection](https://www.postman.com/smartcar/workspace/smartcar-api/collection/13172949-37efba9a-c68c-4f45-b123-af9154d7a0a6?action=share\&creator=9829117)
*   [A Smartcar Developer Account](https://dashboard.smartcar.com/signup)

## Configuring the Connect flow in Postman

1.  Install the latest [Postman app](https://www.postman.com/downloads/) and log in
2.  Import the [Smartcar collection](https://www.postman.com/smartcar/workspace/smartcar-api/collection/13172949-37efba9a-c68c-4f45-b123-af9154d7a0a6?action=share\&creator=9829117) into your local Postman workspace. Hit Import.
3.  Click Link, paste in [the link](https://www.postman.com/smartcar/workspace/smartcar-api/collection/13172949-37efba9a-c68c-4f45-b123-af9154d7a0a6?action=share\&creator=9829117) to the collection and hit Continue.
4.  On the next screen, hit Import.

<Tabs>
  <Tab title="Step 1">
    <img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/help-center/guide-postman/postman.png" />
  </Tab>

  <Tab title="Step 2">
    <img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/help-center/guide-postman/import1.png" />
  </Tab>

  <Tab title="Step 3">
    <img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/help-center/guide-postman/import2.png" />
  </Tab>

  <Tab title="Step 4">
    <img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/help-center/guide-postman/import3.png" />
  </Tab>
</Tabs>

## Smartcar Application Configuration

If you haven’t already signed up for a Smartcar Developer account, you can do so from this [**signup link**](https://dashboard.smartcar.com/signup).

*   Grab your **Client ID** and **Client Secret** from the Configuration page after you sign in, and copy them to someplace secure. You’ll need those tokens a little later in this setup.
*   Under the Credentials tab for your application, you’ll need to add the following Redirect URIs. This will ensure that Smartcar Connect exits successfully with both Postman’s Native and Web clients.

```
https://oauth.pstmn.io/v1/browser-callback 
http://localhost:8000/exchange
```

<Frame type="simple">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/help-center/guide-postman/appConfig.png" />
</Frame>

Through the Connect flow, you’re able to get consent from vehicle owners to connect their vehicle to your application. Postman provides an easy way to manage oAuth 2.0 flows under the Authorization tab of a Collection. Set up the Configuration Options for either a live or simulated vehicle.

<Frame type="simple">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/help-center/guide-postman/authorization.png" />
</Frame>

**Live Vehicle**

| Parameter        | Description                                                                                                       |
| ---------------- | ----------------------------------------------------------------------------------------------------------------- |
| Auth URL         | `https://connect.smartcar.com/oauth/authorize?approval_prompt=force`                                              |
| Access Token URL | `https://auth.smartcar.com/oauth/token`                                                                           |
| Client ID        | `client_id` from your Dashboard                                                                                   |
| Client Secret    | `client_secret` from your Dashboard                                                                               |
| Scope            | A space-separated list of [permissions](/api-reference/permissions) that your application is requesting access to |

**Simulated Vehicle**

| Parameter        | Description                                                                                                       |
| ---------------- | ----------------------------------------------------------------------------------------------------------------- |
| Auth URL         | `https://connect.smartcar.com/oauth/authorize?approval_prompt=force&mode=simulated`                               |
| Access Token URL | `https://auth.smartcar.com/oauth/token`                                                                           |
| Client ID        | `client_id` from your Dashboard                                                                                   |
| Client Secret    | `client_secret` from your Dashboard                                                                               |
| Scope            | A space-separated list of [permissions](/api-reference/permissions) that your application is requesting access to |

## Setting up a Simulated Vehicle

Under the Simulator tab on Dashboard, hit Add Vehicle. Note that you may already have a pre-created simulated vehicle available, if so skip to **Connecting to a vehicle** below.

<Frame type="simple">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/help-center/guide-postman/sim1.png" />
</Frame>

Select a region and MMY for your vehicle, then hit Search by MMY

<Frame type="simple">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/help-center/guide-postman/sim2.png" />
</Frame>

After selecting Use Vehicle, you’ll want to select a state for the vehicle. After that, you’ll get a set of credentials to use in the Connect flow.

<Frame type="simple">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/help-center/guide-postman/sim3.png" />
</Frame>

<Frame type="simple">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/help-center/guide-postman/sim4.png" />
</Frame>

Before proceeding to the next step, you’ll want to start the simulation in the Smartcar Dashboard.

<Frame type="simple">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/help-center/guide-postman/sim5.png" />
</Frame>

## Connecting to a vehicle

If configured correctly, when you click **Get New Access Token** in Postman, you should see the first screen of the Connect flow.

<Tip>
  Before hitting Continue, make sure to select a country from the dropdown appropriate to the region you selected for your simulated vehicle.
</Tip>

<Frame type="simple">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/help-center/guide-postman/connect1.png" />
</Frame>

Continue through the Connect flow, select the brand of your simulated vehicle and enter in the credentials you were issued for your simulated vehicle.
After accepting the permissions you’ll be met with the following screen:

<Frame type="simple">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/help-center/guide-postman/connect2.png" />
</Frame>

Hit Use Token. You should see Access Token under Current Token populate with the access\_token from the popup. Using this access\_token you can make API
requests to Smartcar's API.

<Frame type="simple">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/help-center/guide-postman/connect3.png" />
</Frame>

<br />

<Warning>
  Access tokens are only valid for two hours. If you want to make API requests after it has expired, you'll need to generate a
  new one by stepping through the Connect Flow again, or through a [token refresh](/api-reference/authorization/token-refresh).
</Warning>

## Making an API request

<Tip>
  Thanks to Postman, requests in the collection will inherit the `access_token` from the OAuth 2.0 Authorization flow we went through in the steps above.
</Tip>

In order to make API requests, we’ll need to first get a Smartcar `vehicle Id`. A `vehicle Id` is a unique identifier for a vehicle on Smartcar’s platform.

This can be done with the `All Vehicles` request. Making this request will assign the `vehicle Id` to the `{{vehicle_id}}` variable for other requests in the Collection.

<Frame type="simple">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/help-center/guide-postman/req1.png" />
</Frame>

<br />

Now that you've got a vehicle Id, you can make a request to other endpoints. Hitting Vehicle Info, we can see the MMY of the vehicle.

<Frame type="simple">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/help-center/guide-postman/req2.png" />
</Frame>

<br />

Checking `EV Battery Level`, we can see the response matches the vehicle state on the simulator

<Frame type="simple">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/help-center/guide-postman/req3.png" />
</Frame>

<br />

<Frame type="simple">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/help-center/guide-postman/req4.png" />
</Frame>

<br />

## Troubleshooting

<AccordionGroup>
  <Accordion title="I’m getting an Invalid Credentials error in the Connect flow">
    *   Check that you’re launching Connect in simulated mode
    *   If you’re still running in to an error make sure you’ve selected a country that matches the region you selected for your simulated vehicle.
  </Accordion>

  <Accordion title="I’m getting a 403 - Permission error on API requests">
    *   Check that the vehicle you’ve created supports the endpoint. Select View Estimated Latencies to see a list of endpoints supported for the vehicle.
    *   If you’re still running into the error, check that you’ve requested the appropriate permission in the scope parameter of the Connect URL.

    <Tip>
      You can always check the `/permissions` endpoint to see what endpoints you have access to.
    </Tip>
  </Accordion>
</AccordionGroup>


# Smartcar Usage Limits

Learn about limits you may encounter when using Smartcar.

## Overview

There are several types of limits that govern your use of Smartcar. The nature of telematics requires us to carefully manage vehicle connections and traffic to ensure the stability of our platform and those of our upstream providers.

There are two major types of limits - **Billing Limits** and **Operational Rate Limits**.

# Billing Limits

### [BILLING : VEHICLE\_REQUEST\_LIMIT](/errors/api-errors/billing-errors#vehicle-request-limit)

Your Smartcar plan specifies a maximum number of API calls you are permitted to make to each single vehicle in a given month. If you exceed this limit, you will receive the `VEHICLE_REQUEST_LIMIT` error.

For example: you have been allocated 500 API calls per vehicle per month, but you made the 501<sup>st</sup> call to a single vehicle during the billing period.

**This limit can be changed.** If you require more calls per vehicle per month, contact [support@smartcar.com](mailto:support@smartcar.com) or your Account Manager and we can work with you to understand your options.

### [BILLING : VEHICLE\_LIMIT](/errors/api-errors/billing-errors#vehicle-request-limit)

Your Smartcar plan specifies a maximum number of vehicles that you may have connected at any one time. This limit applies to vehicle connections, and is separate from the limit regarding the number of API calls to those vehicles. If you receive this error, you have exceeded your maximum number of connected vehicles.

**This limit can be changed.** Reach out to [support@smartcar.com](mailto:support@smartcar.com) or your Account Manager to discuss your options.

# Operational Rate Limits

### [RATE\_LIMIT : SMARTCAR\_API](/errors/api-errors/rate-limit-errors#smartcar-api)

Smartcar limits the total number of requests a single application can make over a given period of time to ensure platform stability for all customers. The Smartcar API Limit is defined as a "bucket" of requests that refills at a constant rate over time.

The default Smartcar API Limit is a **bucket of 120 requests that refills at a rate of 2 requests per minute.**

If you receive a `RATE_LIMIT:SMARTCAR_API` response, your application has exceeded this limit. You should implement an exponential backoff strategy when retrying requests.

**This limit can be changed.** Reach out to [support@smartcar.com](mailto:support@smartcar.com) or your Account Manager to discuss your options.

### [RATE\_LIMIT : VEHICLE](/errors/api-errors/rate-limit-errors#vehicle)

Sending telematics requests to a vehicle causes it to wake up from its sleep state and consume energy and data resources. Excessive requests to a single vehicle can result in:

*   EV battery drain
*   12 volt battery drain
*   `UPSTREAM:RATE_LIMIT` errors that prevent you from making requests for a longer period of time

Smartcar enforces a per-vehicle rate limit that governs the rate of requests to a single vehicle and mitigates these potential issues. These limits can differ based on the vehicle manufacturer and a number of other factors, and are set by Smartcar to ensure consistent and timely data can be retrieved from vehicles.

**This limit cannot be changed.** If you receive this response, refer to the `retry-after` header (returned as seconds) for when to retry the request.

### [UPSTREAM : RATE\_LIMIT](/errors/api-errors/upstream-errors#rate-limit)

Vehicle manufacturers sometimes impose rate limits on requests to vehicles. The Smartcar Vehicle Rate Limit will generally prevent those limits from being reached, but outside requests from other providers may cause the upstream limit to be exceeded. If the OEM upstream rate limit is exceeded, you will receive `UPSTREAM:RATE_LIMIT` from the Smartcar API for the affected vehicle until the limit is reset.

**This limit cannot be changed.** Smartcar cannot control rate limits imposed by our upstream providers. If you consistently receive this response for a single vehicle, reach out to [support@smartcar.com](mailto:support@smartcar.com) and we can investigate.


# Brand Quirks

Brand specific quirks to keep in mind while building out your application.

## Acura

### Ignition On

Depending on model year, certain Acura vehicles do not return data when the ignition/engine is on.

### Sleep State

Most Acuras will go into a sleep state after about a week of inactivity,

## Audi

### Primary Key User

In order to have access to all vehicle functionality the account that connects to Smartcar will need to be flagged as a Key User by Audi.

## BMW/MINI

### CONNECTED\_SERVICES\_ACCOUNT - SUBSCRIPTION errors

Smartcar API will throw a CONNECTED\_SERVICES\_ACCOUNT - SUBSCRIPTION when the data we receive from the vehicle is older than a month as this normally indicates a subscription issue.

## Ford/Lincoln

### Authentication

Ford requires the use of an SDK to authenticate vehicles. Smartcar's Connect SDKs will redirect to Ford’s site to handle the authentication process when the user logs in. Web consent flows are not possible at this time. See [Connect SDKs](/docs/connect/connect-sdks) for our latest SDKs.

## GM (Buick, Chevrolet, Cadillac, GMC)

### VEHICLE\_STATE - ASLEEP errors

After 3-4 days of no activity, GM vehicles will enter a deep sleep state at which point they will no longer respond to API requests to preserve their 12v battery. In order to get data from the vehicle again, the car will need to go through an ignition cycle.

### UPSTREAM - RATE\_LIMIT errors

In order to avoid hitting UPSTREAM - RATE\_LIMIT errors use batch requests and ping no more than once every 30 minutes. Use of the OEM app also counts towards the rate limit.

## Hyundai/Kia

### Lock/Unlock Support for Hyundai US vehicles.

Hyundai has limitations in place that limit how many lock/unlock requests can be made in a given period. As a result, we want to avoid the case where a user accidentally makes too many lock/unlock requests, potentially blocking them from using an app until Hyundai’s rate limit for the vehicle has reset.

### Polling Limitations

Hyundai/Kia vehicles have a limitation where only 20 requests can be made in a 24 hour period. Smartcar allows one requests every 72 minutes to go to the vehicle directly. All other requests will be sent to the OEM's cloud which may be updated after events such as:

*   Every 10% of SoC while charging
*   5 minutes after ignition off
*   Vehicle doors are left unlocked for 5 minutes
*   After a command successfully completes
*   Whenever charging stops

## Nissan

### “Vehicle has been found” MyNISSAN notifications

Vehicle owners may receive a notification from the MyNISSAN app stating “Success! We found the location of your vehicle. Check the map for the location of your YYYY Model.” every time the location endpoint is hit.

The app appears to have an option to edit notifications, but as of Feb 2024 they are not available in the app. Notifications may need to be turned off at the iOS/Android level by the vehicle owner.

## PSA Group (Citroen, DS, Opel, Peugeot, Vauxhall)

### Requesting control\_charge permissions

If you request control\_charge permissions for PSA EVs, upon login owners will be presented with a PIN and MFA screen in Connect upon submitting their credentials. They will need to have set this up on their OEMs application in order to grant your application this permission.

## Rivian

### MFA

If MFA is enabled the vehicle owner will need to re-authorize via Connect about every 2 weeks.

## Tesla

### Remote Access

It may take a few hours or up to a full day for the REMOTE\_ACCESS\_DISABLED errors to subside after remote access is enabled.

### Charge Billing Records

In order to retrieve charge billing records, the main Tesla account must connect the vehicle, as driver profiles do not have access to this data.

### Virtual Key

Tesla now requires virtual keys for 3rd-party applications in order to issue commands for the following models:

*   All Cybertrucks, Model 3 and Model Y
*   2021+ Model S and X

## Toyota/Lexus

### Prius Prime - Location

Due to very low reliability/accuracy of the location endpoint for Prius Primes, we currently do not support that endpoint for the Prius Prime vehicles specifically. The regular Prius vehicle **do** support location.

## Volkswagen

### Control charge limits

Volkswagen only allows 15 charge commands (start/stop charge) before the vehicle needs to be driven again in order to start responding to start/stop requests.

### CONNECTED\_SERVICES\_ACCOUNT errors on lock/unlock commands

In addition to verifying the VW account with the activation code, some cars will need to undergo the VW Ident Process before you can access remote lock/unlock functionality. This involves contacting the dealership to verify your ownership of the vehicle.

### Missing Subscription (European VWs)

Upon purchasing (or activating the free trial), VW needs to review the request. You will get an email confirmation once they've cleared everything on their side.

### Primary Driver Status

In order to fully interact with Smartcar, the credentials need to be flagged as the primary driver. You'll need to tap the "become primary driver" flow in the VW app. Depending on the model, this may require you to be in the car to interact with the infotainment system.

## Volvo

### Lock/unlock commands

Volvo is an outlier regarding how unlock requests are processed. After initiating the request, after about 10 seconds you'll need to open the trunk (boot) to successfully complete the request. You'll know the car is ready to unlock the trunk as the hazard lights will flash. We recommend adding a notification for Volvos as part of the request loading animation to inform the user of this process.

### Phone number username

Smartcar Connect currently checks for an email format, as such phone number usernames cannot be used. The owner will need to add their email to their Volvo account via the web portal.

### Compatibility

Some models are not compatible because the device needs to be physically in the vehicle during authentication, which Connect doesn’t support at the moment:

*   2021+: XC40 Recharge
*   2022+: S90, S90 Recharge, V90, V90 Recharge, V90 Cross Country, XC60, XC60 Recharge, C40 Recharge
*   2023+: All models with the exception of the XC40

Even if the vehicle has been connected to and shows up in the Volvo app, if they go through Connect the account will present as if there are no vehicles on the account.


# Brand Subscription Information

Below you can find the connected service name for each brand as well as any specific subscription packages needed to connect to the vehicle via Smartcar.

| Make       | Region                      | Connected Service                           | Package                                           | Subscription Cost                                                                                             |
| ---------- | --------------------------- | ------------------------------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| Acura      | US, Canada                  | ACURALINK                                   | Remote                                            | 3 year free trial (2023 and Newer Models), 6 month free trial (2022 and Older Models). \$110/year thereafter. |
| Alfa Romeo | US, Europe                  | My Alfa Connect                             | My Car and My Remote                              | 3 - 5 years included.                                                                                         |
| Audi       | US                          | myAudi                                      | CARE                                              | -                                                                                                             |
|            | Europe, Canada              | Audi Connect                                | Remote                                            | Free for three years after delivery of a new vehicle. \~£120/year thereafter.                                 |
| BMW        | All                         | BMW Connected                               | -                                                 | Free trial varies with model year. \~\$120/year thereafter.                                                   |
| Buick      | US, Canada                  | OnStar                                      | Remote Access                                     | Free trial varies with model year. \$14.99/month for standalone Remote Access package.                        |
| Cadillac   | US, Canada                  | OnStar                                      | Remote Access                                     | Free trial varies with model year. \$14.99/month for standalone Remote Access package.                        |
| Chevrolet  | US, Canada                  | OnStar                                      | Remote Access                                     | Free trial varies with model year. \$14.99/month for standalone Remote Access package.                        |
| Chrysler   | US, Canada                  | Uconnect                                    | Sirius XM Guardian (Remote Package)               | 1 year free trial. \$12.99/month for the Remote Package thereafter.                                           |
| Citroën    | Europe                      | My Citroën                                  | ë-remote services needed for remote commands      | -                                                                                                             |
| CUPRA      | Europe                      | CUPRA CONNECT                               | Remote Access Services                            | 3 years free for the Born model, 1 year free for others. Price varies with region.                            |
| Dacia      | Europe                      | My Dacia                                    | -                                                 |                                                                                                               |
| Dodge      | US, Canada                  | Uconnect                                    | Sirius XM Guardian (Remote Package)               | 1 year free trial. \$12.99/month for the Remote Package thereafter.                                           |
| DS         | Europe                      | MyDS                                        | E-TENSE Remote                                    | -                                                                                                             |
| Fiat       | Europe                      | FIAT                                        | My Car and My Remote                              | 6 month free trial.                                                                                           |
|            | US                          | FIAT Connect                                | Assistance Package                                | 3 month free trial with select vehicles. \$14.99/month.                                                       |
| Ford       | All                         | FordPass                                    | -                                                 | -                                                                                                             |
| GMC        | US, Canada                  | OnStar                                      | Remote Access                                     | Free trial varies with model year. \$14.99/month for standalone Remote Access package.                        |
| Honda      | US                          | HondaLink                                   | EV Access for EV Data. Remote Access for Commands | EV Access 8 year trial. \$14.99/month for standalone Remote Access package.                                   |
| Hyundai    | All                         | Hyundai BlueLink                            | -                                                 | 3 year free trial for new vehicles. \$9.90/month per package thereafter.                                      |
|            | US                          | Hyundai BlueLink (2023 IONIQ 6 & all 2024+) | BlueLink+                                         | -                                                                                                             |
| Infiniti   | US                          | MyINFINITI                                  | -                                                 | 1 year free trial. \$12.99/month thereafter.                                                                  |
| Jaguar     | All                         | Jaguar InControl                            | -                                                 | 3 year free trial. \~\$100/year thereafter.                                                                   |
| Jeep       | US, Canada                  | Uconnect                                    | Sirius XM Guardian (Remote Package)               | 1 year free trial. \$12.99/month for the Remote Package thereafter.                                           |
|            | US, Canada                  | Jeep Connect                                | Sirius XM Guardian (Remote Package)               | 1 year free trial. \$12.99/month for the Remote Package thereafter.                                           |
| Kia        | US, Canada                  | Kia Access                                  | Plus                                              | 1 year free trial. \$149/year thereafter.                                                                     |
|            | Europe                      | Kia Connect                                 | -                                                 | 7 year free trial starting on sale to the first owner.                                                        |
| Land Rover | All                         | Land Rover InControl                        | -                                                 | 3 year free trial. \~\$100/year thereafter.                                                                   |
| Lexus      | US, Canada                  | Lexus Enform                                | REMOTE                                            | Free trial up to 3 years, varies with model year. \$80/year thereafter.                                       |
| Lincoln    | US                          | Lincoln Way                                 | -                                                 | -                                                                                                             |
| Mercedes   | All                         | MeConnect                                   | -                                                 | 1 year free trial. \~\$15/year there after.                                                                   |
| Mini       | All                         | Mini Connected                              | -                                                 | Free trial varies with model year. \~\$120/year thereafter.                                                   |
| Mazda      | US, Europe                  | MyMazda                                     | -                                                 | 3 year free trial. Pricing thereafter has not been established.                                               |
| Nissan     | US (non-Leaf)               | NissanConnect Services                      | Convenience                                       | 6 month free trial. \$8.00/month thereafter.                                                                  |
|            | US (Leaf)                   | NissanConnect EV Services                   | Convenience                                       | 6 month free trial. \$8.00/month thereafter.                                                                  |
|            | Europe                      | NissanConnect                               | -                                                 | Free trial varies with model year. \~£1.99/month thereafter.                                                  |
| Opel       | Europe                      | myOpel                                      | e-Remote services needed for remote commands      | -                                                                                                             |
| Peugeot    | Europe                      | MYPEUGEOT                                   | E-REMOTE CONTROL needed for remote commands       | -                                                                                                             |
| Porsche    | US, Europe                  | My Porsche                                  |                                                   | 1 year free trial after initial purchase. \$299/year there after.                                             |
| RAM        | US, Canada                  | Uconnect                                    | Sirius XM Guardian (Remote Package)               | 1 year free trial. \$12.99/month for the Remote Package thereafter.                                           |
|            | US, Canada                  | Ram Connect                                 | Sirius XM Guardian (Remote Package)               | 1 year free trial. \$12.99/month for the Remote Package thereafter.                                           |
| Renault    | Europe                      | My Renault                                  | -                                                 | -                                                                                                             |
| Rivian     | US                          | Rivian                                      | -                                                 | -                                                                                                             |
| Skoda      | Europe                      | MySKODA                                     | Care Connect                                      | \~£36/year.                                                                                                   |
| Subaru     | US                          | MySubaru                                    | STARLINK Security Plus                            | 6-month free trial. \$4.95/month thereafter.                                                                  |
| Tesla      | All                         | Tesla                                       | -                                                 | -                                                                                                             |
| Toyota     | US, Canada                  | Toyota Connected Services                   | Remote Connect                                    | 1 year free trial. \$80/year thereafter.                                                                      |
| Vauxhall   | Europe                      | myVauxhall                                  | e-Remote services needed for remote commands      | -                                                                                                             |
| Volvo      | All                         | Volvo Cars                                  | -                                                 | Free trial varies with model year. \~\$200/year thereafter.                                                   |
| Volkswagen | US                          | Car-Net                                     | Remote Access                                     | -                                                                                                             |
|            | Europe (non-ID) 2018 - 2022 | Car-Net                                     | -                                                 | -                                                                                                             |
|            | Europe (non-ID) ≤ 2023      | We Connect                                  | -                                                 | -                                                                                                             |
|            | Europe (non-ID) 2024+       | VW Connect                                  | -                                                 | -                                                                                                             |
|            | Europe (ID) Firmware \<3    | We Connect Start                            | -                                                 | -                                                                                                             |
|            | Europe (ID) Firmware v3+    | We Connect ID                               | -                                                 | -                                                                                                             |

## Notes

### Audi

*   Owners will need to ensure they're the Primary or Key user for the vehicle connected to their account in order to access all Smartcar functionality.

### Ford and Lincoln

*   Owners that use a username to login to their connected services app will need to migrate to using their email address under account settings in their Ford Pass or Lincoln Way portal.

### Onstar

*   Chevy Bolts MY 2020+ come with the **EV Mobile Command** service included for 5 years with the purchase of a new vehicle. Location data is not included in the package. Bolt owners will need to also subscribe to **Remote Access** to be able to get access to location data.
*   For all other OnStar accounts, we require the modern **Remote Access** plan as our base subscription. This plan comes with the **Vehicle Status** feature set, which is what enables our remote access to data from cars.
    More information can be found [in this PDF](https://my.chevrolet.com/content/dam/gmownercenter/gmna/dynamic/onstar/comparePlans/nbm/OC_Compare-Plans-Chevy.pdf).
*   There are certain legacy OnStar accounts floating around with similar names. A good check on whether a customer has the correct plan or not is the ability to view vehicle information like fuel level, EV battery level, odometer, or tire pressure from within their vehicle’s mobile app.

### Nissan US

*   Convenience features are included as part of the Premium package.

### Toyota

*   The Remote Connect subscription is tied to the audio package purchased with the vehicle. Compatible audio package availability is determined based on the trim of the vehicle model and varies model year to model year.
    Toyota provides PDFs for Remote Connect availability [here](https://www.toyota.com/connected-services/#:~:text=Learn%20about%20your%20Connected%20Services).

### Uconnect

*   For all Uconnect accounts, we require the ability to interact with vehicle information through the UConnect portal
*   A Uconnect account may have access to Mopar, but not all Mopar accounts have access to UConnect. If a user can see information in Mopar but not UConnect, they’ll need to reach out to UConnect support to set up the right UConnect plan for their vehicle.
*   2021+ Jeeps have their own connected service - Jeep Connect
*   2022+ Rams have their own connected service - Ram Connect
*   2022+ Jeep Wagoneers have their own connected service - Wagoneer Connect
*   Canada has limited support listed [here](https://www.driveuconnect.ca/en/sirius-xm-guardian-vehicles)

### Volkswagen ID Series

*   Model year 2021 and certain 2022 Volkswagen ID vehicles require an upgrade to vehicle software version 3 which will allow you to get location and odometer data. This is a requirement for both US and European vehicles.

### Volvo

The following models are not currently compatible with Smartcar:

*   2021+ : XC40 Recharge
*   2022+ : S90, S90 Recharge, V90, V90 Recharge, V90 Cross Country, XC60, XC60 Recharge
*   2023+ : All models with the exception of the XC40


# Compatible Vehicles





# Connect your car





# Diagnostic Systems

To support our System Status endpoint, reference the below list of unified systems.

The [System Status](https://smartcar.com/docs/api-reference/get-system-status) endpoint returns a list of systems reported by any given vehicle, as well as their current state which may be "OK" or "ALERT".

## System IDs

|                                   |                                                           |
| --------------------------------- | --------------------------------------------------------- |
| `SYSTEM_ABS`                      | Antilock Braking Systems                                  |
| `SYSTEM_ACTIVE SAFETY`            | Active Safety Systems                                     |
| `SYSTEM_AIRBAG`                   | Airbag Systems                                            |
| `SYSTEM_BRAKE_FLUID`              | Brake Fluid Level                                         |
| `SYSTEM_DRIVER_ASSISTANCE`        | Driver Assistance Systems                                 |
| `SYSTEM_EMISSIONS`                | Emissions Systems                                         |
| `SYSTEM_ABS`                      | Antilock Braking Systems                                  |
| `SYSTEM_ENGINE`                   | Engine Systems                                            |
| `SYSTEM_EV_BATTERY_CONDITIONING`  | EV Battery Conditioning Systems                           |
| `SYSTEM_EV_CHARGING`              | EV Charging Systems                                       |
| `SYSTEM_EV_DRIVE_UNIT`            | EV Drive Unit Systems                                     |
| `SYSTEM_EV_HV_BATTERY`            | EV High-Voltage Battery Systems                           |
| `SYSTEM_LIGHTING`                 | Lighting Systems                                          |
| `SYSTEM_MIL`                      | Malfunction Indiciator Lamp Systems (Check Engine Lights) |
| `SYSTEM_OIL_LIFE`                 | Oil Life Systems                                          |
| `SYSTEM_OIL_PRESSURE`             | Oil Pressure Systems                                      |
| `SYSTEM_OIL_TEMPERATURE`          | Oil Temperature Systems                                   |
| `SYSTEM_TELEMATICS`               | Telematics Systems                                        |
| `SYSTEM_TIRE_PRESSURE`            | Tire Pressure Systems                                     |
| `SYSTEM_TIRE_PRESSURE_MONITORING` | Tire Pressure MonitoringSystems                           |
| `SYSTEM_TRANSMISSION`             | Transmission Systems                                      |
| `SYSTEM_WASHER_FLUID`             | Washer Fluid Systems                                      |
| `SYSTEM_WATER_IN_FUEL`            | Water in Fuel Detection Systems                           |


# Early Access

Understand Smartcar's approach to Early Access features.

Early Access is a program that allows developers to test and integrate new Smartcar features before they are fully released. Early Access refers to a phase where certain features are made available for testing and feedback prior to general availability. These features are functional but may still be under development or refinement.

## Benefits of Early Access

Participating in Early Access allows developers to get a head start on integrating new features, a chance to influence the feature in development through feedback and help Smartcar ensure your app’s needs are met.

## Considerations for Early Access

When working with Early Access features, keep in mind that features may change before final release. As such, extra caution is advised when using these features in production environments.

## How to Participate

If you would like to get involved in testing an Early Access feature, contact your Account Manager or our [Support](support@smartcar.com) team for guidance.


# Frequently Asked Questions (FAQs)



Below you'll find answers to some of the most frequently asked questions about Smartcar.

<AccordionGroup>
  <Accordion title="Does Smartcar make apps?">
    Smartcar does not build applications ourselves. Rather, we provide the building blocks that our customers need in order to build applications for a variety of use cases.
  </Accordion>

  <Accordion title="Do I need a connected services account?">
    Yes. For instance, if you own a VW, you will need to have Car-Net activated in the US or WeConnect in Europe. You can read more about connected service subscriptions [here](/help/brand-subscriptions).
  </Accordion>

  <Accordion title="What countries does Smartcar work in?">
    Take a look at our [Global Compatibility page](https://smartcar.com/global/) for the latest information on where Smartcar works.

    Smartcar is always expanding and working hard to ensure supported countries are stable and reliable. If your country is not currently supported, but you think we'll be a good fit for your use case, [schedule a demo](https://smartcar.com/demo/) and let's see how we can help you!
  </Accordion>

  <Accordion title="Which languages does Smartcar support?">
    [Smartcar Connect](/connect/what-is-connect) is available in English, Danish, German, Spanish (Spain), Spanish (Latin America), French, Italian, Dutch, Norwegian, and Swedish providing vehicle owners a native experience as they onboard vehicles to your platform.
  </Accordion>

  <Accordion title="How fresh is my data?">
    Smartcar will always try to pull the latest data point from any given vehicle. Each API response includes an [sc-data-age header](https://smartcar.com/docs/api#response-headers) that will contain the timestamp of when that data was last saved.

    Although each OEM saves data at different times, the data age header should not be older than the last time the vehicle was used.
  </Accordion>

  <Accordion title="How many cars is Smartcar compatible with?">
    <Tip>
      For a list of compatible vehicles, visit [our website](https://smartcar.com/product/compatible-vehicles/).
    </Tip>

    Smartcar is compatible with **161 million vehicles** across the US, Canada and Europe.

    **United States** <br />
    Smartcar is compatible with **29 car brands** in the United States.

    **Europe** <br />
    Smartcar is compatible with **19 car brands** in Europe.

    **Canada** <br />
    Smartcar is compatible with **21 car brands** in Canada.
  </Accordion>

  <Accordion title="Why isn't my car supported?">
    **If your make isn't supported...**

    We work hard to ensure that supported brands are stable and reliable, which takes time. If you don't see your make on our [compatibility page](https://smartcar.com/product/compatible-vehicles/) but you would like it to be, reach out to [support@smartcar.com](mailto:support@smartcar.com) to see how you can help speed up the process!

    **If we support your make, but not your model...**

    We might just need to do some additional testing. Sign up to our [research fleet](https://smartcar.com/research-fleet) and we'll reach out to see what we can do for you!

    **If we support your make, model, but not your year...**

    The majority of automakers only started adding internet connectivity to their cars around 2014. If you're able to access your car through a smartphone application and believe it should be supported, reach out to us and we'll be happy to take a look.
  </Accordion>

  <Accordion title="Smartcar versus Aftermarket Hardware">
    While on-board diagnostics dongles are versatile and useful for tracking and diagnostics of many kinds, they are far from ideal when it comes to mileage verification.
    They can be inaccurate, inconvenient, expensive and unreliable.Smartcar is only one example of a pure software alternative that uses API technology to offer the perfect
    mileage verification solution to auto insurance companies. Compared with traditional OBD-II devices, our API is accurate, cost efficient and tamper-resistant.

    You can read more about why using our API is a great choice on our [blog](https://smartcar.com/blog/obd-mileage-verification/).
  </Accordion>

  <Accordion title="Why do I see requests that resulted in a 460 status code with different error codes and error types on the Smartcar Dashboard?">
    In the event that we recieve a response from the OEM after the connection is closed, we will show the error code and error type we would have responded with on the Dashboard if the connection had been kept open.
  </Accordion>
</AccordionGroup>


# Submit a Feature Request



<div class="asana-embed-container"><link rel="stylesheet" href="https://form.asana.com/static/asana-form-embed-style.css" /><iframe class="asana-embed-iframe" height="533" width="800" src="https://form.asana.com/?k=97Hkc15gNVv5js06cZTxTg&d=25776492380141&embed=true" /><div class="asana-embed-footer"><a rel="nofollow noopener" target="_blank" class="asana-embed-footer-link" href="https://asana.com/?utm_source=embedded_form"><span class="asana-embed-footer-text">Form powered by</span><div class="asana-embed-footer-logo" role="img" aria-label="Logo of Asana" /></a></div></div>


# Upgraded Tesla API Integration

This page has information regarding Smartcar's upgraded Tesla integration and what this means for developers. For an overview of the changes see [this page](https://smartcar.com/docs/help/oem-integrations/tesla/whats-new).

## What's changing for my integration?

Vehicle owners will now step through two new screens within Connect to authorize access to their Tesla account. Launching and exiting the Connect flow remains unchanged.

<Steps>
  <Step title="Launching Connect">
    <img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/help-center/oem-integrations/tesla/default-login/preamble.png" />
  </Step>

  <Step title="Authorize with Tesla">
    <Note>
      Currently Tesla **does not** check any permissions by default after a user signs in.
    </Note>

    <img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/help-center/oem-integrations/tesla/default-login/tesla-auth.png" />
  </Step>

  <Step title="Grant Screen">
    <img height="400" width="400" src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/help-center/oem-integrations/tesla/default-login/grant-screen.png" />
  </Step>
</Steps>

Prior to launching Connect, we strongly recommend prompting your users to **Select All** permissions on the Tesla grant screen for the smoothest experience. Smartcar will continue to gate access to your application with our permission model on the next screen. Failure to check the the correct combination of permissions will require user action to
[revoke access and re-authenticate](/help/oem-integrations/tesla/faqs#how-can-my-users-fix-their-permissions-with-tesla).

## Commands

In addition to permissions from their authorization flow, Tesla now **requires** virtual keys for 3rd-party applications
in order to issue commands for the following models:

*   All Cybertrucks, Model 3s and Ys
*   2021+ Model S and X

<Note>
  Each vehicle on a Tesla account will need to have a virtual key added individually.
</Note>

In order to do this, the vehicle owner needs to set up **Phone as a Key** prior to accepting a **Third-Party Virtual Key**.
Failure to have these complete will result in certain requests failing e.g. lock and unlock, or charge control requests come January 2024.

### Handling the new redirect parameter

After going through the new Connect flow, we'll send back a URL pointing to our Third-Party Virtual Key along with the `code`:

```http Success
HTTP/1.1 302 Found
Location: https://example.com/home?
code=90abecb6-e7ab-4b85-864a-e1c8bf67f2ad
&virtual_key_url=https://www.tesla.com/_ak/smartcar.com
```

<Info>
  This new param will **not** break existing HTTP client integrations or older SDK versions. Update to the latest version to receive the URL in the Connect `onComplete` for our Frontend SDKs.
</Info>

<Tabs>
  <Tab title="Android SDK">
    ```java
    handleResponse(SmartcarResponse smartcarResponse) {
        // handle code
        // retrieve virtualKeyUrl
        String virtualKeyUrl = smartcarResponse.getVirtualKeyUrl()
    } 
    ```
  </Tab>

  <Tab title="JavaScript SDK">
    ```swift
    onComplete: function(err, code, state, virtualKeyUrl) {
       // handle code
       // send virtualKeyUrl to backend, for example
       api.post('/backend-route', { virtualKeyUrl });
    }
    ```
  </Tab>

  <Tab title="🚨 iOS SDK - Breaking Change">
    The the completion handler signature is different with the **latest version**. In the `completionHandler`, the order of arguments is now `code: String?, state: String?, virtualKeyUrl: String?, err: AuthorizationError?`<br />

    ```swift
    func completionHandler(
            code: String?, state: String?, virtualKeyUrl: String?, 
            err: AuthorizationError?,) -> Void {
            ...
        }
    ```
  </Tab>

  <Tab title="Backend SDKs">
    No changes. Simply reference the new parameter from our `POST` back to your redirect URI - `virtual_key_url`
  </Tab>
</Tabs>

### Adding a Virtual Key

You will need to prompt your users to open the link. Depending on your user's device, they will need to do the following:

<Tip>
  Adding a Virtual Key will need to be done after a user has granted Smartcar access to their Tesla account in the Connect flow.

  Please see our [FAQs](/help/oem-integrations/tesla/faqs#can-owner-and-driver-accounts-authorize-access-with-smartcar-through-connect) for details on adding a virtual key for accounts with multiple vehicles and different account types.
</Tip>

<Tabs>
  <Tab title="Mobile Device">
    On mobile devices, they will be redirected to the Tesla app and prompted to add a Virtual Key

    <Frame type="simple" caption="Opening the link on a mobile device with the Tesla app installed">
      <img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/help-center/oem-integrations/tesla/add-virtual-key/mobile.png" />
    </Frame>
  </Tab>

  <Tab title="Desktop">
    On Desktop, they will be prompted to scan the QR code which in turn opens up the Tesla app and prompts them to add a Virtual Key

    <Frame type="simple" caption="Opening the link on a desktop">
      <img height="400" width="400" src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/help-center/oem-integrations/tesla/add-virtual-key/desktop.png" />
    </Frame>
  </Tab>
</Tabs>

## Virtual Keys for Smartcar Enterprise Customers

By default, Smartcar will host a Smartcar specific virtual key. This will prompt vehicle owners to approve Smartcar third party application access to their vehicle.

Smartcar's [Enterprise](https://smartcar.com/pricing) customers can use a virtual key specific to their branding. This allows your brand to request access to a vehicle owner's Tesla account instead of Smartcar by default. For example, the Tesla authorization screen would read:

```
    Allow {{YOUR_BRAND}} access to your Tesla Account?
```

In addition, this will prompt vehicle owners to approve a virtual key using their brand name in the following format:

```
    {{YOUR_BRAND}}.app.car
```

When adding the virtual key via the Tesla app, a vehicle owner will see the following message:

```
A virtual key for "{{YOUR_BRAND}}.app.car" will be paired with your Model 3
```

Please reach out to your Account Manager to get the process started.

## Updating Access with Tesla

You can use either of the following URLs to launch an [Update Access flow from step 3.](/help/oem-integrations/tesla/faqs#how-can-my-users-fix-their-permissions-with-tesla) in the event you need to get additional Tesla permissions from the vehicle owner due to:

*   A [PERMISSION](/errors/api-errors/permission-errors) error from API
*   A [CONNECTED\_SERVICES\_ACCOUNT:PERMISSION](/errors/api-errors/connected-services-account-errors#permission) error from API
*   Needing access to an endpoint out of scope for your existing permissions

<Tabs>
  <Tab title="Authorize">
    <Info>
      This flow sends a new authorization code to your callback URI in order to fetch a new access and refresh token. Use this flow if you have set up a custom branded application with its own virtual key.
    </Info>

    ```
        https://connect.smartcar.com/oauth/authorize?
        response_type=code
        &make=TESLA
        &update_access=true
        &client_id=8229df9f-91a0-4ff0-a1ae-a1f38ee24d07
        &scope=read_odometer control_security
        &redirect_uri=https://example.com
        &user_id=8229df9f-91a0-4ff0-a1ae-a1f38ee24d07
        &vehicle_id=8229df9f-91a0-4ff0-a1ae-a1f38ee24d07

    ```

    | name            | type            | required | description                                                                                                                                                                                                                                                                                                            |
    | --------------- | --------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `response_type` | `string`        | true     | This should be set to `code`.                                                                                                                                                                                                                                                                                          |
    | `make`          | `string`        | true     | Specifies the brand to update access to. Currently, the only make available for this flow is `TESLA`.                                                                                                                                                                                                                  |
    | `update_access` | `bool`          | true     | Setting this to `true` sets the behavior of Connect to update access to the specified brand.                                                                                                                                                                                                                           |
    | `client_id`     | `string`        | true     | The application’s unique identifier. This is available on the credentials tab of the Smartcar Dashboard.                                                                                                                                                                                                               |
    | `scope`         | `[permissions]` | true     | A space-separated list of permissions that your application is requesting access to. The valid permission names can be found in the [permissions](/api-reference/permissions) section. When reauthenticating, the user will be required to grant the corresponding OEM permissions before being able to exit the flow. |
    | `redirect_uri`  | `string`        | true     | Required if using the `/authorize` route for Smartcar to return an authorization code.                                                                                                                                                                                                                                 |
    | `user_id`       | `string`        | true     | The Smartcar `user_id` tied to the vehicle returned from [/user](/api-reference/user)                                                                                                                                                                                                                                  |
    | `vehicle_id`    | `string`        | true     | The Smartcar `vehicle_id` associated with the vehicle returned from [/vehicles](/api-reference/all-vehicles)                                                                                                                                                                                                           |
  </Tab>

  <Tab title="Reauthenticate">
    <Info>
      Use this flow if you are using the default Smartcar application and virtual key.
    </Info>

    ```
        https://connect.smartcar.com/oauth/reauthenticate?
        response_type=none
        &make=TESLA
        &revoke_access=true
        &client_id=8229df9f-91a0-4ff0-a1ae-a1f38ee24d07
        &scope=read_odometer control_security
    ```

    | name            | type            | required | description                                                                                                                                                                                                                                                                                                            |
    | --------------- | --------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `response_type` | `string`        | true     | This should be set to `none` .                                                                                                                                                                                                                                                                                         |
    | `make`          | `string`        | true     | Specifies the brand to revoke access to. Currently, the only make available for this flow is `TESLA`.                                                                                                                                                                                                                  |
    | `revoke_access` | `bool`          | true     | Sets the behavior of the reauthenticate flow to revoke access to the specified brand.                                                                                                                                                                                                                                  |
    | `client_id`     | `string`        | true     | The application’s unique identifier. This is available on the credentials tab of the Smartcar Dashboard.                                                                                                                                                                                                               |
    | `scope`         | `[permissions]` | true     | A space-separated list of permissions that your application is requesting access to. The valid permission names can be found in the [permissions](/api-reference/permissions) section. When reauthenticating, the user will be required to grant the corresponding OEM permissions before being able to exit the flow. |
  </Tab>
</Tabs>

## Permission Mappings

<Info>
  These are **currently** the mappings of Smartcar permissions to Tesla's. Given Tesla's aggressive timeline we expect there may be some changes so strongly recommend prompting your users to **Select All** permissions in Tesla's flow to avoid needing to [update access](/help/oem-integrations/tesla/faqs#how-can-my-users-fix-their-permissions-with-tesla) and reauthenticate in the future.
</Info>

| Smartcar Permission          | Tesla Permission          |
| ---------------------------- | ------------------------- |
| `control_charge`             | Vehicle Charge Management |
| `control_climate`            | Vehicle Commands          |
| `control_navigation`         | Vehicle Commands          |
| `control_pin`                | Vehicle Commands          |
| `control_security`           | Vehicle Commands          |
| `control_trunk`              | Vehicle Commands          |
| `read_battery`               | Vehicle Information       |
| `read_charge_records`        | Vehicle Charge Management |
| `read_charge`                | Vehicle Information       |
| `read_climate`               | Vehicle Information       |
| `read_compass`               | Vehicle Information       |
| `read_engine_oil`            | Vehicle Information       |
| `read_extended_vehicle_info` | Vehicle Information       |
| `read_fuel`                  | Vehicle Information       |
| `read_location`              | Vehicle Information       |
| `read_odometer`              | Vehicle Information       |
| `read_security`              | Vehicle Information       |
| `read_speedometer`           | Vehicle Information       |
| `read_thermometer`           | Vehicle Information       |
| `read_tires`                 | Vehicle Information       |
| `read_vehicle_info`          | Vehicle Information       |
| `read_vin`                   | Vehicle Information       |

## For vehicles connected via the old integration

<Info>
  Depending on how many Tesla accounts are associated with a vehicle, there may be changes to the `user_id` returned from the [`/user`](/api-reference/user) endpoint with the new `access_token` minted after authorizing with Tesla's new flow.
</Info>

In this example, we pass the old smartcar `user_id`, but you can use any identifier to indicate this is one of your existing users reauthorizing using the new flow.

```http Connect URL
HTTP/1.1 302 Found
Location: https://connect.smartcar.com/oauth/authorize?
    response_type=code
    &client_id=8229df9f-91a0-4ff0-a1ae-a1f38ee24d07
    &redirect_uri=https://example.com/home
    &scope=read_vehicle_info read_vin read_battery
    &flags=tesla_auth:true
    &state={old_user_id}
```

We'll then send this back to you in our `POST` back to your `redirect_uri`.

```http Connect URL
HTTP/1.1 302 Found
Location: https://example.com/home
?code=90abecb6-e7ab-4b85-864a-e1c8bf67f2ad
&virtual_key_url=https://www.tesla.com/_ak/smartcar.com
&state={old_user_id}
```

After fetching the initial `access_token`, you can fetch the `user_id` from [`/user`](/api-reference/user) and update your record (if applicable) in addition to saving the newly minted token pair.

If a user failed to select the corresponding Tesla permissions for the ones passed to Smartcar, you will receive a `PERMISSION:NULL` error when making an API request. Connect scopes this Smartcar authorization based on the intersect of your requested smartcar permissions with the ones selected by the user on Tesla's side.


# Tesla FAQs

FAQs on our new Tesla integration. For an overview of the changes see [this page](https://smartcar.com/docs/help/oem-integrations/tesla/whats-new).

#### What happens if I connect to one of my applications with the legacy flow and another with the new flow?

As long as you have access to the same set of permissions on Tesla’s side and have added our virtual key there will not be any conflicts while the legacy API is active.

#### If my users have more than one Tesla on their account, will they need to add the virtual key to all of their vehicles?

Yes. You will need to add our virtual key to each vehicle on the Tesla account.

#### What happens if I issue a command but Smartcar’s virtual key hasn’t been added to the vehicle?

We will throw a `CONNECTED_SERVICES_ACCOUNT:VIRTUAL_KEY_REQUIRED` error.

#### What happens if I issue a command but the owner has revoked access through their Tesla portal?

We will throw a `CONNECTED_SERVICES_ACCOUNT:PERMISSION` error.

#### What happens if a user doesn’t select the correct permissions on Tesla’s side?

Connect maps Tesla’s permissions to Smartcar’s and only grants your application access to the ones requested. If we do not get the corresponding permission from Tesla, we will not grant your application access and throw the `PERMISSION:NULL` error as per usual when you make an API request.

Your users will need to [revoke access](\(/help/oem-integrations/tesla/faqs#how-can-my-users-fix-their-permissions-with-tesla\)) through the Tesla portal, then step through the flow again in order to fix this.

#### How can I tell which cars have gone through the new flow?

The [Migration Status](/api-reference/tesla/get-migration-status) make specific endpoint indicates if a vehicle still needs to be migrated to Tesla's new API.

#### Can owner and driver accounts authorize access with Smartcar through Connect?

Yes. Either account type can go through the Connect flow. As long as the Tesla account is attached to the vehicle, you can make requests to it.

#### Does the user need to be next to vehicle when adding Smartcar's virtual key?

No. However, Smartcar's virtual key will need to be added from a phone that is already set up as a key for the vehicle from the **owner's account**.

#### Can driver profiles add Smartcar's virtual key?

No. Only **owners** are able to add Smartcar's virtual key. Once the owner has added the key, either account type will be able to process commands. While only owners are able to add Smartcar's virtual key, drivers are still able to connect their accounts with Smartcar so your application can make requests to the vehicle. If a command is successful or not depends on if the virtual key has been added.

#### How can my users fix their permissions with Tesla?

As some applications require different permissions than others, Tesla requires you to revoke access from Smartcar before re-authorizing more with another application.

In order to do so navigate to **Account** in your Tesla App then select:

1.  Security and Privacy > Manage Third Party Apps
2.  Under Account Settings > Security > Third Party Apps,  hit **Manage** next to **Smartcar**
3.  Select the relevant permissions and hit **Update**
4.  Now you can follow instructions from the application that requested additional permissions in order to reconnect your Tesla with the required permissions.

<Tabs>
  <Tab title="Mobile Device">
    <Steps>
      <Step title="In-app Profile">
        <img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/help-center/oem-integrations/tesla/revoke-access/mobile/app-profile.png" />
      </Step>

      <Step title="Login">
        <img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/help-center/oem-integrations/tesla/revoke-access/mobile/tesla-login.png" />
      </Step>

      <Step title="Update Access">
        <img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/help-center/oem-integrations/tesla/update-access/update-access.png" />
      </Step>
    </Steps>
  </Tab>

  <Tab title="Desktop">
    <Steps>
      <Step title="Browser Profile">
        <img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/help-center/oem-integrations/tesla/revoke-access/desktop/browser-profile.png" />
      </Step>

      <Step title="Login">
        <img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/help-center/oem-integrations/tesla/revoke-access/desktop/tesla-login.png" />
      </Step>

      <Step title="Update Access">
        <img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/help-center/oem-integrations/tesla/update-access/update-access.png" />
      </Step>
    </Steps>
  </Tab>
</Tabs>


# What's New?



As you may have heard, Tesla is in the process of deprecating their legacy API and requiring third party developers to use their new architecture.

Tesla has set an aggressive timeline of deprecating their legacy API by **January 2024**. In order to minimize disruption, this will necessitate the following:

1.  Vehicle owners will need to go through our new Tesla specific Connect flow in order for you to retain data access.
2.  If you’re issuing commands, your users will also need to add Smartcar’s virtual key.

## The new Connect flow for Tesla owners

Starting December 18, 2023, Tesla owners connecting to your application will go through a new version of Smartcar Connect for customers on our Free, Build and Scale Plan. This will not require any code changes on your end.

Enterprise customers will have the option of going through a new version of Smartcar Connect that uses their own brand on the Tesla Login screen. This will require minor changes [documented here](/help/oem-integrations/tesla/developers#virtual-keys-for-smartcar-enterprise-customers), and will be possible starting December 20, 2023. Your Smartcar account manager can walk you through these steps.

<Steps>
  <Step title="Launching Connect">
    <img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/help-center/oem-integrations/tesla/default-login/preamble.png" />
  </Step>

  <Step title="Authorize with Tesla">
    <img src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/help-center/oem-integrations/tesla/default-login/tesla-auth.png" />
  </Step>

  <Step title="Grant Screen">
    <img height="400" width="400" src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/help-center/oem-integrations/tesla/default-login/grant-screen.png" />
  </Step>
</Steps>

For more information on testing out the new flow, please see our [developer guide](/help/oem-integrations/tesla/developers).

## For existing vehicles

Vehicle owners that are already connected to your application can use our streamlined reauthentication flow to accomplish this. For more information on using this flow, please see our [guide for developers](/help/oem-integrations/tesla/developers).

<Steps>
  <Step title="Launching the Re-auth Flow">
    <img height="400" width="400" src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/help-center/oem-integrations/tesla/re-auth/preamble.png" />
  </Step>

  <Step title="Authorize with Tesla">
    <img height="400" width="600" src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/help-center/oem-integrations/tesla/re-auth/tesla-auth.png" />
  </Step>

  <Step title="Successful Reconnect">
    <img height="400" width="400" src="https://mintlify.s3-us-west-1.amazonaws.com/smartcar-docs/images/help-center/oem-integrations/tesla/re-auth/success.png" />
  </Step>
</Steps>

## If your application issues commands

In addition to permissions from their authorization flow, Tesla now **requires** virtual keys for 3rd-party applications
in order to issue commands for the following models:

*   All Cybertrucks, Model 3 and Model Y
*   2021+ Model S and X

<Tip>
  Adding a Virtual Key will need to be done after a vehicle owner goes through Tesla's authorization flow with Smartcar.

  Authorizing their Tesla account and adding the key are separate processes.

  Please see our [vehicle owner](/help/oem-integrations/tesla/owners) page for details on getting Phone as a Key and the virtual key set up.
</Tip>

## Next steps

For detailed instructions on how to get set up for the upgraded integration please see our [guide for developers](/help/oem-integrations/tesla/developers).


# OEM Latency

Request latency we've observed by make

## Acura

| HTTP Method | p95 (seconds) | Median (seconds) |
| ----------- | ------------- | ---------------- |
| GET         | 22            | 2                |
| POST        | 38            | 1                |

## Audi

| HTTP Method | p95 (seconds) | Median (seconds) |
| ----------- | ------------- | ---------------- |
| GET         | 9             | 2                |
| POST        | 55            | 28               |

## BMW/MINI

| HTTP Method | p95 (seconds) | Median (seconds) |
| ----------- | ------------- | ---------------- |
| GET         | 5             | 2                |
| POST        | 93            | 17               |

## Cupra

| HTTP Method | p95 (seconds) | Median (seconds) |
| ----------- | ------------- | ---------------- |
| GET         | 9             | 4                |
| POST        | 170           | 151              |

## Fiat

| HTTP Method | p95 (seconds) | Median (seconds) |
| ----------- | ------------- | ---------------- |
| GET         | 9             | 7                |

## Ford

| HTTP Method | p95 (seconds) | Median (seconds) |
| ----------- | ------------- | ---------------- |
| GET         | 42            | 11               |
| POST        | 90            | 23               |

## GM (Buick, Chevrolet, Cadillac, GMC)

| HTTP Method | p95 (seconds) | Median (seconds) |
| ----------- | ------------- | ---------------- |
| GET         | 145           | 33               |
| POST        | 70            | 7                |

## Honda

| HTTP Method | p95 (seconds) | Median (seconds) |
| ----------- | ------------- | ---------------- |
| GET         | 46            | 34               |

## Hyundai

| HTTP Method | p95 (seconds) | Median (seconds) |
| ----------- | ------------- | ---------------- |
| GET         | 41            | 6                |
| POST        | 125           | 16               |

## Infiniti

| HTTP Method | p95 (seconds) | Median (seconds) |
| ----------- | ------------- | ---------------- |
| GET         | 29            | 18               |
| POST        | 20            | 2                |

## Jaguar/Land Rover

| HTTP Method | p95 (seconds) | Median (seconds) |
| ----------- | ------------- | ---------------- |
| GET         | 128           | 18               |
| POST        | 182           | 66               |

## Kia

| HTTP Method | p95 (seconds) | Median (seconds) |
| ----------- | ------------- | ---------------- |
| GET         | 120           | 3                |
| POST        | 56            | 14               |

## Mazda

| HTTP Method | p95 (seconds) | Median (seconds) |
| ----------- | ------------- | ---------------- |
| GET         | 9             | 5                |
| POST        | 58            | 36               |

## Mercedes-Benz

| HTTP Method | p95 (seconds) | Median (seconds) |
| ----------- | ------------- | ---------------- |
| GET         | 17            | 2                |
| POST        | 271           | 129              |

## MG

| HTTP Method | p95 (seconds) | Median (seconds) |
| ----------- | ------------- | ---------------- |
| GET         | 15            | 7                |
| POST        | 26            | 8                |

## Nissan

| HTTP Method | p95 (seconds) | Median (seconds) |
| ----------- | ------------- | ---------------- |
| GET         | 75            | 2                |
| POST        | 50            | 2                |

## Porsche

| HTTP Method | p95 (seconds) | Median (seconds) |
| ----------- | ------------- | ---------------- |
| GET         | 8             | 2                |
| POST        | 29            | 10               |

## PSA Group (Citroen, DS, Opel, Peugeot, Vauxhall)

| HTTP Method | p95 (seconds) | Median (seconds) |
| ----------- | ------------- | ---------------- |
| GET         | 26            | 4                |
| POST        | 33            | 31               |

## Stellantis (Chrysler, Dodge, Jeep, RAM)

| HTTP Method | p95 (seconds) | Median (seconds) |
| ----------- | ------------- | ---------------- |
| GET         | 6             | 4                |
| POST        | 62            | 35               |

## Renault

| HTTP Method | p95 (seconds) | Median (seconds) |
| ----------- | ------------- | ---------------- |
| GET         | 3             | 2                |
| POST        | 10            | 6                |

## Rivian

| HTTP Method | p95 (seconds) | Median (seconds) |
| ----------- | ------------- | ---------------- |
| GET         | 3             | 1                |

## Skoda

| HTTP Method | p95 (seconds) | Median (seconds) |
| ----------- | ------------- | ---------------- |
| GET         | 49            | 6                |
| POST        | 15            | 13               |

## Subaru

| HTTP Method | p95 (seconds) | Median (seconds) |
| ----------- | ------------- | ---------------- |
| GET         | 41            | 38               |
| POST        | 39            | 21               |

## Tesla

| HTTP Method | p95 (seconds) | Median (seconds) |
| ----------- | ------------- | ---------------- |
| GET         | 25            | 2                |
| POST        | 15            | 2                |

## Toyota/Lexus

| HTTP Method | p95 (seconds) | Median (seconds) |
| ----------- | ------------- | ---------------- |
| GET         | 152           | 25               |
| POST        | 126           | 20               |

## Volkswagen

| HTTP Method | p95 (seconds) | Median (seconds) |
| ----------- | ------------- | ---------------- |
| GET         | 11            | 4                |
| POST        | 290           | 33               |

## Volvo

| HTTP Method | p95 (seconds) | Median (seconds) |
| ----------- | ------------- | ---------------- |
| GET         | 144           | 20               |
| POST        | 155           | 30               |


# Reliability and Data Age

When making requests to vehicles, there is variation in how often data is updated and how many requests it can process in a given period. The tables below indicate the performance for each of Smartcar supported brands in each region.

**Reliability**<br />

Ranking indicates the reliability of data requests upstream i.e. the vehicle's or OEM's ability to process a request where 1 is the most reliable.

**Data Freshness**<br />
For a successful request, ranking indicates the average time since the data was last updated by the vehicle where 1 is the most fresh data for data or least average latency for actions.

***

# North America

### Data

| <div style={{ width:200 }}>Make </div> | <div style={{ width:150 }}>Reliabilty </div> | <div style={{ width:150 }}>Data Freshness </div> |
| -------------------------------------- | -------------------------------------------- | ------------------------------------------------ |
| Tesla                                  | 1                                            | 1                                                |
| Volvo                                  | 1                                            | 1                                                |
| Volkswagen                             | 1                                            | 2                                                |
| Buick                                  | 2                                            | 1                                                |
| Chevrolet                              | 2                                            | 1                                                |
| GMC                                    | 2                                            | 1                                                |
| Jaguar                                 | 2                                            | 1                                                |
| Kia                                    | 2                                            | 1                                                |
| Land Rover                             | 2                                            | 1                                                |
| Nissan (non-Leaf)                      | 2                                            | 1                                                |
| Porsche                                | 2                                            | 1                                                |
| Toyota                                 | 2                                            | 1                                                |
| Hyundai                                | 2                                            | 2                                                |
| Rivian                                 | 2                                            | 2                                                |
| Audi                                   | 2                                            | 3                                                |
| BMW                                    | 2                                            | 3                                                |
| Chrysler                               | 2                                            | 3                                                |
| Jeep                                   | 2                                            | 3                                                |
| Mercedes-Benz                          | 2                                            | 3                                                |
| Mini                                   | 2                                            | 3                                                |
| Cadillac                               | 3                                            | 1                                                |
| Ford                                   | 3                                            | 1                                                |
| Infiniti                               | 3                                            | 1                                                |
| Lexus                                  | 3                                            | 1                                                |
| Lincoln                                | 3                                            | 1                                                |
| Nissan Leaf                            | 3                                            | 1                                                |
| Acura                                  | 3                                            | 3                                                |
| Dodge                                  | 3                                            | 3                                                |
| Mazda                                  | 3                                            | 3                                                |
| RAM                                    | 3                                            | 3                                                |

# Europe

### Data

| <div style={{ width:200 }}>Make </div> | <div style={{ width:150 }}>Reliabilty </div> | <div style={{ width:150 }}>Data Freshness </div> |
| -------------------------------------- | -------------------------------------------- | ------------------------------------------------ |
| Jaguar                                 | 1                                            | 1                                                |
| Tesla                                  | 1                                            | 1                                                |
| Citroen                                | 1                                            | 2                                                |
| Porsche                                | 1                                            | 2                                                |
| DS                                     | 1                                            | 3                                                |
| Vauxhall                               | 1                                            | 3                                                |
| Kia                                    | 2                                            | 1                                                |
| Land Rover                             | 2                                            | 1                                                |
| Volvo                                  | 2                                            | 1                                                |
| CUPRA                                  | 2                                            | 3                                                |
| Peugeot                                | 2                                            | 3                                                |
| Volkswagen                             | 2                                            | 3                                                |
| Ford                                   | 3                                            | 1                                                |
| Nissan                                 | 3                                            | 1                                                |
| Skoda                                  | 3                                            | 1                                                |
| Audi                                   | 3                                            | 3                                                |
| BMW                                    | 3                                            | 3                                                |
| Hyundai                                | 3                                            | 3                                                |
| Mazda                                  | 3                                            | 3                                                |
| Mercedes-Benz                          | 3                                            | 3                                                |
| Mini                                   | 3                                            | 3                                                |
| Opel                                   | 3                                            | 3                                                |
| Renault                                | 3                                            | 3                                                |

Last Updated: December 2023


# Join the Research Fleet



Smartcar is a company building an API for cars funded by [a16z](https://a16z.com/), [NEA](https://www.nea.com/) and [Energize Capital](https://www.energizecap.com/).\
We enable companies like [Turo](https://explore.turo.com/turo-go/) to monitor a car's status and remotely lock/unlock the doors for a contact-free rental experience.
We are always expanding to new makes and models of cars and we'd love your help!

## What are we asking for?

Building and maintaining our APIs is a complex endeavor. Smartcar operates a research fleet of vehicles across brands, models, and geographies
to ensure we can provide the best product possible. This is where you come in. We'd like to use your car in order to verify our ability to do things like:

*   Read your car’s odometer
*   View the amount of fuel/battery your car has remaining
*   Obtain your car’s VIN

## Perks of being part of the Research Fleet

*   💰 You will receive \$250 for the 6 months that your car is part of the fleet
*   🧥 A Smartcar Research Fleet sweater
*   🙋 Assistance setting up your car's connected services

## Sign up

<iframe src="https://form.typeform.com/to/a8XPIn9W?utm_source=docs.smartcar.com&utm_medium=form-embed&utm_campaign=research-fleet" width="700" height="700" allow="fullscreen" />

## FAQs

<AccordionGroup>
  <Accordion title="How and when will I get paid?">
    The Smartcar team will schedule a check to be sent to your preferred address if your car is verified to be eligible for the Smartcar Research Fleet.
  </Accordion>

  <Accordion title="What exactly will Smartcar do with my car?">
    Smartcar will use your vehicle to retrieve and verify key data points such as your odometer and fuel tank/battery level.
    The team will inform you of all data and actions they will retrieve from your vehicle and the schedule at which they will be performing the verification.
  </Accordion>
</AccordionGroup>


# Teams

With Teams you're able to easily manage your team's access to Dashboard

## Roles and Permissions

Team members can be added on any plan. Specific roles are available on our [Enterprise plan](https://smartcar.com/pricing).

| <div style={{ width:200 }} /> | Owner <div style={{ width:100 }} /> | Admin <div style={{ width:100 }} /> | Editor <div style={{ width:100 }} /> | Viewer <div style={{ width:100 }} /> |
| ----------------------------- | ----------------------------------- | ----------------------------------- | ------------------------------------ | ------------------------------------ |
| Manage billing                | ✅                                   |                                     |                                      |                                      |
| View billing                  | ✅                                   |                                     |                                      |                                      |
| Delete applications           | ✅                                   |                                     |                                      |                                      |
| Modify team settings          | ✅                                   |                                     |                                      |                                      |
| Remove team members           | ✅                                   | ✅                                   |                                      |                                      |
| Modify team members           | ✅                                   | ✅                                   |                                      |                                      |
| Create applications           | ✅                                   | ✅                                   |                                      |                                      |
| Modify applications           | ✅                                   | ✅                                   | ✅                                    |                                      |
| View applications             | ✅                                   | ✅                                   | ✅                                    | ✅                                    |
| View team members             | ✅                                   | ✅                                   | ✅                                    | ✅                                    |

<Tip>
  Editors and Viewers can be limited to specific applications.
</Tip>

## Roles

### Owner

Owners have full control and access to the team. They're able to add and remove members, create and modify applications, edit billing information and more.

A team **can** have multiple Owners, but **must** have at least one.

### Admin

Admins have similar access to Owners but can't edit or view billing information.

### Editor

Editors have similar access to Admins but are limited to specific applications. They're unable to manage team members, view the team's billing information, create applications, or delete applications they're allowed to access.

### Viewer

Viewers have similar permissions to Editors but only have read-only access to applications they've been invited to.


# Vehicle Simulator

Learn about what to expect from Vehicle Simulator and how it compares to Live mode.

Vehicle Simulator allows you to test your application in realistic scenarios with a simulated Smartcar-compatible vehicle. Simulator responds to API requests just like a real vehicle. You can choose a simulated trip for your vehicle to take, and track it over time.

You can use the simulator for initial testing before you have a real vehicle to connect, or as part of an end-to-end testing suite.

## Creating a Simulated Vehicle

Simulated vehicles are managed in the Smartcar Dashboard.

Select "Add a vehicle" and select a vehicle by Make, Model, and Year, or provide a VIN for a US-based vehicle that you want to simulate. You'll be able to preview the API endpoints that are supported for the vehicle model you select.

Once you create your simulated vehicle, you'll select a simulated trip profile that the vehicle will follow. This profile can run automatically over time, or you can manually select a stage of the trip for the vehicle in the Dashboard.

## Connecting a Simulated Vehicle

Simulated vehicles generate a special set of credentials that mimic what a real-world vehicle owner would have. You'll use these credentials to establish a vehicle connection through the same Smartcar Connect flow that you will use for live vehicles.

In order for Connect to know you're using credentials generated from Vehicle Simulator, you'll need to pass `mode=simulated` in the [Connect URL](/connect/redirect-to-connect).

<Info>
  Please ensure you're passing or changing the country flag for Connect based on the region you've created your vehicle for.
  Failure to do so will result in an invalid credential error on login. You can read more about country selection for Connect [here](/connect/advanced-config/country-flag).
</Info>

<AccordionGroup>
  <Accordion title="SDKs">
    You can set `mode` in the auth client builder to `simulated`.
  </Accordion>

  <Accordion title="No SDK">
    You'll need to pass `mode=simulated` in the Connect URL
  </Accordion>
</AccordionGroup>

## Making requests to a Simulated Vehicle

Once your simulated vehicle is connected, you can make API requests to it just as you would a real vehicle.

Supported endpoints for the simulated vehicle will send responses with simulated data - unsupported endpoints will return errors just as they would with a real vehicle.

You can also send commands to simulated vehicles, like start/stop charge or lock/unlock doors. These requests will send responses that mimic that of a real vehicle, but the vehicle state will continue to reflect the simulated trip that was selected.

## Expected Responses

### Data

| Permission          | Request Method / Path | Example Response                                                                            |
| ------------------- | --------------------- | ------------------------------------------------------------------------------------------- |
| `read_engine_oil`   | GET /engine/oil       | `{ lifeRemaining: 0.35 }`                                                                   |
| `read_battery`      | GET /battery          | `{ percentRemaining: 0.3, range: 40.5 }`                                                    |
| `read_battery`      | GET /battery/capacity | `{ capacity: 28 }`                                                                          |
| `read_charge`       | GET /charge           | `{ isPluggedIn: true, state: 'FULLY_CHARGED' }`                                             |
| `read_charge`       | GET /charge/limit     | `{ limit: 1 }`                                                                              |
| `read_fuel`         | GET /fuel             | `{ amountRemaining: 53.2, percentRemaining: 0.3, range: 40.5 }`                             |
| `read_location`     | GET /location         | `{ latitude: 37.4292, longitude: 122.1382 }`                                                |
| `read_odometer`     | GET /odometer         | `{ distance: 104.32 }`                                                                      |
| `read_tires`        | GET /tires/pressure   | `{ backLeft: 219.3, backRight: 219.3, frontLeft: 219.3, frontRight: 219.3 }`                |
| `read_vehicle_info` | GET /                 | `{ id: 36ab27d0-fd9d-4455-823a-ce30af709ffc, make: "TESLA", model: "Model S", year: 2014 }` |
| `read_vin`          | GET /vin              | `{ vin: 1234A67Q90F2T4567 }`                                                                |

### Commands

Below are the various action requests that can be made to simulated vehicles, and what responses to expect based on the simulated vehicle's current state or simulator support.

Not listed here are the standard API errors that will be returned if the vehicle does not support the capability or the application has not been granted permission.

| Permission         | Request (method / path) | Action request | Vehicle state                     | Response                                                       |
| ------------------ | ----------------------- | -------------- | --------------------------------- | -------------------------------------------------------------- |
| `control_security` | POST /security          | `LOCK`         | Parked / Charging                 | `{ status: "success" }`                                        |
| `control_security` | POST /security          | `UNLOCK`       | Parked / Charging                 | `{ status: "success" }`                                        |
| `control_security` | POST /security          | `LOCK`         | Driving                           | `{ type: VEHICLE_STATE, code: IN_MOTION }`                     |
| `control_security` | POST /security          | `UNLOCK`       | Driving                           | `{ type: VEHICLE_STATE, code: IN_MOTION }`                     |
| `control_charge`   | POST /charge            | `START`        | Charging                          | `{ status: "success" }`                                        |
| `control_charge`   | POST /charge            | `STOP`         | Charging                          | `{ status: "success" }`                                        |
| `control_charge`   | POST /charge            | `STOP`         | Parked / Driving (not plugged in) | `{ type: VEHICLE_STATE, code: CHARGING_PLUG_NOT_CONNECTED }`   |
| `control_charge`   | POST /charge            | `START`        | Parked / Driving (not plugged in) | `{ type: VEHICLE_STATE, code: CHARGING_PLUG_NOT_CONNECTED }`   |
| `control_charge`   | POST /charge-limit      | `<limit>`      | Charging                          | `{ "type": "COMPATIBILITY", "code": "SMARTCAR_NOT_CAPABLE", }` |
| `control_charge`   | POST /charge-limit      | `<limit>`      | Parked / Driving (not plugged in) | `{ type: VEHICLE_STATE, code: CHARGING_PLUG_NOT_CONNECTED }`   |

### Errors

| Event                                                                                                               | Error response                                                                     | Suggested resolution                                                                                                                                                                                                                                                                      |
| ------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Making an API request to a simulated vehicle before connecting the vehicle to your application via Smartcar Connect | `{ type: "PERMISSION", statusCode: 403, resolution: "REAUTHENTICATE" }`            | Locate the 'Connect Credentials' button at the top of the simulation screen in the Smartcar Dashboard for your simulated vehicle. There you will find the credentials necessary to connect the vehicle to your application as well as instructions for doing so through Smartcar Connect. |
| Making an API request to a simulated vehicle before a simulation has been started on Dashboard                      | `{ type: "CONNECTED_SERVICES_ACCOUNT", code: "ACCOUNT_ISSUE", statusCode: 400 }`   | Open the Simulator tab in the Smartcar Dashboard and navigate to your target vehicle. If you haven't yet selected a vehicle state, do so now, and then start the simulation using the 'Play' button on the simulation screen.                                                             |
| Making an API request to a simulated vehicle that is not associated with  your application                          | `{ type: "CONNECTED_SERVICES_ACCOUNT", code: "VEHICLE_MISSING", statusCode: 400 }` | Ensure the simulated vehicle you are making requests to has been created in the Simulator within your Smartcar Dashboard.                                                                                                                                                                 |

## Mode Comparison

| <div style={{ width:180 }} />Feature | <div style={{ width:80 }} />Simulator | <div style={{ width:80 }} />Live |   |
| ------------------------------------ | ------------------------------------- | -------------------------------- | - |
| Single Select                        | ✅                                     | ✅                                |   |
| Brand Select                         | ✅                                     | ✅                                |   |
| Compatibility API\*                  | ✅                                     | ✅                                |   |
| `control_security`                   | ✅                                     | ✅                                |   |
| `control_charge`                     | ✅                                     | ✅                                |   |
| Make-Specific Endpoints              | ❌                                     | ✅                                |   |
| Scheduled Webhooks                   | ❌                                     | ✅                                |   |
| Event Based Webhooks\*\*             | ❌                                     | ✅                                |   |

<sub>
  <sup>
    \*When a real VIN is used either through `VIN@smartcar` for `test` mode, or generating a simulated vehicle with a real VIN.
  </sup>

  <sup>
    0SC and 1SC prefixed VINs will not work.
  </sup>
</sub>

<sub>
  <sup>
    \*\*For supported brands - Toyota, Ford and Tesla.
  </sup>
</sub>

## FAQs

<AccordionGroup>
  <Accordion title="How are tokens handled?">
    Access and refresh tokens behave as they do in `live` mode:

    *   Access Tokens are valid for 2 hours
    *   Refresh Tokens are valid for 60 days.
    *   Using a refresh token to fetch an new access/refresh token pair will invalidate the refresh token that you used.

    **Reusing simulated vehicle credentials**<br />
    If you use the same simulated credentials for multiple Connect flow sessions, we'll issue a new set of tokens each time.
    This will not invalidate any existing tokens from previous logins so you'll be able to keep them refreshed in parallel without impacting the validity of the others.
  </Accordion>

  <Accordion title="Are there any limits on how many vehicles I can create?">
    The number of simulated vehicles that can be created depends on your Smartcar plan tier. Please see [here](https://smartcar.com/pricing#plans) for more information.
  </Accordion>

  <Accordion title="I'm getting an invalid credentials error when I try to sign in to a connected service account.">
    *   Please check that you have launched Connect with the `mode=simulated` parameter
    *   Please check that you are passing the country feature flag for the region you've set up your vehicle with.
        Please see [Country Selection](/connect/advanced-config/country-flag)for Connect for more information.
  </Accordion>
</AccordionGroup>


# What is a Connected Car?

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

Connected cars are vehicles that have in-built cellular modems. Most vehicles manufactured after 2015 have been shipping with this connectivity, or "embedded telematics." This essentially makes cars "smart" allowing them to communicate with the Internet. Take a look at this blog post for an in depth primer.


# What is Smartcar?

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

The Smartcar platform allows mobility businesses to easily connect with their customers’ cars. Whether you need to track a vehicle’s location,
verify its mileage, share a virtual key, start charging an EV, monitor a car’s fuel tank level, inspect the tire pressure, or check the engine
oil life, Smartcar lets you do so with a single API request.

Take a look at the video below for a quick overview of how Smartcar works.

<Frame type="simple">
  <iframe width="800" height="450" src="https://www.youtube.com/embed/P-7CP70r-8U" />
</Frame>