| | ----------------------------- | ----------------------------- | ----------------------------- | ----------------------------- | | Audi | Hyundai | Mercedes-Benz | Skoda | | BMW | Jaguar | MINI | Vauxhall | | Citroen | Kia | Opel | Volkswagen | | DS | Land Rover | Peugeot | Volvo | | Ford | Mazda | Renault | | # Latest Releases Source: https://smartcar.com/docs/changelog/latest Learn about Smartcar's latest product updates and improvements [Subscribe to changelog updates](https://sta26.share.hsforms.com/2CCbdweFdSOeE5B58UvjVlw) and receive email notifications for new releases and updates. ## Smartcar Partners with Mercedes-Benz Connectivity Services GmbH!

We are excited to announce our partnership with Mercedes-Benz Connectivity Services GmbH, expanding seamless access to connected vehicle data for developers and businesses across Europe. This integration enables developers to build innovative applications using data from Mercedes-Benz vehicles, including popular models such as the A-Class, C-Class, E-Class, S-Class, GLA, GLC, and more. With this partnership, Smartcar customers can leverage secure, reliable, and real-time access to vehicle data for a wide range of use cases, from fleet management to mobility services. Read more about this partnership and its impact in our [blog post](https://smartcar.com/blog/smartcar-partners-with-mercedes-benz-connectivity-services-gmbh). ## Introducing the new Smartcar Platform!

We are excited to announce the launch of the new Smartcar Platform, designed to provide a more reliable and efficient way to access vehicle data. With our new [webhook integration](/integrations/webhooks/overview) and [API](/api-reference/intro), developers can now receive vehicle data at higher frequencies and with improved reliability. For all use cases, Smartcar can deliver data as it detect changes based on our new standardized Signal Schema while avoiding unnecessary polling. With over 80 signals available, developers can access a wide range of vehicle data to build innovative applications. Getting started with Smartcar is now even easier. [Configure](/getting-started/configure-application) your app, [Connect](/getting-started/connect-vehicles) vehicles, and start receiving data via [webhooks](/integrations/webhooks/overview) in just a few minutes. To get started with the new webhooks, check out our [Getting Started guide](/getting-started/introduction) and [Webhook integration overview](/integrations/webhooks/overview). These new features are now available to all new customers. Existing customers can reach out to their account manager or contact our support team at [support@smartcar.com](mailto:support@smartcar.com) ## Smartcar Partners with Ford in Europe!

Smartcar is thrilled to announce our partnership with Ford in Europe, enabling developers to access vehicle data from millions of Ford vehicles across the continent. This upcoming integration will give developers seamless access to vehicle data from models including the Mustang Mach‑E®, E‑Transit™, Puma, Fiesta, and Kuga. Read more about this exciting partnership in our [blog post](https://smartcar.com/blog/smartcar-partners-with-ford-to-expand-access-to-connected-vehicle-apis?utm_source=docs\&utm_medium=changelog). ## Rivian Commands Now Available!

You can now use the Smartcar API to send commands—such as lock, unlock, and start/stop charge—to Rivian vehicles! When requesting command permissions (like `control_security` or `control_charge`), Rivian owners will be prompted to pair their phone with their vehicle. After successful pairing, your application will be able to issue commands to the connected Rivian. For step-by-step instructions, see our [Rivian Bluetooth Pairing guide](/connect/other-actions/rivian-bluetooth-pairing). > **Note:** Read data permissions (such as `read_location` or `read_charge`) do not require Bluetooth pairing. > > Smartcar mobile SDKs for iOS and Android are required for Bluetooth pairing. ## Hyundai Lock and Unlock now available!

You can now lock and unlock Hyundai vehicles using the same standard Smartcar API. This new feature enables remote control of vehicle doors for supported Hyundai models, making it easier to build secure and convenient experiences for your users. For more details on how to use this capability, see our [API reference](/api-reference/control-lock-unlock). ## Webhook Logs Now Available in Dashboard You can now view logs for your webhooks directly in the Smartcar Dashboard, alongside your API request logs. This update gives you greater visibility into webhook deliveries, making it easier to monitor, debug, and ensure successful integrations. To see your webhook logs in action, head over to the [Smartcar Dashboard](https://dashboard.smartcar.com/logs?tab=webhooks). ## New Dashboard Overview Page

Our new Dashboard overview page offers a comprehensive snapshot of your application's performance at a glance. Now, you can quickly visualize: * Total vehicle connections * New connections in the last 7 days * Request trends over time * Conversion rates * Top five vehicle brands connected to your application This update is designed to help you monitor key metrics effortlessly. ## Virtual Keys installation Are Now Supported in Connect Smartcar now provides detailed steps for adding and managing Virtual Keys during the connection flow. Virtual Keys are required for third-party applications to issue commands to Tesla vehicles and are the preferred method for accessing data.

For more details, visit the [Virtual Key documentation](/help/oem-integrations/tesla/virtual-key-tesla). ## atHome signal is now available!

Smartcar now supports a new vehicle signal `atHome` that returns true or false if a vehicle is at the configured home location. This signal is currently available for Tesla vehicles capable of streaming via [this endpoint](/api-reference/tesla/get-ext-vehicle-info). ## Our New Support Features Are Live!

We’re excited to share that our new support experience is now available. These updates are designed to make it easier and faster to get the help you need through self-service tools, AI-powered assistance, and improved visibility into your support history. **Customer Support Portal** *(Available to paid customers via the Smartcar Dashboard)* Your new central hub for all support-related needs: * Browse the **Knowledge Base** for helpful articles, guides, and troubleshooting tips * Submit new support requests through a user-friendly form * View and update **open tickets**, track past communications, and receive timely updates * Get help fast with our **AI-powered chat agent**, available 24/7 **Enhanced Slack Support** *(For eligible plans)* Our upgraded Slack support includes: * AI-powered answers to common questions directly in your Slack channel * Ability to create and track support tickets without leaving Slack * One-click access to the Customer Support Portal * Real-time updates and faster response workflows For more information about what’s included in your current plan, please reach out to your account manager or contact us at [**support@smartcar.com**](mailto:support@smartcar.com). For step-by-step instructions on how to use the new features, check out our documentation [here](https://smartcar.com/docs/help/accessing-support-center). ## Support for Single Sign-on (SSO)

Single Sign-On (SSO) is now available for teams on an Enterprise plan. To get started, reach out to your account manager to have it enabled. For implementation details and setup instructions, check out our [SSO documentation](/getting-started/dashboard/single-sign-on). ## User Selected Battery Capacity

Developers can now redirect vehicle owners to a Smartcar Connect url where they can select the [battery capacity](/api-reference/get-nominal-capacity) of their vehicle for cases where the battery capacity cannot be accurately deteremined. This can occur when vehicle owners purchase extension packs, or software upgrades specific to their vehicle. When a user selects an option, Smartcar will return this value with `USER_SELECTED` as the source. ## Diagnostics Webhooks, DTSs, and System Status Smartcar now provides Diagnostic Webhooks, DTCs, and System Status vehicle data for an [initial set of brands](https://smartcar.com/product/compatible-vehicles) with more brands added in the future. ## Support for Simplified Chinese

Vehicle owners can now select Simplified Chinese as they go through the Smartcar Connect flow to connect their cars. ## Tesla Telemetry API Smartcar natively supports Tesla's Telemetry API as the default mechanism for retrieving data from Tesla vehicles out of the box and without any configuration from developers. Tesla's Telemtry API is the most efficient and effective way of gathering data from Tesla vehicles. It allows vehicles to stream data directly to Smartcar, eliminating the need to poll Tesla servers. This prevents unnecessary vehicle wakes and battery drain. ## Smartcar MFA When a vehicle owner attempts to login to their OEM Connected Services Account and they do not have MFA enabled, Smartcar customers can enable this feature to enforce MFA verification for extra security. If you don't see this option in the Smartcar dashboard, contact [support@smartcar.com](mailto:support@smartcar.com) to get access to this feature. ## New Billing page in Dashboard

This new page provides more visibility and the ability to update your billing information, view past invoices, and view your plan features and available upgrade options. # Country Selection Source: 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. You can override this behavior 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. Our SDKs provide ways for you to add this as part of the various `authUrlBuilder` or `getAuthUrl` methods. ```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:

# Connect Flows Source: https://smartcar.com/docs/connect/advanced-config/flows Connect can be launched with three different workflows (defult, single select, and single select with VIN). 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. 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.

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.

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.

To enable Single Select with VIN, you can pass `single_select=true` and `single_select_vin=:vin` as URL parameters when launching Smartcar Connect. ### 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.

To enable Brand Select, you can pass `make` as URL parameter when launching Connect. For example, `make=TESLA` # Modes Source: https://smartcar.com/docs/connect/advanced-config/modes Connect can be launched in different modes depending on whether you want to interact with real vehicles or test your integration. If no mode is specified, Connect will launch in `live` mode by default. | Mode | Description | | --------- | --------------------------------------------------------------------------------------------------------------------- | | live | Launches Connect in live mode allowing a user to log in with a real connected services account. | | simulated | Launches Connect in simulated mode allowing developers to connect to vehicles created on Dashboard via the Simulator. | # SDKs for Connect Source: https://smartcar.com/docs/connect/connect-sdks 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](/api-reference/api-sdks) to manage tokens and make API requests to vehicles. **Note:** In addition to using a frontend SDK to integrate with Smartcar Connect, a backend SDK is strongly recommended to securely manage tokens, receive data from Smartcar, and make API requests to issue commands to vehicles. The backend SDK facilitates authentication, token exchange, and all communication with Smartcar’s APIs. For server-side rendered applications, you can use one of our backend SDKs:
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. # Dashboard Configuration Source: https://smartcar.com/docs/connect/dashboard-config ## 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 authorization server. ## 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 first redirect URI you add to your application is automatically set as the default. If you do not specify a `redirect_uri` in your Connect URL, Smartcar will use this default URI. You can add multiple URIs and set any of them as the default in the Smartcar Dashboard. 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` | HTTP is allowed only for testing purposes on localhost ### 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 Source: 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 an error, we'll provide an error and description as parameters instead. ## Success An authorization code used to obtain your initial `ACCESS_TOKEN`. The auth `code` expires after **10 minutes**. ```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](/api-reference/api-errors). The type of error A detailed description of what caused the error ```http Error HTTP/1.1 302 Found Location: https://example.com/home? error=access_denied &error_description=User+denied+access+to+application. &state=0facda3319 ``` 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. Can be returned for errors where the vehicle is incompatible. The manufacturer of the vehicle. The model of the vehicle. The year of production of the vehicle. # Rivian Bluetooth Pairing Source: https://smartcar.com/docs/connect/other-actions/rivian-bluetooth-pairing To support vehicle commands such as lock/unlock or start/stop charge, Rivian requires a mobile device to be paired via Bluetooth with the vehicle. If permissions for commands are requested in your Connect URL (i.e. `control_security`, `control_charge`), Rivian owners will be prompted to pair their phone to the vehicle to complete the connection. After successful login, users will see a list of vehicles within their Rivian account to pair to. It is important that the mobile phone has Bluetooth enabled at this time.

After selecting the vehicle, the user will be prompted to tap “Set up now” on the Rivian vehicle’s display and follow any on-screen prompts to connect.

Once setup is complete, the application will be able to issue commands to the Rivian vehicle.

Should Bluetooth be disabled or the Rivian display prompts not followed, the Bluetooth connection will not be established and the vehicle will not be connected to your application.

## Notes * Rivian vehicles must be paired via Bluetooth to support commands. Data permissions (i.e. `read_location`, `read_charge`) do not require Bluetooth pairing. * The following commands are supported for Rivian vehicles: lock/unlock, start/stop charge, and set charge limit. * If a user has multiple Rivian vehicles, they will be prompted to pair each vehicle that they wish to connect to your application. * At least one vehicle must be paired via Bluetooth to complete the pairing process before the user can continue with the Connect flow and connect their Rivian to your application. * If there are multiple drivers associated with a Rivian account and both drivers want to connect to your application, each driver must pair their mobile device to the vehicle via Bluetooth. * There is a limit of four devices that can be paired to a Rivian vehicle at one time. If a user has already paired four devices to their Rivian, they will need to unpair one of the existing devices from the vehicle before they can pair their mobile device and complete the connection to your application. * Smartcar mobile SDKs for iOS and Android are required to pair the vehicle via Bluetooth. # Tesla Virtual Keys Source: https://smartcar.com/docs/connect/other-actions/tesla-virtual-key To support vehicle commands such as lock/unlock or start/stop charge, and benefit from faster data frequencies, Tesla requires a Virtual Key to be added to the vehicle. For more information about Virtual Keys, please visit the [Virtual Key page](/help/oem-integrations/tesla/virtual-key-tesla). ### Vehicle Owners adding a Virtual Key Smartcar Connect will present Tesla vehicle owners a prompt to install the Tesla Virtual Key after granting access and prior to redirecting them back to your application.

When users open the virtual key link, depending on their device, they will be redirected to the Tesla app or prompted to scan a QR code. On mobile devices, they will be redirected to the Tesla app and prompted to add the Virtual Key

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

Virtual Key status can be checked at any time from the Tesla infotainment screen under Settings > Locks.

Smartcar will automatically determine which Tesla vehicles require a Virtual Key and prompt users to add it only for those vehicles. If a user has multiple Tesla vehicles, they will be prompted to add a Virtual Key for each vehicle that requires it. At least one vehicle must complete the pairing process before the user can continue with the Connect flow and connect their Tesla to your application. # Handle the Response Source: 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. ## Success Unique identifier for a vehicle on Smartcar’s platform. ```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](/api-reference/api-errors). The type of error A detailed description of what caused the error ```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 Source: https://smartcar.com/docs/connect/re-auth/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. The [`AUTHENTICATION_FAILED`](/errors/api-errors/connected-services-account-errors#authentication-failed) API error contains a partially constructed re-authentication URL in the `resolution.url` field.
The application’s unique identifier. 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. The first redirect URI you add to your application is automatically set as the default. If you do not specify a `redirect_uri` in your Connect URL, Smartcar will use this default URI. You can add multiple URIs and set any of them as the default in the Smartcar Dashboard. This value must be set to `vehicle_id`. The id of the vehicle you are reauthenticating. 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 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. ```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 ``` # Build the Connect URL Source: https://smartcar.com/docs/connect/redirect-to-connect Learn how to construct the Smartcar Connect URL to redirect users through the vehicle authorization flow. 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). Using our SDKs makes it much easier to generate the Connect URL with the proper parameters. You can configure default permissions for your application in the "Vehicle Access" tab of your application's Configuration page in the [Smartcar Dashboard](https://dashboard.smartcar.com). These settings will determine what permissions are requested during the Connect flow. Any `scope` parameters you specify in the Connect URL will override these dashboard settings. Smartcar Dashboard Configuration Page For Vehicle Access

Smartcar Dashboard Configuration Page For Vehicle Access

Once you have configured your application, you can get a pre-built Connect URL by clicking the "Share Connect Link" button at the top right in the Smartcar Dashboard.

To build the Connect URL manually by overriding your dashboard settings, pass the following parameters: Any parameters you specify in the Connect URL will override your dashboard settings. {/* 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). */} The application’s unique identifier. This is available on the credentials tab of the dashboard 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. The first redirect URI you add to your application is automatically set as the default. If you do not specify a `redirect_uri` in your Connect URL, Smartcar will use this default URI. You can add multiple URIs and set any of them as the default in the Smartcar Dashboard. This value must be set to `code` during the initial authentication. OAuth2 outlines multiple authorization types. Smartcar Connect utilizes the “Authorization Code” flow. To reauthenticate a user after they have already connected a vehicle, you can set this value to the `vehicle_id` of a previously connected vehicle. 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. If you don't specify a `scope` parameter, Smartcar will use the permissions configured in the "Vehicle Access" tab of your application's Configuration page in the Dashboard. Any `scope` parameters passed in the Connect URL will override those dashboard settings. 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 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. 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. Live mode should be used when connecting to a real vehicle. 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. 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. This parameter is only available in the Custom Plan. 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. This parameter is only available in the Custom Plan. A space separated list of feature flags in the form `{flag}:{value}`. 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. 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. ```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 ``` # User Selected Battery Capacity Source: https://smartcar.com/docs/connect/user-selected-batcap This flow can be launched using the URL provided by the [battery capacity](https://smartcar.com/docs/api-reference/get-nominal-capacity) endpoint. ## Append your redirect URI Smartcar will provide a URL with the following parameters from the [GET /battery/nominal\_capacity](/api-reference/get-nominal-capacity) endpoint: ```http https://connect.smartcar.com/battery-capacity ?vehicle_id=36ab27d0-fd9d-4455-823a-ce30af709ffc &client_id=8229df9f-91a0-4ff0-a1ae-a1f38ee24d07 &token=90abecb6-e7ab-4b85-864a-e1c8bf67f2ad &response_type=vehicle_id &redirect_uri= ``` The Smartcar vehicle Id. The `client_id` from the Smartcar Dashboard for your application. Must be set to `vehicle_id`. The URI you would like the response sent to after a user exits the flow. **NOTE:** this is the only parameter that will **not** be prepopulated as part of the API response. You **must** append it in order to launch the flow successfully and receive confirmation the user has exited the flow. A token to validate that the URL was provided from a [battery capacity](/api-reference/get-nominal-capacity) response for your application. The token is valid for 30 days. If a token is not provided or is no longer valid, the user will be directed to re-auth prior to selecting their capacity. ## Response ### Success After the user selects a capacity and hits "Back to Application", Smartcar will send the following to your redirect URI: ```http Success https://example.com/home ?vehicle_id=36ab27d0-fd9d-4455-823a-ce30af709ffc &selected_capacity=80.9 &reason=battery_capacity ``` Upon receiving a success Smartcar will return `selected_capacity` as a parameter or you can hit the GET [/battery/nominal\_capacity](/api-reference/get-nominal-capacity) endpoint to view the selection in the `capacity.nominal` field. ### Error If a user selects "I don't know the battery capacity", Smartcar will send the following to your redirect URI: ```http Error https://example.com/home ?error=battery_capacity_no_selection &error_description=user did not know battery capacity &vehicle_id=36ab27d0-fd9d-4455-823a-ce30af709ffc ``` ## Flow Example

# What is Connect? Source: https://smartcar.com/docs/connect/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

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](/api-reference/authorization/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 Source: https://smartcar.com/docs/errors/api-errors/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 Source: 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 available. # `VEHICLE_LIMIT` You’ve reached the limit of vehicles in your plan. Please upgrade to unlock access to more vehicles. ```json VEHICLE_LIMIT { "type": "BILLING", "code": "VEHICLE_LIMIT", "description": "You’ve reached the limit of vehicles in your plan. Please upgrade to unlock access to more vehicles.", "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 Source: https://smartcar.com/docs/errors/api-errors/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**
`` is not yet able to connect to your car brand.
# `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**
For Tesla vehicles please have the owner re-authenticate using the latest Tesla authorization flow.
# `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**
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.
# `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**
Your car is unable to perform this request.
# Connected Services Account Errors Source: https://smartcar.com/docs/errors/api-errors/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-services-account-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-services-account-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 . Please use this link to re-connect your car: ." } ``` ### 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 \. Please use this link to re-connect your car: \. *** # `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-services-account-errors#no-vehicles", "statusCode": 400, "requestId": "5dea93a1-3f79-4246-90c5-89610a20471b", "resolution": { "type": null }, "suggestedUserMessage": "Your car got disconnected from . Please use this link to re-connect your car: ." } ``` ### 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 \. Please use this link to re-connect your car: \. *** # `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-services-account-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-services-account-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 . 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 \. 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-services-account-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 . 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-services-account-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 Source: https://smartcar.com/docs/errors/api-errors/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 Source: https://smartcar.com/docs/errors/api-errors/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 . 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 \. 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 . 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 \. Please be patient while we’re working to resolve this issue. *** # Resource Not Found Source: 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. # `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 . 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 . 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`). Version 1 has been sunset and is no longer supported. # Server Errors Source: https://smartcar.com/docs/errors/api-errors/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 . 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 \. 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 . 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 \. 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 . 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 \. Please be patient while we’re working to resolve this issue. # Upstream Errors Source: https://smartcar.com/docs/errors/api-errors/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 . 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 \. 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 . 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 \. 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 . 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 \. 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 . 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 \. 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 beta. * 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 . 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 \. Please be patient while we’re working to resolve this issue. *** # Validation Errors Source: https://smartcar.com/docs/errors/api-errors/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 . 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 \. 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 . 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 \. Please be patient while we’re working to resolve this issue. # Vehicle State Errors Source: 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. # `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 \. 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 \ 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 \. 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 \. 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 \. 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 \. 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 \. 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 > \ 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 Source: 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. | 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.

We recommend handling this error by re-prompting the user to authorize their vehicle and adding a message like in the example below.

# Configuration Source: 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. | 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.

# Invalid Subscription Source: 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. | 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.

## 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 Source: 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. | 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.

The user has the option to add vehicles or return to your application. # OEM Login Cancelled Source: 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. | 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 ```

# User returned to application Source: 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. | 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.

# Server Source: https://smartcar.com/docs/errors/connect-errors/server-error 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. ``` 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.

# Vehicle Incompatible Source: https://smartcar.com/docs/errors/connect-errors/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"

We recommend that your application provides a flow for incompatible vehicles like in the example below.

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. 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 | # Testing Errors Source: 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. ## Testing 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](/api-reference/api-errors#connect-errors) page for more details. ## Testing 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 | # Configure Your Application Source: https://smartcar.com/docs/getting-started/configure-application Learn how to configure your Smartcar application, including setting up permissions and redirect URIs. Once you have registered your application in the [Smartcar Dashboard](https://dashboard.smartcar.com), you can configure it to suit your business needs. ## Application Configuration Overview Your application configuration includes several key components: * **Application Name & Description**: A clear name and description help users understand what your application does. * **Redirect URI**: The URL to which users will be redirected after they authorize your application. This must match the redirect URI you use in your OAuth flow. * **Privacy Policy URL**: A link to your application's privacy policy that will be presented to users during the authorization process. * **Vehicle Data**: Select the specific vehicle data signals your application will request access to. This determines the permissions your application will need from users. Application Configuration in Smartcar Dashboard

Application Configuration in Smartcar Dashboard

#### What’s Next? * [Connect your first vehicle](/getting-started/connect-vehicles). * [Build your first integration](/getting-started/integration-overview). # Connect Vehicles Source: https://smartcar.com/docs/getting-started/connect-vehicles Learn how to connect vehicles to your Smartcar application using Smartcar Connect. Smartcar Connect is the starting point for connecting vehicles to your application. It uses Smartcar's patented and secure [OAuth 2.0](https://oauth.net/2/) flow to let vehicle owners grant your app access to their car data and control features. ### Prerequisites Before you begin, make sure you have [configured](/getting-started/configure-application) your Smartcar application in the [Smartcar Dashboard](https://dashboard.smartcar.com/configuration). You will need: * Your application's `Client ID` and `Client Secret` * A valid `redirect_uri` for your application * The vehicle data you want to access (e.g., odometer, location, etc.) Direct your users to the Smartcar Connect URL. This can be done using the Smartcar SDK for your platform (web, iOS, or Android) or copying the URL from the [Smartcar Dashboard](https://dashboard.smartcar.com/configuration). The user will: * Select their vehicle brand * Log in with their connected services account * Review and approve the requested permissions After the user authorizes access, Smartcar will redirect them back to your application using the default `redirect_uri` you provided in your app configuration. The redirect will include an authorization `code` as a query parameter. Your backend exchanges the authorization code for an access token and refresh token by making a request to [Smartcar’s token endpoint](/api-reference/authorization/auth-code-exchange). You’ll need your app’s `client_id`, `client_secret`, and the same `redirect_uri`. ``` POST https://auth.smartcar.com/oauth/token Content-Type: application/x-www-form-urlencoded client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&grant_type=authorization_code&code=AUTH_CODE&redirect_uri=YOUR_REDIRECT_URI ``` The response will include an `access_token` and a `refresh_token`. Store the `access_token` and `refresh_token` securely in your application's database. These tokens are sensitive credentials that allow access to vehicle data and actions, so: * Use encrypted storage or a secrets manager whenever possible. * Never log tokens or expose them in client-side code. * Associate tokens with the correct user and vehicle in your database for easy lookup and management. Here is a [recommended architecture structure](/getting-started/how-to/architecture-design). * The `access_token` expires after two hours. You will need to use the `refresh_token` to obtain new access tokens when needed. The `refresh_token` expires after 60 days. If the `refresh_token` expires, the user will need to reauthorize your application. ## What’s Next * [Build your first integration](/getting-started/integration-overview). * [See more about Smartcar Connect](/connect/what-is-connect) * [Explore available API endpoints](/api-reference) * [Learn about permissions and scopes](/api-reference/permissions) # Connect Insights Source: https://smartcar.com/docs/getting-started/dashboard/connect-insights Connect Insights allows you to visualize your Connect conversion rate and identify where individual users are running into issues during onboarding. ## Conversion Rate For Enterprise customers, the **Conversion Rate** gives you high-level insight into how users are progressing through the Connect Flow over the last two weeks.

## Session Details Clicking into an event in the **Sessions Feed** will pull up more detailed information for that specific user's session, allowing you to see where they dropped off and highlighting issues they may have run into. If you need to dial into a specific time frame or individual user, you can use filters such as Date, VIN, User or Session ID to do so.

# Dashboard Multi-Factor Authentication (MFA) Source: https://smartcar.com/docs/getting-started/dashboard/dashboard-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.

# Dashboard Overview Source: https://smartcar.com/docs/getting-started/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, billing settings, team members, simulated vehicles, and webhooks.

# Vehicle Simulator Source: https://smartcar.com/docs/getting-started/dashboard/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.

## 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: ```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" }) ``` #### 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. # Single Sign-on (SSO) Source: https://smartcar.com/docs/getting-started/dashboard/single-sign-on Smartcar offers SSO through your identity provider (IdP) for Enterprise customers. ## About SSO with Smartcar Our Dashboard supports SSO integrations with popular identity providers including: * Okta * Microsoft Azure AD * Google Workspace * OneLogin * Ping Identity * ADFS * Custom SAML 2.0 providers To set up SSO for your organization's Dashboard accounts, you'll need to: 1. Be an Owner for an existing Team on an Enterprise plan 2. Verify your domain 3. Configure your identity provider The following section will guide you through each step of this process. ## Setting up SSO On Dashboard navigate to **Team settings > Security** and select **Enable SSO**

You’ll be redirected to start the SSO configuration process.

Depending on your DNS provider, you'll receive instructions on how to verify your domain.

Once your domain is verified, you’ll be able to select your Identity Provider (IdP).

You'll be provided a guide on how to get set up based on your IdP.

Once you’ve got everything configured, you’ll be prompted to test SSO.

If you exit the flow at any time before finalizing your configuration, you can jump back in from Dashboard.

## Disabling SSO If you have SSO configured, the Team Owner can disable it from **Team settings > Security**. Disabling SSO will require you to go through the whole setup process again. ## Inviting team members with SSO enabled Once enabled, you’ll need to add members to your team through your identity provider. Invites via the Dashboard will be disabled while SSO is enabled.

When a newly added member has signed in via SSO, they will have the Viewer role by default. Other team members with the appropriate role can promote these members as needed. If a user creates a Dashboard account with their email prior to being added to your IdP, they will be added to their own Team initially. When they are added to your IdP they will be able to switch Teams in Dashboard. ## A note on aliased emails If members of your team have Dashboard accounts using email aliases prior to enabling SSO e.g. [rover+thebest@dog.com](mailto:rover+thebest@dog.com), once SSO is enabled for your Team and they’re added to your IdP, their login will be tied to their non-aliased email address e.g. [rover@dog.com](mailto:rover@dog.com). SSO is only available on the **Enterprise** plan, please reach out to your Account Manager for more details. # Team Settings Source: https://smartcar.com/docs/getting-started/dashboard/teams Your Smartcar Team is the central hub for managing your applications, vehicles, members, security settings, and billing information. Your Smartcar Team allows you to collaborate with other members and manage your applications in one place. ## Members You can add team members to your Smartcar account on any plan for free. Team members can be added to your Smartcar account by navigating to the **Settings** tab in the Dashboard and selecting **Members** under the **Team** section.

## Roles and Permissions Team members can be added on any plan. Specific roles are available on our [Enterprise plan](https://smartcar.com/pricing). |

| Owner

| Admin

| Editor

| Viewer

| | ----------------------------- | ----------------------------------- | ----------------------------------- | ------------------------------------ | ------------------------------------ | | Manage billing | ✅ | | | | | View billing | ✅ | | | | | Delete applications | ✅ | | | | | Modify team settings | ✅ | | | | | Remove team members | ✅ | ✅ | | | | Modify team members | ✅ | ✅ | | | | Create applications | ✅ | ✅ | | | | Modify applications | ✅ | ✅ | ✅ | | | View applications | ✅ | ✅ | ✅ | ✅ | | View team members | ✅ | ✅ | ✅ | ✅ | Editors and Viewers can be limited to specific applications. ## 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. # How to Design Your Backend Architecture for Smartcar Source: https://smartcar.com/docs/getting-started/how-to/architecture-design Learn how to design your backend to integrate your application with Smartcar. Designing your backend architecture for Smartcar integration ensures secure storage of credentials, reliable webhook handling, and a scalable implementation. This guide walks you through the essential database tables and backend endpoints you’ll need. ## What You'll Achieve * Set up database tables to store vehicles, users, and tokens * Create backend endpoints to handle OAuth and webhooks * Understand the data flow between Smartcar and your backend You’ll need tables to track users, vehicles, and Smartcar tokens. Here’s a recommended schema: | Table | Purpose | Key Fields | | ----------------- | ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | `users` | You probably already have this table to store your app's users | `id`, `email`, `name`, etc. | | `smartcar_tokens` | Stores Smartcar access and refresh tokens pairs with user and vehicle IDs | `id`, `your_app_user_id`, `smartcar_vehicle_id`, `smartcar_access_token`, `smartcar_refresh_token`, `expires_at`, `created_at`, `updated_at` | | `vehicles` | Stores connected vehicle information | `id`, `smartcar_user_id`, `your_app_user_id`, `make`, `model`, `year`, `created_at`, `updated_at` | | `vehicle_data` | Stores data about your vehicles (i.e. odometer readings, location, etc.) | `id`, `smartcar_vehicle_id`, `created_at`, `data_type`, `data_value` | | `webhook_logs` | Log incoming webhook events (optional) | `id`, `smartcar_vehicle_id`, `event_type`, `payload`, `received_at` | Always encrypt tokens at rest and never expose them to the client. Create a backend endpoint to handle the OAuth redirect from Smartcar and exchange the authorization code for tokens. **Example: `/api/smartcar/callback`** 1. Receive the `code` and `state` query parameters from Smartcar. 2. Exchange the code for tokens using Smartcar’s token endpoint. 3. Store the tokens in your `tokens` table, linked to the user and vehicle. ```javascript POST https://auth.smartcar.com/oauth/token Content-Type: application/x-www-form-urlencoded client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&grant_type=authorization_code&code=AUTH_CODE&redirect_uri=YOUR_REDIRECT_URI ``` Set up an endpoint to receive webhook POST requests from Smartcar. **Example: `/api/webhooks/smartcar`** * Validate the webhook signature (see [Smartcar webhook docs](/integrations/webhooks)). * Parse the event payload and update your database as needed. * Log the event in `webhook_logs` for auditing and debugging. ```javascript // Example Express.js handler app.post('/api/webhooks/smartcar', async (req, res) => { try { // 1. Validate webhook signature const isValid = await validateWebhookSignature(req); if (!isValid) { return res.status(401).send('Invalid signature'); } // 2. Parse event and update database const event = req.body; await processWebhookEvent(event); // 3. Respond with 200 OK res.status(200).send('Received'); } catch (error) { console.error('Error processing webhook:', error); res.status(500).send('Error processing webhook'); } }); ``` * Restrict access to OAuth and webhook endpoints. * Use HTTPS for all traffic. * Never expose access or refresh tokens to the frontend. *** ## What’s Next * [Set up Smartcar Connect](/getting-started/connect-vehicles) * [Configure your webhook integration](/getting-started/integration-overview) # How to Configure Permissions for Vehicle Data Collection Source: https://smartcar.com/docs/getting-started/how-to/configure-permissions Step-by-step guide to selecting signals, commands, and attributes in the Smartcar Dashboard and requesting the right permissions from vehicle owners. To retrieve vehicle data through Smartcar, you must configure your application to request the correct permissions from vehicle owners. This guide walks you through the process using the Smartcar Dashboard. Go to the [Smartcar Dashboard](https://dashboard.smartcar.com/configuration) and select your application. Navigate to the Configuration section and choose the Vehicle access tab. Under the Signals, Commands, and Attributes tabs, select the specific vehicle data points and actions your application needs. Each selection corresponds to a permission that the vehicle owner must approve. Smartcar Dashboard configuration page showing signal selection and Connect Preview.

Smartcar Dashboard configuration page showing signal selection and Connect Preview.

Signals: Dynamic vehicle data (e.g., battery level, odometer, location).
Commands: Actions your app can perform (e.g., lock/unlock, start charging).
Attributes: Static vehicle info (e.g., make, model, year).

Only select the permissions your application truly needs. This improves user trust and increases the likelihood of successful connections. As you select signals, commands, and attributes, the Connect Preview on the right updates to show what the vehicle owner will see when connecting their vehicle. This preview lists the permissions your app is requesting and the vehicles that will be connected. Once you are satisfied with your selections, click Publish to save your configuration. Your application will now request these permissions from vehicle owners during the Smartcar Connect flow. ## Dynamic Permissions If your application needs to access different permissions based on user actions or vehicle types, you can leverage the `scope` parameter in the Smartcar Connect URL to dynamically request permissions at runtime. This allows you to tailor the permissions based on the specific vehicle or user context. Keep in mind that any permissions you pass via the `scope` parameter will override the permissions configured in the Smartcar Dashboard for that specific connection. ### Notes * If you need to change permissions later, you can return to this configuration page and update your selections. Vehicle owners will need to reauthorize your application to grant any new permissions. * The permissions you select here will determine the data and actions available to your application. Make sure to choose only what is necessary for your use case. *** ## What’s Next * [How to Connect Vehicles](/getting-started/connect-vehicles) * [How to Manage API Tokens](/getting-started/how-to/manage-api-tokens) * [API Reference: Permissions](/api-reference/permissions) # How to Detect and Process Charging Sessions with Webhooks Source: https://smartcar.com/docs/getting-started/how-to/detect-charging-session Learn how to use Smartcar webhooks to detect when a vehicle starts and ends charging, and how to process charging session data. Smartcar webhooks make it easy to detect and process vehicle charging sessions in real time. This guide explains how to configure your webhook, handle charging events, and process charging session data in your backend. In the [Smartcar Dashboard](https://dashboard.smartcar.com/integrations), create or edit a webhook integration. Under Triggers, select the following events:

Charge.IsCharging
Charge.IsChargingCableConnected

These signals will act as triggers for detecting when a vehicle starts and stops charging and when it is plugged in or unplugged. Whenever these signals change, Smartcar will send a webhook event to your configured endpoint. Next, you'll configure your **data**. This is the information you want to receive in your webhook payload every time you receive a webhook event. Triggers are included by default, but you can also add additional signals to the data payload, such as:

Charge.StateOfCharge (included as a trigger)
Charge.ChargingCurrent (included as a trigger)
Charge.ActiveLimit
Charge.Amperage
Charge.Voltage
Charge.Wattage
Charge.EnergyAdded
Charge.TimeToComplete
TractionBattery.Range
TractionBattery.NominalCapacity
Location.PreciseLocation

These data signals will be delivered for every webhook event, allowing you to track the state of charge and other relevant metrics while the vehicle is charging. Next, provide your webhook URL where Smartcar will send the events. Make sure your endpoint is publicly accessible and can handle POST requests. You can choose to auto enroll all your vehicles to this webhook or manually subscribe vehicles later (you can do this from the Dashboard). For this guide, select "don't subscribe any vehicles". Now it is time to save and verify your webhook. Smartcar will send a verification request to your endpoint, which you must respond to with a 200 OK status code to complete the setup (see [Webhook Verification guide](/integrations/webhooks/callback-verification)). Once verified, you will start to receive vehicle data for the vehicles you have subscribed to this webhook. For this guide, we chose not to auto subscribe vehicles, so let's head over to the [Smartcar Dashboard](https://dashboard.smartcar.com/vehicles) to manually subscribe a vehicle to your webhook. Select a vehicle from your list of connected vehicles and click on the three dots action menu to the right of the row and click subscribe. Select your newly created webhook from the options and click subscribe. Smartcar Dashboard showing how to subscribe a vehicle to a webhook.

At this point, your webhook is fully configured to receive charging events from the subscribed vehicle. Now let's handle the incoming webhook events in your backend. Every webhook will include an `eventId` and an `eventType` field. The `eventType` will indicate the type of event that occurred, such as `VEHICLE_STATE` or `VEHICLE_ERROR`. Your handler should gracefully handle both event types. For `VEHICLE_STATE` events, you will receive the updated vehicle data. For `VEHICLE_ERROR` events, you may want to log the error. For `VEHICLE_STATE` events, you will receive the data in a `data` property of the payload. There will also be an array of signals under a `triggers` property that caused the event to be sent. Lastly, you will also receive a `meta` property with additional context about the event, such as the webhook ID, name, delivery ID, delivery timestamp, etc. ### How to track charging sessions When a vehicle starts charging, you will receive a webhook event with the `eventType` of `VEHICLE_STATE` and the `Charge.IsCharging` signal set to `true`. When the vehicle stops charging, you will receive another event with `Charge.IsCharging` set to `false`. You can use these events to track the start and end of each charging session. Example event payload: ```json { "eventId": "a7738a15-7ee2-40b3-9815-823d146230cd", "eventType": "VEHICLE_STATE", "data": { "user": { "id": "deee49b6-d638-4be4-82dc-121ea613eed9" }, "vehicle": { "id": "829e30ab-5a13-40b5-9f8a-8538af86ed95", "make": "Tesla", "model": "Model 3", "year": 2020 }, "signals": [ { "code": "charge-ischarging", "name": "IsCharging", "group": "Charge", "body": { "value": true }, "meta": { "oemUpdatedAt": 1754365413366, "retrievedAt": 1754365413366 } } ], "triggers": [ "Charge.IsCharging" ], "meta": { "webhookId": "f1c2d3e4-5678-90ab-cdef-1234567890ab", "webhookName": "My Charging Webhook", "deliveryId": "b1c2d3e4-5678-90ab-cdef-1234567890ab", "deliveryTimestamp": "2024-08-04T17:00:00Z", "mode": "LIVE", "signalCount": 1 } } } ``` Tip: Always validate the webhook signature to ensure the request is from Smartcar. *** ## What’s Next * [How to Configure Permissions](/getting-started/how-to/configure-permissions) * [How to Manage API Tokens](/getting-started/how-to/manage-api-tokens) * [API Reference: Webhooks](/api-reference/webhooks/subscribe-webhook) # How to Get an API Access Token Source: https://smartcar.com/docs/getting-started/how-to/get-an-access-token Learn how to obtain your first Smartcar API access token by exchanging an authorization code. To make requests to the Smartcar API, you first need to obtain an access token. This guide walks you through the process of getting the authorization code and exchanging it for an access token for the first time. Direct your user to the Smartcar Connect URL. The user will: * Select their vehicle brand * Log in with their connected services account * Approve the requested permissions After successful authorization, Smartcar will redirect the user to your application's `redirect_uri` with an authorization `code` as a query parameter. Your application should listen for requests to the `redirect_uri`. When Smartcar redirects the user, extract the `code` parameter from the query string. Example redirect: ``` https://your-app.com/callback?code=AUTH_CODE&state=STATE ``` Use the authorization code to request an access token and refresh token from [Smartcar’s OAuth token endpoint](/api-reference/authorization/auth-code-exchange). Here is an example using the Smartcar Node.js SDK: ```javascript const smartcar = require('smartcar'); //Smartcar backend Node SDK smartcar.OAuth.getToken({ client_id: 'YOUR_CLIENT_ID', client_secret: 'YOUR_CLIENT_SECRET', grant_type: 'authorization_code', code: 'AUTH_CODE', //extracted from the URL query parameter redirect_uri: 'YOUR_REDIRECT_URI' }); ``` The response will include an `access_token`, an `expires_in` field, and a `refresh_token`. Store these securely in your backend database. The `access_token` expires after two hours, and the `refresh_token` expires after 60 days. *** ## What’s Next * [How to Manage API Tokens](/getting-started/how-to/manage-api-tokens) * [Refreshing API Access Tokens](/api-reference/authorization/refreshing-access-token) # How to Manage API Access Tokens and Refresh Tokens Source: https://smartcar.com/docs/getting-started/how-to/manage-api-tokens Best practices for securely storing, refreshing, and rotating Smartcar API tokens. This guide explains how to store, refresh, and rotate tokens using the Smartcar API. API Access Token vs. Application Management Token

API Access Token: Used to access vehicle data and issue commands on behalf of a vehicle owner. These tokens are obtained through the OAuth flow after a user connects their vehicle and are required for all Smartcar API requests involving vehicle data.
Application Management Token: Used to manage your Smartcar application itself (e.g., configuring webhooks or managing your vehicles). This token is found in the Smartcar Dashboard and is not used for accessing vehicle data or making API requests on behalf of users.

Always use the correct token type for your use case: API access tokens for vehicle data, and management tokens for application configuration. * Store both the `access_token` and `refresh_token` in your backend database, never in client-side code. * Encrypt tokens at rest and restrict access to only necessary backend services. * Associate tokens with the correct user and vehicle for easy lookup and management. * Use the `access_token` as a Bearer token in the `Authorization` header for all API requests. ```javascript GET https://vehicle.api.smartcar.com/v3/vehicles/{vehicleId} Authorization: Bearer ACCESS_TOKEN ``` * If the access token is valid, the API will return the requested data. * If an API request returns a 401 Unauthorized error, the access token may have expired. * In this case, use the refresh token to obtain a new access token. * Make a POST request to the Smartcar OAuth token endpoint with `grant_type=refresh_token`. ```javascript POST https://auth.smartcar.com/oauth/token?client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&grant_type=refresh_token&refresh_token=YOUR_REFRESH_TOKEN Content-Type: application/x-www-form-urlencoded ``` * Store the new `access_token` and `refresh_token` in your database, replacing the old values. * Always update both tokens after a refresh to maintain security. *** ## Additional Resources * [Smartcar API Reference](/api-reference) * [How to Design Your Backend](/getting-started/how-to/architecture-design) # Integrate Your Systems To Receive Data Source: https://smartcar.com/docs/getting-started/integration-overview Welcome to the integration phase of your Smartcar journey! After configuring your application and connecting vehicles, the next crucial step is to integrate your systems with Smartcar to receive vehicle data. ## The architecture that's right for you Webhooks are the recommended way to receive real-time vehicle data from Smartcar. You can still use the REST API for retrieving data and issuing commands, but webhooks are the most scalable and reliable option for most use cases. ## Webhooks [Webhooks](/integrations/webhooks/overview) are the most efficient way to receive real-time vehicle data. Smartcar sends you a payload whenever a vehicle event occurs, such as a change in battery level or location. This allows you to build applications that respond instantly to vehicle changes without polling an API. Get started with Webhooks [here](/integrations/webhooks/overview). ## REST APIs If you prefer to retrieve data on demand, you can use the Smartcar [Vehicles API](/api-reference/vehicles-api-intro). This allows you to query vehicle data at any time, but it may not be as efficient for real-time applications. The Vehicles API provides endpoints for accessing signals, issuing commands, and retrieving vehicle attributes. The Vehicles API is designed primarily for exploration and non-frequent data retrieval. This API is not designed for continuous polling or real-time monitoring. Data is typically updated once every 24 hours unless the vehicle is actively subscribed to a webhook, which enables more frequent updates. For most use cases, you should avoid polling the Vehicles API at high frequency leverage [webhooks](/integrations/webhooks/overview) instead. ## CSVs (coming soon) If you need to process large amounts of historical data, Smartcar can provide vehicle data in CSV format. This is useful for analytics and reporting purposes, allowing you to analyze trends over time. To inquire about CSV data, or if you are interested in a specific integration, please contact our support team at [support@smartcar.com](mailto:support@smartcar.com). # Getting Started with Smartcar Source: https://smartcar.com/docs/getting-started/introduction Welcome to Smartcar's Developer Documentation! Here, you'll learn how to integrate your application with over 40 OEM brands, securely connect to vehicles, and receive the dynamic vehicle data you need, delivered directly to your systems. Learn how to configure your first application and connect a vehicle in under 10 minutes. Solve common implementation challenges with step-by-step instructions. Learn how to use our patented consent management authorization flow, to connect vehicles to your application. Visit our Help Center for FAQs, troubleshooting tips, and to contact support. Dive deep into our Smartcar integrations and learn how to connect with various services. Connect with other developers, share ideas, and get help. Learn how to connect your app to Smartcar so you can access vehicle data like odometer, location, battery level, issue vehicle commands, and more. In this guide, you’ll register your app, walk through the Smartcar Connect flow, and configure a webhook to receive data. By the end of this guide, you’ll have a working setup with access to a vehicle’s data through Smartcar’s platform. ## Prerequisites Before you begin, you’ll need: * A [Smartcar Account](https://dashboard.smartcar.com) * Your Application ID and Secret (found in the [Smartcar Dashboard](https://dashboard.smartcar.com/configuration)) * An application with a redirect URI (e.g. a local development server or staging environment) 1. Log in or sign up via the [Smartcar Dashboard](https://dashboard.smartcar.com) 2. Fill in your app name, description, and redirect URI in the configuration page of the dashboard. 3. Copy your `Client ID` and `Client Secret` in a safe location. These credentials identify your app during the authorization process. **Do not commit your client secret to version control**. 4. Select the data you want to access from vehicles by choosing the data signals (e.g. `odometer`, `location`, etc.). The necessary permissions will be derived from these signals and presented to your users. [Smartcar Connect](/connect) is an OAuth 2.0 consent flow that lets your users link their vehicles securely. The vehicle access tab in the Smartcar Dashboard will generate a Connect URL for you. You can also generate the URL programmatically using one of our SDKs. ```javascript const link = new Smartcar.AuthClient({ //Smartcar frontend SDK clientId: 'YOUR_CLIENT_ID', redirectUri: 'YOUR_REDIRECT_URI', scope: ['read_vehicle_info', 'read_odometer'], // add other scopes as needed mode: 'live', // use 'simulated' for testing with simulated vehicles }); window.location.href = link.getAuthUrl(); ``` This will take your user to the Smartcar Connect screen to authorize access. After the user grants access, Smartcar redirects back to your app with an authorization code. This is where the redirect URI you configured earlier comes into play. Use this code in your backend to exchange for access and refresh tokens: ```javascript const smartcar = require('smartcar'); //Smartcar backend SDK const client = new smartcar.AuthClient({ clientId: 'YOUR_CLIENT_ID', clientSecret: 'YOUR_CLIENT_SECRET', redirectUri: 'YOUR_REDIRECT_URI', mode: 'live', //use 'simulated' for testing with simulated vehicles }); const access = await client.exchangeCode('AUTHORIZATION_CODE_FROM_QUERY'); ``` You’ll receive: * `accessToken`: used to make API calls * `refreshToken`: used to obtain new access tokens Our recommended method is to use webhooks, allowing you to choose triggers (e.g. location changes, battery state of charge changes) and the data to be sent upon those triggers. For lower frequency data needs, you can also use our [REST API](/api-reference/intro) to fetch data at lower intervals (e.g. once a week/month). Once you've configured a webhook, you’ve successfully integrated Smartcar and retrieved vehicle data. #### What’s Next? * [Learn how to configure your application](/getting-started/configure-application). * [Connect your first vehicle](/getting-started/connect-vehicles). * [Build your first integration](/getting-started/integration-overview). Need help? Visit our Support Portal or contact us at [support@smartcar.com](mailto:support@smartcar.com). Let’s get building! # Android Tutorial Source: https://smartcar.com/docs/getting-started/tutorials/android In this tutorial, we will use the Android SDK to integrate Connect into your application. 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. # Overview

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.](/getting-started/tutorials/android#setup) to your application configuration. 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. # Setup 1. Clone our repo and install the required dependencies: ```bash $git clone https://github.com/smartcar/getting-started-android-sdk.git ``` Do not “checkout from version control” with the Getting Started repo in Android Studio, as it will not open the proper module. 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](/getting-started/tutorials/android#handle-the-response) step later on in the tutorial to our backend. ```xml strings.xml sc[yourClientId] [yourClientId] http://10.0.2.2:8000 ``` # 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 } ); } ``` 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. 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

``` # 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. This tutorial configures Connect to launch in `test` mode by default. In `test` mode, any `username` and `password` is valid for each brand. 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(); } ``` 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. # 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. 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`. # Backend SDK Tutorials Source: 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. # Overview

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: ```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 ``` 2. You will also have to set the following environment variables 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. ```bash $export SMARTCAR_CLIENT_ID= $export SMARTCAR_CLIENT_SECRET= $export SMARTCAR_REDIRECT_URI=http://localhost:8000/exchange ``` 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.
# Build your Connect URL 1. Instantiate a `Smartcar` object in the constructor of the App component. ```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', }) ``` Feel free to set `mode` to `simulated` or `live` where you instantiate your `Smartcar` object to connect to a simulated or real vehicle. 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. ```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 ```
# 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`. ```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 ```
# Launching Connect Let’s try authenticating a vehicle! Restart your server, open up your browser and go to `http://localhost:8000/login` ```bash Node $node index.js ``` ```bash Python $python main.py ``` ```bash Java $./gradlew run ``` ```bash Ruby $bundle exec ruby app.rb ```
This tutorial configures Connect to launch in `test` mode by default. In `test` mode, any `username` and `password` is valid for each brand. 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 If you've used one of our frontend SDKs to integrate Connect, this is where you'll need to fetch your access token. 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. ```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 ```
# 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. ```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 ``` 2. Restart your sever and head back to `http://localhost:8000/login` to go through Connect and make your first API request! ```bash Node $node index.js ``` ```bash Python $python main.py ``` ```bash Java $./gradlew run ``` ```bash Ruby $bundle exec ruby app.rb ``` # iOS Tutorial Source: https://smartcar.com/docs/getting-started/tutorials/ios In this tutorial, we will use the iOS SDK to integrate Connect into your application. 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.
# Overview

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 [step 2](/getting-started/tutorials/ios/#setup) below to your application configuration. 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. # 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](/getting-started/tutorials/ios#handle-the-response) step later on in the tutorial to our backend. ```swift Constants.swift struct Constants { static let clientId = ""; static let appServer = "http://localhost:8000"; } ``` # Build your Connect URL Instantiate a `SmartcarAuth` object in the `viewdidLoad` function of the `ViewController`. The iOS application will launch a `WebView` 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 let appDelegate = UIApplication.shared.delegate as! AppDelegate func completionHandler(code: String?, state: String?, virtualKeyUrl: String?, err: AuthorizationError?,) -> Void { // Receive authorization code } appDelegate.smartcar = SmartcarAuth( clientId: "afb0b7d3-807f-4c61-9b04-352e91fe3134", redirectUri: "scafb0b7d3-807f-4c61-9b04-352e91fe3134://exchange", scope: ["read_vin", "read_vehicle_info", "read_odometer"], mode: SCMode.simulated, //use SCMode.live to connect to a real vehicles completionHandler: completionHandler ) let smartcar = appDelegate.smartcar // Generate a Connect URL let authUrl = smartcar.authUrlBuilder().build() // Pass in the generated Connect URL and a UIViewController smartcar.launchAuthFlow(url: authUrl, viewController: viewController) ```
# 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](/getting-started/tutorials/ios#prerequisites) section (i.e. 'sc' + clientId).

# 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. This tutorial configures Connect to launch in `test` mode by default. In `test` mode, any `username` and `password` is valid for each brand. 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} ``` 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. # 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. 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`. # React Tutorial Source: https://smartcar.com/docs/getting-started/tutorials/react In this tutorial, we will use the JavaScript SDK to integrate Connect into your application. 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.
# Overview

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.](/getting-started/tutorials/react#setup) to your application configuration. 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` # 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= $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: 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. # 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, }); } ``` 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 ; } ``` # 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`. You should be reciderect to Smartcar Connect. This tutorial configures Connect to launch in `test` mode by default. In `test` mode, any `username` and `password` is valid for each brand. 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 ? ( ) : ( ); } ``` # 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. 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`. # Testing with Postman Source: https://smartcar.com/docs/getting-started/using-vs-with-postman In this tutorial 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/smartcar-api/collection/qk7g8v2/smartcar-api-v3?action=share\&creator=33621094) * [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/smartcar-api/collection/qk7g8v2/smartcar-api-v3?action=share\&creator=33621094) into your local Postman workspace. Hit Import. 3. Click Link, paste in [the link](https://www.postman.com/smartcar/smartcar-api/collection/qk7g8v2/smartcar-api-v3?action=share\&creator=33621094) to the collection and hit Continue. 4. On the next screen, hit Import.

## 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 ```

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.

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

Select a region and MMY for your vehicle, then hit Search by MMY

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.

Before proceeding to the next step, you’ll want to start the simulation in the Smartcar Dashboard.

## 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. Before hitting Continue, make sure to select a country from the dropdown appropriate to the region you selected for your simulated vehicle.

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:

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.

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). ## Making an API request 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. 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.

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.

Checking `EV Battery Level`, we can see the response matches the vehicle state on the simulator

## Troubleshooting * Check that you’re launching Connect in simulated mode * If you’re still running into an error make sure you’ve selected a country that matches the region you selected for your simulated vehicle. * 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. You can always check the `/permissions` endpoint to see what endpoints you have access to. # Accessing the Smartcar Support Center Source: https://smartcar.com/docs/help/accessing-support-center The Smartcar Support Center provides helpful resources including a knowledge base, ticket submission form, AI chat assistant, and a ticket center to manage your requests. This feature is available on paid plans. You can access the Support Center in two ways: ### Option 1: Visit the Support Center directly Go to [support.smartcar.com](https://support.smartcar.com). You’ll be redirected to the Smartcar Dashboard to log in with your Dashboard credentials. ### Option 2: From the Smartcar Dashboard 1. Log in at [dashboard.smartcar.com](https://dashboard.smartcar.com). 2. Click the **Help** icon in the bottom-left corner, or the **Help Hub** icon in the bottom-right.

3. Select the **Support Center** option to be redirected to the full Support Center.

# Smartcar Usage Limits Source: https://smartcar.com/docs/help/api-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^st 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. # Assist AI features in Slack Source: https://smartcar.com/docs/help/assist-ai-slack As part of our Enterprise Slack support offering, Smartcar includes access on select Enterprise plans to an AI-powered assistant that can help you get answers quickly, submit tickets, and navigate support resources—all without leaving your Slack workspace. ## 1. Ask a Question In your dedicated Slack support channel, send a message with your question. The AI Agent will attempt to answer it based on Smartcar’s support documentation and past support interactions.

## 2. Submit a Support Ticket If your question requires deeper support, simply click **"Create a Ticket"** at the bottom of the AI-generated response within the Slack channel. This will open a form to submit a formal, trackable support request.

## 3. View Open Tickets To check the status of an existing ticket, navigate to the Slack thread where the ticket was created and click the **"View Ticket Info"** icon. This will display the current status and details of your support request.

## 4. Navigate to the Support Center Need more detailed help? You can access your ticket by clicking the **ticket ID** that appears after submitting a request using the **"Create a Ticket"** option. Alternatively, from the **"View Ticket Info"** window, you can click the **ticket number** to be redirected to the Smartcar Developer Dashboard. If you're already logged into an active session, you'll be taken directly to the ticket details within the Support Center. Otherwise, you'll be prompted to log in first. In the Support Center, you can: * Browse our documentation * Submit new support requests * View and update your existing tickets For step-by-step instructions on how to log into the Smartcar Support Center, please see the following article: [Accessing the Smartcar Support Center](/help/accessing-support-center) # Beta Source: https://smartcar.com/docs/help/beta Understand Smartcar's approach to features in beta. Beta is an option that allows developers to test and integrate new Smartcar features before they are fully released. Beta 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 Beta Features Participating in beta 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 features in Beta When working with beta 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 a beta features, contact your Account Manager or our Support team at [support@smartcar.com](mailto:support@smartcar.com) for guidance. # Brand Quirks Source: https://smartcar.com/docs/help/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 Connecting Ford and Lincoln vehicles requires the use of one of our mobile SDKs. We currently offer SDKs for iOS, Android, and Flutter. Smartcar's Connect SDKs will redirect to Ford’s site to handle the authentication process when the user logs in. **Authentication via non-mobile platforms such as web browsers is not supported at this time**. See [Connect SDKs](/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 ### 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 Source: 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. | 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. \$10/month thereafter. | | Nissan | US | NissanConnect Services | - Convenience - Select (EV data) | Free trial varies with model year. $9.99 - $ 21.98/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 (excluding Solterra) | US | MySubaru | STARLINK Security Plus | 6-month free trial. \$4.95/month thereafter. | | Subaru Solterra | US | Solterra Connect | Remote Connect | One-year trial included, \$8/month after trial. | | 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 Source: https://smartcar.com/docs/help/compatibility # Connect your car Source: https://smartcar.com/docs/help/connect-your-car # Diagnostic Systems Source: https://smartcar.com/docs/help/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 | # Frequently Asked Questions (FAQs) Source: https://smartcar.com/docs/help/faqs Below you'll find answers to some of the most frequently asked questions about Smartcar. 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. 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). 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! [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. 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. For a list of compatible vehicles, visit [our website](https://smartcar.com/product/compatible-vehicles/). Smartcar is compatible with **161 million vehicles** across the US, Canada and Europe. **United States**
Smartcar is compatible with **29 car brands** in the United States. **Europe**
Smartcar is compatible with **19 car brands** in Europe. **Canada**
Smartcar is compatible with **21 car brands** in Canada. **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. 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/). 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. # Submit a Feature Request Source: https://smartcar.com/docs/help/feature-request ## Help Us Improve Smartcar! Your feedback shapes our future. Have an idea or improvement you’d love to see? Submit your suggestions using the form below, and let us know how we can better serve your needs. If you have trouble seeing the form below, please visit [this link](https://smartcarapi.notion.site/215f1477e9d380538219cb34866b8540?pvs=105) to submit your feature request.