| | ----------------------------- | ----------------------------- | ----------------------------- | ----------------------------- | | Audi | Hyundai | Mercedes-Benz | Skoda | | BMW | Jaguar | MINI | Vauxhall | | Citroen | Kia | Opel | Volkswagen | | DS | Land Rover | Peugeot | Volvo | | Ford | Mazda | Renault | | # July 2024 Releases ## July 31, 2024 Connect Insights is now available!

* Each Connect flow launched for the previous two weeks is available in the Smartcar Dashboard with a variety of ways to search for specific Connect launches. * Enterprise customers have access to funnel analysis so they can understand their conversion rates in the Connect flow. ## July 30, 2024 Test and Simulated mode have been combined into a singular mode; Simulated. If a simulated vehicle is enabled, we will return data following the selected trip. If the simulated vehicle doesn't support the requested endpoint, randomized data will be returned. If no simulated vehicle is enabled for, we will return data as if a simulated vehicle with "Day Commute" was selected. If the simuday commute doesn't support the requested endpoint, randomized data will be returned. ## July 25, 2024 The Smartcar Dashboard now supports Google authentication. ## July 3, 2024 The following endpoints are now available for Tesla: * [Get User Info](/api-reference/tesla/get-user-info) * [Get User access](/api-reference/tesla/get-user-access) # June 2024 Releases ## June 24, 2024

You can now customize which bands show up in Connect from the [Dashboard](https://dashboard.smartcar.com/). Easily manage which brands your users can connect to based on engine type or endpoint. ## June 20, 2024 The following Brand Specific Endpoint is now available for Audi: * [Get Charge Status](/api-reference/audi/get-charge) ## June 5, 2024 The following endpoints are now available for Audi: * [Get Charge Limit](/api-reference/evs/get-charge-limit) * [Set Charge Limit](/api-reference/evs/set-charge-limit) * [Control Charge](/api-reference/evs/control-charge) * [Lock Status](/api-reference/get-lock-status) # March 2024 Releases ## March 6, 2024

Organization access for Teams is now available on Dashboard. Check out our docs page on [Teams](/help/teams) for details. ### Additional Releases The following endpoint is now available for Tesla vehicles globally: * [Virtual Key Status](/api-reference/tesla/get-virtual-key-status) # May 2024 Releases ## May 10, 2024 The following endpoint is now available for Ford, Lincoln, Toyota, Lexus, Mazda and Volkswagen (US) vehicles: * [GET /service/history](/api-reference/get-service-records) ## May 8, 2024 The following make specific endpoint is now available for Tesla across all supported regions: * [GET /tesla/alerts](/api-reference/tesla/get-alerts) # October 2024 Releases ## October 8, 2024 The Smartcar Dashboard now indicates which vehicles are subscribed to webhooks through the main Vehicles table. ## October 10, 2024 The Smartcar Dashboard now indicates which webhooks a vehicle is subscribed to. From the Vehicles table, click into the three dot menu to view vehicle details. From here, navigate to the new Webhooks tab! # September 2024 Releases ## September 25, 2024 [Dynamic Webhooks](/getting-started/tutorials/webhooks-dynamic) are now in early access for Enterprise customers! Please request access from the Webhooks tab on the Smartcar Dashboard! ## September 30, 2024 [Multi-Factor Authentication](/getting-started/dashboard-mfa) is available to offer an additional layer of security for the Smartcar Dashboard. # Latest Releases ## November 1, 2024 A new [System Status](https://smartcar.com/docs/api-reference/get-system-status) endpoint is available for early access. This endpoint returns a list of vehicle components and their health state for FCA and GM makes. ## November 5, 2024 Ford's authentication process has been updated to require the use of SDKs. Our [Connect SDKs](https://smartcar.com/docs/connect/connect-sdks) have been updated to redirect to Ford's site to handle the authentication process when the user logs in. # Country Selection By default Connect will launch based on the devices location impacting the brands that are available to the user e.g. Renault is only available in Europe. You can override this behaviour by passing a country feature flag in your Connect URL in the form `country:{country_code}`. Your feature flag should contain the [two-character ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the country that your user is located in. Our SDKs provide ways for you to add this as part of the 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 Connect can be launched with three different workflows. Depending on your use case and what information you have about the vehicle ahead of a launching Connect, you may be able to leverage one of these flows for a more streamlined Connect experience. 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=true` 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 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 login in with a real connected services account. | | simulated | Launches Connect in simulated mode allowing developer to connect to vehicles created on Dashboard via the Simulator. | # Auth Code Exchange To interact with the Smartcar API, you will need to exchange your authorization code for an access token. The authorization code represents a user’s consent, but cannot be used to make requests to a vehicle. Instead, it must be exchanged for an access token. An example request is provided to the right. # SDKs for Connect Our SDKs make integrating Smartcar fast and easy in different languages and frameworks. For mobile or single page web apps, you can use one of our frontend SDKs. Please note that our frontend SDKs only handle integrating Connect into your application. You will still need to use a backend SDK to manage tokens and make API requests to vehicles. 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 ## 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 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 Upon successfully accepting the permissions, Smartcar will redirect the user back to your application using the specified `REDIRECT_URI`, along with an authorization code as a query parameter. In the case of on error, we'll provide an error and description as parameters instead. ## Success 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](/errors/overview). 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. # Handle the Response If the re-auth is successful, the redirect to your application will contain a vehicle ID. In the case of an error, we'll provide an error and description as parameters instead. ## Success 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](/errors/overview). 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 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`]() 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. 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 Construct the Smartcar Connect redirect with the parameters below. Launching this link will send users through the Smartcar Connect 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). Alternatively, you can build the Connect URL manually.
{/* 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 This value must be set to `code`. OAuth2 outlines multiple authorization types. Smartcar Connect utilizes the “Authorization Code” flow. A space-separated list of permissions that your application is requesting access to. The valid permission names can be found in the permissions section. A permission is optional by default. It can be made required by adding the required: prefix to the permission name, e.g. required:read\_odometer. Please refer to the integration guide in our docs for more information. 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. 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. 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. Disable remembering a user's authorization on subsequent login sessions. This feature is enabled by default and can only be disabled (by setting the parameter to false) in simulated mode. 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 ``` # Overview After fetching your first token pair, you'll need to manage them in order to maintain access to the vehicle. ## Storing access tokens ### Default and Brand Select Connect Flow By default tokens are scoped to the user's connceted services account. This means that if there are multiple vehicles on the account - and they are selected at the time of authorization, the access token is valid for all those vehicle Ids. To manage this, we recommend using the [Smartcar User Id](/api-reference/management/user) to link tokens to your corresponding user id. The diagram below will also allow multiple users to connect to vehicles on the same account.

### Single Select Connect Flow When using the Single Select flow, tokens are strictly scoped to the vehicle that was authorized for that Connect session. This means that if a user connects multiple vehicles under the same connected services account, each vehicle id will be tied to its own set of tokens.

## Token expiry Access tokens are valid for 2 hours, while refresh tokens are valid for 60 days. You can use the corresponding refresh token to fetch a new token pair once an access token has expired. In order to maintain access to a vehicle without having a user go through Connect again, you'll want to make sure the refresh token never expires. Whenever you fetch a new token pair, we will return a **new access and refresh token**. Prior to expiry, access tokens will remain valid until their expiry when fetching a new token pair. Refresh tokens on the other hand are invalidated 1 minute after they're used. To avoid common 401 Authentication errors, please ensure you are **persisting both the access and refresh token** we return whenever you fetch a new pair. In addition to any logic that checks access token expiry when making an API request, we strongly recommend having another job that periodically checks for refresh tokens that are close to expiry and refreshes them. # Refreshing Refresh Tokens Refresh tokens expire after **60 days ordinarily** or **after 1 minute when used to fetch a new token pair**. Depending on your application logic, there may be cases where you don't end up fetching a fresh access token for more than 60 days. If this is the case, you should fetch a new token pair before the 60 days are up so the user doesn’t need to go through Connect again. This will give you a newly minted access token **and** refresh token. # Refreshing Access Tokens Your access token will expire **2 hours** after it is issued. When this happens, your application can retrieve a new one by using the corresponding `REFRESH_TOKEN`. # 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](/connect/auth-code-exchange) for an access token to start making requests to their vehicle(s). We have designed Connect in compliance with the OAuth2 authorization protocol, safely handling all user information. Connect comes with robust configurations to fit your needs and frontend [SDKs](/connect/connect-sdks) for faster integration. # Authentication Errors Thrown when there is an issue with your authorization header. # `NULL` The authorization header is missing or malformed, or it contains invalid or expired authentication credentials (e.g. access token, client ID, client secret). Please check for missing parameters, spelling and casing mistakes, and other syntax issues. ```json { "type": "AUTHENTICATION", "code": null, "description": "The authorization header is missing or malformed, or it contains invalid or expired authentication credentials. Please check for missing parameters, spelling and casing mistakes, and other syntax issues.", "docURL": "https://smartcar.com/docs/errors/api-errors/authentication-errors", "statusCode": 401, "requestId": "5dea93a1-3f79-4246-90c5-89610a20471b", "resolution": { "type": null } } ``` ### Suggested Resolution You can resolve this error by referring to our API reference and ensuring that you pass all the parameters as specified. If you are certain that your request is well-formed, please try refreshing your access token. ### Troubleshooting Steps Refer to our API reference and ensure that you use the correct authentication mechanism for your request * Check constants like Bearer and Basic for spelling mistakes. * If you make a request to a vehicle endpoint, verify that your access token grants you access to the correct vehicle. You can do so by making a request to the /vehicles endpoint and ensuring that the correct vehicle ID is included in the returned response. * If you have refreshed your access token, make sure that it persists and that you use your new token to make your request. # Billing Errors Thrown when limits have been reached based on your plan, or if the feature is not avaible. # `VEHICLE_LIMIT` You have exceeded your active vehicle limit for the current billing period. Please log in to the [Smartcar dashboard](https://dashboard.smartcar.com/login) and visit the Billing tab to learn more. ```json VEHICLE_LIMIT { "type": "BILLING", "code": "VEHICLE_LIMIT", "description": "You have exceeded your active vehicle limit for the current billing period. Please log into the Smartcar dashboard and visit the Billing tab to learn more.", "docURL": "https://smartcar.com/docs/errors/api-errors/billing-errors#vehicle-limit", "statusCode": 430, "requestId": "5dea93a1-3f79-4246-90c5-89610a20471b", "resolution": { "type": "CONTACT_SUPPORT" }, } ``` ### Troubleshooting Steps To resolve this error, please [contact us](mailto:support@smartcar.com) to upgrade your plan and increase your vehicle limit. Please note that you won’t be able to make requests to additional vehicles until the end of the current billing period or until you have upgraded your plan. # `INVALID_PLAN` The feature you are trying to use is not included in your current pricing plan. Please visit our pricing page to learn more about our plans and features. ```json INVALID_PLAN { "type": "BILLING", "code": "INVALID_PLAN", "description": "The feature you are trying to use is not included in your current pricing plan. Please visit our pricing page to learn more about our plans and features.", "docURL": "https://smartcar.com/docs/errors/api-errors/billing-errors#invalid-plan", "statusCode": 430, "requestId": "5dea93a1-3f79-4246-90c5-89610a20471b", "resolution": { "type": "CONTACT_SUPPORT" } } ``` ### Troubleshooting Steps If you have checked our pricing page and believe that the feature you are trying to use is included in your plan, please [contact us](mailto:support@smartcar.com) and we’ll be happy to assist you. # `VEHICLE_REQUEST_LIMIT` You have exceeded the number of API requests that are allowed for **this** vehicle in the current billing period. Please log in to the [Smartcar dashboard](https://dashboard.smartcar.com/login) and visit the Billing tab to learn more. ```json VEHICLE_REQUEST_LIMIT { "type": "BILLING", "code": "VEHICLE_REQUEST_LIMIT", "description": "You have exceeded the number of API requests that are allowed for this vehicle in the current billing period. Please log into the Smartcar dashboard and visit the Billing tab to learn more.", "docURL": "https://smartcar.com/docs/errors/api-errors/billing-errors#vehicle-request-limit", "statusCode": 430, "requestId": "5dea93a1-3f79-4246-90c5-89610a20471b", "resolution": { "type": "CONTACT_SUPPORT" } } ``` ### Troubleshooting Steps To resolve this error, please [contact us](mailto:support@smartcar.com) to upgrade your plan and increase your vehicle limit. Please note that you won’t be able to make additional requests to this vehicle until the end of the current billing period or until you have upgraded your plan. # `ACCOUNT_SUSPENDED` Your Smartcar account is past due and has been suspended. Please reach out to our finance team to resolve this issue. ```json ACCOUNT_SUSPENDED { "type": "BILLING", "code": "ACCOUNT_SUSPENDED", "description": "Your Smartcar account is past due and has been suspended. Please reach out to our finance team to resolve this issue.", "docURL": "https://smartcar.com/docs/errors/api-errors/billing-errors#account-suspended", "statusCode": 430, "requestId": "5dea93a1-3f79-4246-90c5-89610a20882a", "resolution": { "type": "FINANCE" } } ``` ### Troubleshooting Steps To resolve this error, please [contact us](mailto:finance@smartcar.com) to pay past due invoices. Please note that you won’t be able to make any requests until you have resolved this issue. # Compatibility Errors Thrown when Smartcar does not support a make, or feature for a vehicle. # `MAKE_NOT_COMPATIBLE` Smartcar is not yet compatible with this vehicle’s make in the country you specified. ```json { "type": "COMPATIBILITY", "code": "MAKE_NOT_COMPATIBLE", "description": "Smartcar is not yet compatible with this vehicle’s make in the country you specified.", "docURL": "https://smartcar.com/docs/errors/api-errors/compatibility-errors#make-not-compatible", "statusCode": 501, "requestId": "5dea93a1-3f79-4246-90c5-89610a20471b", "resolution": { "type": null } } ``` **Suggested User Messaging**
`` 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 Thrown when there are issues with the user's connected service account. # `ACCOUNT_ISSUE` Action needed in the user’s connected services account. The user needs to log in and complete an outstanding task in their connected services account. Examples: * The user needs to accept the connected services app’s Terms of Service. * The user has created but not yet fully activated their connected services account. * If you've received this error while testing with Vehicle Simulator, it likely means a simulation has not been started for the vehicle. Visit the Simulator tab in the Smartcar Dashboard to start a simulation for the vehicle. ```json { "type": "CONNECTED_SERVICES_ACCOUNT", "code": "ACCOUNT_ISSUE", "description": "Action needed in the user’s connected services account. Please prompt the user to log into their connected services account and complete any outstanding tasks.", "docURL": "https://smartcar.com/docs/errors/api-errors/connected-service-errors#account-issue", "statusCode": 400, "requestId": "5dea93a1-3f79-4246-90c5-89610a20471b", "resolution": { "type": null }, "suggestedUserMessage": "Action required in your connected services account. Please log into your connected services app or web portal and complete any outstanding tasks (e.g. finish activating your account or accept the Terms of Service)." } ``` ### Suggested resolution The user can resolve this error by logging into their connected services account and completing any outstanding tasks. ### Troubleshooting steps * Prompt the user to log into their connected services account using the app or web portal. * Prompt the user to try triggering an action on their car, e.g. locking the doors or flashing the lights. * At this point, the app should prompt the user to complete their outstanding task. ### Suggested user message > Action required in your connected services account. Please log into your connected services app or web portal and complete any outstanding tasks (e.g. finish activating your account or accept the Terms of Service). *** # `AUTHENTICATION_FAILED` Smartcar was unable to authenticate with the user’s connected services account. This error usually occurs when the user has updated their connected services account credentials and not yet re-authenticated in Smartcar Connect. The user should re-authenticate using Smartcar Connect. ```json { "type": "CONNECTED_SERVICES_ACCOUNT", "code": "AUTHENTICATION_FAILED", "description": "Smartcar was unable to authenticate with the user’s connected services account. Please prompt the user to re-authenticate using Smartcar Connect.", "docURL": "https://smartcar.com/docs/errors/api-errors/connected-service-errors#authentication-failed", "statusCode": 400, "requestId": "5dea93a1-3f79-4246-90c5-89610a20471b", "resolution": { "type": "REAUTHENTICATE", "url": "https://connect.smartcar.com/oauth/reauthenticate?response_type=vehicle_id&client_id=8229df9f-91a0-4ff0-a1ae-a1f38ee24d07&vehicle_id=sc4a1b01e5-0497-417c-a30e-6df6ba33ba46", } "suggestedUserMessage": "Your car got disconnected from . 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-service-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-service-errors#permission", "statusCode": 400, "requestId": "5dea93a1-3f79-4246-90c5-89610a20471b", "resolution": { "type" : "REAUTHENTICATE" } } ``` ### Suggested resolution For Tesla Owners: * Prompt the vehicle owner to go through the Connect flow again or use our [reauthentication flow](/help/oem-integrations/tesla/developers#stand-alone-flow) to streamline the process. *** # `SUBSCRIPTION` The vehicle’s connected services subscription is inactive or does not support the requested API endpoint. ```json { "type": "CONNECTED_SERVICES_ACCOUNT", "code": "SUBSCRIPTION", "description": "The vehicle’s connected services subscription is inactive or does not support the requested API endpoint.", "docURL": "https://smartcar.com/docs/errors/api-errors/connected-service-errors#subscription", "statusCode": 400, "requestId": "5dea93a1-3f79-4246-90c5-89610a20471b", "resolution": { "type": null }, "suggestedUserMessage": "Your car’s connected services subscription has either expired or it doesn’t support the necessary features to connect to . 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-service-errors#vehicle-missing", "statusCode": 400, "requestId": "5dea93a1-3f79-4246-90c5-89610a20471b", "resolution": { "type": null }, "suggestedUserMessage": "Your car’s connected services subscription has either expired or it doesn’t support the necessary features to connect to . Please activate your subscription or contact us to upgrade your subscription." } ``` ### Suggested resolution The user can resolve this issue by logging into their connected services account and either re-adding the vehicle or re-activating its subscription. If the user wishes to disconnect their vehicle from your app, please make a request to our Disconnect endpoint and refrain from making API requests to this vehicle in the future. ### Troubleshooting Steps * Prompt the user to log into their connected services account using the app or web portal. * Prompt the user to check whether the vehicle is listed under their account. * If the vehicle is not listed, prompt the user to add the vehicle to their account. * If the vehicle is listed, prompt the user to activate the vehicle’s connected services subscription. ### Suggested user message > This car is no longer associated with your connected services account. Please log into your account and re-add this car. *** # `VIRTUAL_KEY_REQUIRED` The vehicle owner has granted your application access to the vehicle through Smartcar. However, additional steps are needed on the owners part in order to perform this specific request. ```json { "type": "CONNECTED_SERVICES_ACCOUNT", "code": "VIRTUAL_KEY_REQUIRED", "description": "The vehicle owner needs to grant additional access to Smartcar in order to perform this request.", "docURL": "https://smartcar.com/docs/errors/api-errors/connected-service-errors#virtual-key-required", "statusCode": 400, "requestId": "5dea93a1-3f79-4246-90c5-89610a20471b", "resolution": { "type" : "ACTION_REQUIRED", "url" : "https://www.tesla.com/_ak/smartcar.com" } "suggestedUserMessage": "In order to perform this request you’ll need to add a Third-Party Virtual key to your vehicle. Please open this link on the phone with your Tesla App to complete this step." } ``` ### Suggested resolution For Tesla Owners: * The vehicle owner needs to add Smartcar’s Third-Party Virtual Key. As of late 2023, Tesla is starting to require virtual keys for Third-Party applications to perform commands. * In order to issue commands, please prompt the vehicle owner to add Smartcar’s Third-Party virtual key: [https://www.tesla.com/\_ak/smartcar.com](https://www.tesla.com/_ak/smartcar.com) ### Troubleshooting steps * Please direct the vehicle owner to add Smartcar’s [Third-Party Virtual Key (tesla.com)](https://www.tesla.com/_ak/smartcar.com) in order to allow your application to issue commands to the vehicle. ### Suggested user message > In order to perform this request you’ll need to add a Third-Party Virtual key to your vehicle. Please open [this](https://www.tesla.com/_ak/smartcar.com) link on the phone with your Tesla App to complete this step. # Permission Errors Thrown when Smartcar does not support a make or feature for a vehicle. # `NULL` Your application has insufficient permissions to access the requested resource. Please prompt the user to re-authenticate using Smartcar Connect. If you receive this error while testing with Vehicle Simulator, it is likely because the simulated vehicle has not yet been connected to your application, or your application doesn't have access to the requested permission. Visit the Simulator documentation to learn how to connect the vehicle to your application. ```json { "type": "PERMISSION", "code": null, "description": "Your application has insufficient permissions to access the requested resource. Please prompt the user to re-authenticate using Smartcar Connect.", "docURL": "https://smartcar.com/docs/errors/api-errors/permission-errors#null", "statusCode": 403, "requestId": "5dea93a1-3f79-4246-90c5-89610a20471b", "resolution": { "type": "REAUTHENTICATE" } } ``` ### Suggested Resolution You can resolve this error by ensuring that the scope parameter contains all the permissions that your application requires and prompting the user to re-authenticate using Smartcar Connect. ### Troubleshooting Steps * Ensure that the scope parameter contains all the permissions that your application requires. * Ensure that you spell all permission names in the scope parameter correctly. * Prompt the user to re-authenticate using Smartcar Connect. # Rate Limit Errors Thrown when there is an issue with the frequency of your requests. # `SMARTCAR_API` Your application has exceeded its rate limit. Please retry your request in a few minutes. ```json { "type": "RATE_LIMIT", "code": "SMARTCAR_API", "description": "Your application has exceeded its rate limit. Please retry your request in a few minutes.", "docURL": "https://smartcar.com/docs/errors/api-errors/rate-limit-errors#smartcar-api", "statusCode": 429, "requestId": "5dea93a1-3f79-4246-90c5-89610a20471b", "resolution": { "type": "RETRY_LATER" }, "suggestedUserMessage": "Your vehicle is temporarily unable to connect to . 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 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](https://api.smartcar.com/v2.0/vehicles)). Version 1 has been sunset and is no longer supported. # Server Errors Thrown when Smartcar runs into an unexpected issue and was unable to process the request. # `INTERNAL` An internal Smartcar error has occurred. Our team has been notified and is working to resolve this issue. ```json { "type": "SERVER", "code": "INTERNAL", "description": "An internal Smartcar error has occurred. Our team has been notified and is working to resolve this issue.", "docURL": "https://smartcar.com/docs/errors/api-errors/server-errors#internal", "statusCode": 500, "requestId": "5dea93a1-3f79-4246-90c5-89610a20471b", "resolution": { "type": "RETRY_LATER" }, "suggestedUserMessage": "Your car is temporarily unable to connect to . 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 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 Early Access. * This error does not occur very frequently. * This is the first time we have received this error. ```json { "type": "UPSTREAM", "code": "UNKNOWN_ISSUE", "description": "Smartcar received an unknown error from an upstream source. Please retry your request at a later time and contact us if the issue persists.", "docURL": "https://smartcar.com/docs/errors/api-errors/upstream-errors#unknown-issue", "statusCode": 502, "requestId": "5dea93a1-3f79-4246-90c5-89610a20471b", "resolution": { "type": "RETRY_LATER" }, "suggestedUserMessage": "Your car is temporarily unable to connect to . 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 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 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 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 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 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 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 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 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 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 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 | # Overview A comprehensive breakout of all Smartcar errors. # Connect Errors Connect errors are returned as a parameter in the redirect from Connect. ### Access Denied |

Code | | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | | This error occurs when a user denies your application access to the requested scope of permissions. | [access\_denied](/errors/connect-errors/access-denied) | ### Invalid Subscription |

Code | | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | | This error occurs when the user has encountered an Error page in Connect and has chosen to return to your application. | [configuration\_error](/errors/connect-errors/configuration-error) | ### No Vehicles |

Code | | ------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- | | This error occurs when a vehicle owner has a connected services account, but there are no vehicles associated with the account. | [no\_vehicles](/errors/connect-errors/no-vehicles) | ### Vehicle Incompatible |

Code | | --------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | | This error occurs when a user tries to authorize an incompatible vehicle in Smartcar Connect. | [vehicle\_incompatible](/errors/connect-errors/vehicle-incompatible) | ### Server Error |

Code | | --------------------------------------------------------------------- | ---------------------------------------------------- | | If there is a server error, the user will return to your application. | [server\_error](/errors/connect-errors/server-error) |
# API Errors API errors are returned from requests made via Smartcar API. ### Authentication |

Code | | -------------------------------------------------------------- | ----------------------------------------------------- | | Thrown when there is an issue with your authorization headers. | [NULL](/errors/api-errors/authentication-errors#null) | ### Billing |

Code | | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Thrown when limits have been reached based on your plan or if the feature is not available. | [INVALID\_PLAN](/errors/api-errors/billing-errors#invalid-plan)

[VEHICLE\_LIMIT](/errors/api-errors/billing-errors#vehicle-limit)

[VEHICLE\_REQUEST\_LIMIT](/errors/api-errors/billing-errors#vehicle-request-limit)

[ACCOUNT\_SUSPENDED](/errors/api-errors/billing-errors#account-suspended) | ### Compatibility |

Code | | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Thrown when Smartcar does not support a make or feature for a vehicle. | [MAKE\_NOT\_COMPATIBLE](/errors/api-errors/compatibility-errors#make-not-compatible)

[SMARTCAR\_NOT\_CAPABLE](/errors/api-errors/compatibility-errors#smartcar-not-capable)

[VEHICLE\_NOT\_CAPABLE](/errors/api-errors/compatibility-errors#vehicle-not-capable) | ### Connected Services Account |

Code | | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Thrown when there are issues with the user's connected service account. | [ACCOUNT\_ISSUE](/errors/api-errors/connected-service-errors#account_issue)

[AUTHENTICATION\_FAILED](/errors/api-errors/connected-service-errors#authentication-failed)

[NO\_VEHICLES](/errors/api-errors/connected-service-errors#no-vehicles)

[SUBSCRIPTION](/errors/api-errors/connected-service-errors#subscription)

[VEHICLE\_MISSING](/errors/api-errors/connected-service-errors#vehicle-missing) | ### Permission |

Code | | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | | Thrown when you make a requests to an endpoint associated with permissions not yet granted to your application. | [NULL](/errors/api-errors/permission-errors#null) | ### Rate Limit |

Code | | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- | | Thrown when there is an issue with the frequency of your requests. | [SMARTCAR\_API](/errors/api-errors/rate-limit-errors#smartcar-api)

[VEHICLE](/errors/api-errors/rate-limit-errors#vehicle) | ### Resource Not Found |

Code | | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | Thrown if the requested path does not exist. | [PATH](/errors/api-errors/resource-errors#path)

[VERSION](/errors/api-errors/resource-errors#version)

| ### Server |

Code | | ----------------------------------------------------------------------------------------- | ----------------------------------------------------- | | Thrown when Smartcar runs into an unexpected issue and was unable to process the request. | [INTERNAL](/errors/api-errors/server-errors#internal) | ### Upstream |

Code | | ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Thrown when the OEM or vehicle failed to process the request. | [INVALID\_DATA](/errors/api-errors/upstream-errors#invalid-data)

[KNOWN\_ISSUE](/errors/api-errors/upstream-errors#known-issue)

[NO\_RESPONSE](/errors/api-errors/upstream-errors#no-response)

[RATE\_LIMIT](/errors/api-errors/upstream-errors#rate-limit)

[UNKNOWN\_ISSUE](/errors/api-errors/upstream-errors#unknown-issue) | ### Validation |

Code | | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | Thrown if there is an issue with the format of the request or body. | [NULL](/errors/api-errors/validation-errors#null)

[PARAMETER](/errors/api-errors/validation-errors#parameter) | ### Vehicle State |

Code | | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Thrown when a request fails due to the state of a vehicle or logically cannot be completed e.g. you can't start a vehicle charging if it's not plugged in. | [ASLEEP](/errors/api-errors/vehicle-state-errors#asleep)

[CHARGING\_IN\_PROGRESS](/errors/api-errors/vehicle-state-errors#charging-in-progress)

[CHARGING\_PLUG\_NOT\_CONNECTED](/errors/api-errors/vehicle-state-errors#charging-plug-not-connected)

[DOOR\_OPEN](/errors/api-errors/vehicle-state-errors#door-open)

[FULLY\_CHARGED](/errors/api-errors/vehicle-state-errors#fully-charged)

[NOT\_CHARGING](/errors/api-errors/vehicle-state-errors#not-charging)

[CHARGE\_FAULT](/errors/api-errors/vehicle-state-errors#charge-fault)

[HOOD\_OPEN](/errors/api-errors/vehicle-state-errors#hood-open)

[IGNITION\_ON](/errors/api-errors/vehicle-state-errors#ignition-on)

[IN\_MOTION](/errors/api-errors/vehicle-state-errors#in-motion)

[REMOTE\_ACCESS\_DISABLED](/errors/api-errors/vehicle-state-errors#remote-access-disabled)

[TRUNK\_OPEN](/errors/api-errors/vehicle-state-errors#trunk-open)

[UNKNOWN](/errors/api-errors/vehicle-state-errors#unknown)

[UNREACHABLE](/errors/api-errors/vehicle-state-errors#unreachable)

[VEHICLE\_OFFLINE\_FOR\_SERVICE](/errors/api-errors/vehicle-state-errors#vehicle-offline-for-service) | # Testing Errors By launching Connect in [simulated mode](/docs/connect/advanced-config/modes), you're able to test your application against certain errors. ## Connect Errors You can use the following emails to test a subset of Connect errors: | Error | Email | VIN | | ---------------------- | ----------------------------------------------------------------------------- | ----------------- | | `invalid_subscription` | [smartcar@invalid-subscription.com](mailto:smartcar@invalid-subscription.com) | 0SCAUDI0155C49A95 | | `vehicle_incompatible` | [smartcar@vehicle-incompatible.com](mailto:smartcar@vehicle-incompatible.com) | 0SCAUDI012FE3B132 | Visit the [Connect Errors](/errors/overview#connect-errors) page for more details. ## API Errors You can use use the following emails to test these API error types: * `COMPATIBILITY` * `CONNECTED_SERVICES_ACCOUNT` * `UPSTREAM` * `VEHICLE_STATE` | Type | Code | Email | VIN | | ---------------------------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | | `COMPATIBILITY` | `MAKE_NOT_COMPATIBLE` | [COMPATIBILITY.MAKE\_NOT\_COMPATIBLE@smartcar.com](mailto:COMPATIBILITY.MAKE_NOT_COMPATIBLE@smartcar.com) | 0SCLR000270BE6600 | | `COMPATIBILITY` | `SMARTCAR_NOT_CAPABLE` | [COMPATIBILITY.SMARTCAR\_NOT\_CAPABLE@smartcar.com](mailto:COMPATIBILITY.SMARTCAR_NOT_CAPABLE@smartcar.com) | 0SCLR0002DC18F57F | | `COMPATIBILITY` | `VEHICLE_NOT_CAPABLE` | [COMPATIBILITY.VEHICLE\_NOT\_CAPABLE@smartcar.com](mailto:COMPATIBILITY.VEHICLE_NOT_CAPABLE@smartcar.com) | 0SCLR00024C7CDF7A | | `CONNECTED_SERVICES_ACCOUNT` | `ACCOUNT_ISSUE` | [CONNECTED\_SERVICES\_ACCOUNT.ACCOUNT\_ISSUE@smartcar.com](mailto:CONNECTED_SERVICES_ACCOUNT.ACCOUNT_ISSUE@smartcar.com) | 0SCLR00026BAAA136 | | `CONNECTED_SERVICES_ACCOUNT` | `AUTHENTICATION_FAILED` | [CONNECTED\_SERVICES\_ACCOUNT.AUTHENTICATION\_FAILED@smartcar.com](mailto:CONNECTED_SERVICES_ACCOUNT.AUTHENTICATION_FAILED@smartcar.com) | 0SCLR00021D803C7B | | `CONNECTED_SERVICES_ACCOUNT` | `NO_VEHICLES` | [CONNECTED\_SERVICES\_ACCOUNT.NO\_VEHICLES@smartcar.com](mailto:CONNECTED_SERVICES_ACCOUNT.NO_VEHICLES@smartcar.com) | 0SCLR00027671837B | | `CONNECTED_SERVICES_ACCOUNT` | `SUBSCRIPTION` | [CONNECTED\_SERVICES\_ACCOUNT.SUBSCRIPTION@smartcar.com](mailto:CONNECTED_SERVICES_ACCOUNT.SUBSCRIPTION@smartcar.com) | 0SCLR0002B9BAF29F | | `CONNECTED_SERVICES_ACCOUNT` | `VEHICLE_MISSING` | [CONNECTED\_SERVICES\_ACCOUNT.VEHICLE\_MISSING@smartcar.com](mailto:CONNECTED_SERVICES_ACCOUNT.VEHICLE_MISSING@smartcar.com) | 0SCLR00024E29EEBD | | `UPSTREAM` | `INVALID_DATA` | [UPSTREAM.INVALID\_DATA@smartcar.com](mailto:UPSTREAM.INVALID_DATA@smartcar.com) | 0SCLR000298A0A649 | | `UPSTREAM` | `KNOWN_ISSUE` | [UPSTREAM.KNOWN\_ISSUE@smartcar.com](mailto:UPSTREAM.KNOWN_ISSUE@smartcar.com) | 0SCLR0002A8760B72 | | `UPSTREAM` | `NO_RESPONSE` | [UPSTREAM.NO\_RESPONSE@smartcar.com](mailto:UPSTREAM.NO_RESPONSE@smartcar.com) | 0SCLR0002C23E43AB | | `UPSTREAM` | `UNKNOWN_ISSUE` | [UPSTREAM.UNKNOWN\_ISSUE@smartcar.com](mailto:UPSTREAM.UNKNOWN_ISSUE@smartcar.com) | 0SCLR0002D4878901 | | `VEHICLE_STATE` | `ASLEEP` | [VEHICLE\_STATE.ASLEEP@smartcar.com](mailto:VEHICLE_STATE.ASLEEP@smartcar.com) | 0SCLR0002E8896323 | | `VEHICLE_STATE` | `CHARGING_IN_PROGRESS` | [VEHICLE\_STATE.CHARGING\_IN\_PROGRESS@smartcar.com](mailto:VEHICLE_STATE.CHARGING_IN_PROGRESS@smartcar.com) | 0SCLR000221F1E672 | | `VEHICLE_STATE` | `CHARGING_PLUG_NOT_CONNECTED` | [VEHICLE\_STATE.CHARGING\_PLUG\_NOT\_CONNECTED@smartcar.com](mailto:VEHICLE_STATE.CHARGING_PLUG_NOT_CONNECTED@smartcar.com) | 0SCLR0002CBFC7C21 | | `VEHICLE_STATE` | `DOOR_OPEN` | [VEHICLE\_STATE.DOOR\_OPEN@smartcar.com](mailto:VEHICLE_STATE.DOOR_OPEN@smartcar.com) | 0SCLR0002F8BD90B8 | | `VEHICLE_STATE` | `FULLY_CHARGED` | [VEHICLE\_STATE.FULLY\_CHARGED@smartcar.com](mailto:VEHICLE_STATE.FULLY_CHARGED@smartcar.com) | 0SCLR00029CD9D894 | | `VEHICLE_STATE` | `HOOD_OPEN` | [VEHICLE\_STATE.HOOD\_OPEN@smartcar.com](mailto:VEHICLE_STATE.HOOD_OPEN@smartcar.com) | 0SCLR000219CD4A2C | | `VEHICLE_STATE` | `IGNITION_ON` | [VEHICLE\_STATE.IGNITION\_ON@smartcar.com](mailto:VEHICLE_STATE.IGNITION_ON@smartcar.com) | 0SCLR00021D49E58A | | `VEHICLE_STATE` | `IN_MOTION` | [VEHICLE\_STATE.IN\_MOTION@smartcar.com](mailto:VEHICLE_STATE.IN_MOTION@smartcar.com) | 0SCLR00024F6EE640 | | `VEHICLE_STATE` | `REMOTE_ACCESS_DISABLED` | [VEHICLE\_STATE.REMOTE\_ACCESS\_DISABLED@smartcar.com](mailto:VEHICLE_STATE.REMOTE_ACCESS_DISABLED@smartcar.com) | 0SCLR0002588A5CC1 | | `VEHICLE_STATE` | `TRUNK_OPEN` | [VEHICLE\_STATE.TRUNK\_OPEN@smartcar.com](mailto:VEHICLE_STATE.TRUNK_OPEN@smartcar.com) | 0SCLR00023C607FDB | | `VEHICLE_STATE` | `UNKNOWN` | [VEHICLE\_STATE.UNKNOWN@smartcar.com](mailto:VEHICLE_STATE.UNKNOWN@smartcar.com) | 0SCLR0002E6CC0314 | | `VEHICLE_STATE` | `UNREACHABLE` | [VEHICLE\_STATE.UNREACHABLE@smartcar.com](mailto:VEHICLE_STATE.UNREACHABLE@smartcar.com) | 0SCLR000247EBF067 | | `VEHICLE_STATE` | `VEHICLE_OFFLINE_FOR_SERVICE` | [VEHICLE\_STATE.VEHICLE\_OFFLINE\_FOR\_SERVICE@smartcar.com](mailto:VEHICLE_STATE.VEHICLE_OFFLINE_FOR_SERVICE@smartcar.com) | 0SCLR0002AF1D71A1 | # Dashboard Configurations ## Configuring Connect From the dashboard, you can specify which brands you'd like to present to your customers and in which order. This changes apply only when launching Connect in [default mode](/connect/advanced-config/flows).

# Dashboard Multi-Factor Authentication (MFA) ## Configuring Multi-Factor Authentication From the settings gear, you can access User Security, which supports Multi-Factor Authentication (MFA). Enable MFA and scan with your preferred authenticator app such as Google Authenticator or 1Password. Once enabled, each following login will require the use of your authenticator app to provide a unique code for login. MFA can be disabled for your user at any time, though the authenticator app will be required to disable MFA.

# Dashboard Overview All you need to know about the Smartcar Dashboard You can sign up for a Smartcar account [here](https://dashboard.smartcar.com/signup). The Smartcar Dashboard allows you to manage your application configurations, connected vehicles and billing settings. As well as invite team members, create simulated vehicles and set up webhooks.

# Vehicle Simulator Before launching your integration, we recommend using Smartcar’s Vehicle Simulator to test your application on a simulated vehicle. With the Simulator, you can choose the vehicle's region, make, model and year as well as the vehicle state to test with. Watch your simulated vehicle travel in real-time from the Smartcar Dashboard as you test API requests from your application with realistic vehicle data responses.

## 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. # Charging Station Utilization This guide explains how to use the Smartcar API to enhance charging station discoverability by leveraging vehicle data such as state of charge, battery level, range, and location. These capabilities allow developers to help EV drivers find nearby charging stations based on real-time vehicle data. ## Prerequisites: Creating your application Before implementing the Smartcar API for charging station discoverability, ensure you have: * Created a Smartcar Account and registered your application to obtain your `client_id` and `client_secret`. * Set up Smartcar Connect Flow to authenticate and authorize users. For more details, refer to the [Getting Started Guide](/getting-started/introduction). ## Smartcar API Endpoints for charging station discoverability Use the following Smartcar API endpoints to help drivers locate nearby charging stations based on their vehicle’s current range and location. ### 1. Determine EV Range Once a vehicle is authorized via Smartcar’s Connect flow, you can use the vehicle’s access token to retrieve the current battery level and range through the [GET /battery](/api-reference/evs/get-battery-level) endpoint. ```curl Range Remaining and SoC GET /vehicles/{vehicle_id}/battery ``` ```json Example Response { "percentRemaining": 0.3, "range": 40.5 } ``` ### 2. Retrieve Vehicle Location To locate nearby charging stations based on the vehicle’s current location, use the [GET /location](/api-reference/get-location) endpoint. ```curl Location GET /vehicles/{vehicle_id}/location ``` ```json Example Response { "latitude": 37.4292, "longitude": -122.1381 } ``` ### 3. Calculate Distance to Charging Stations Once you have the vehicle's location, compare it with nearby charging stations’ coordinates. Charging station locations can be sourced from a Charge Point Operator (CPO) or through third-party services such as Google’s Places API. Calculate the distance and estimated time to reach these stations using Google’s Distance Matrix API or a similar service. * Sourcing Charging Station Data: While Smartcar provides vehicle location data, you’ll need to source station coordinates from a CPO database or third-party API like Google’s Places API. * Distance Calculation: Use Google’s Distance Matrix API to compute the travel distance and time, factoring in real-time traffic conditions and travel modes. This process helps drivers locate the nearest available charging stations in real time, offering a smooth and integrated experience. This process helps drivers locate the nearest available charging stations in real time, offering a smooth and integrated experience. ### 4. Send Destination to Vehicle Navigation (Optional) Once you’ve identified the nearest charging station, guide the driver to the location. Depending on the vehicle’s capabilities, there are two options for navigation: 1. **Mobile Navigation Apps**: For vehicles that don’t support in-dash navigation, dispatch the destination coordinates to a mobile app (e.g., Google Maps, Apple Maps). This ensures drivers can still navigate using their smartphone.. 2. **Send to in-dash navigation**: For vehicles that support in-dash navigation, Smartcar allows you to send destination coordinates directly to the onboard system. This allows for seamless, in-vehicle routing. You can check which brands support this feature by visiting the Supported Brands section. Use [Send Destination](/api-reference/send-destination-to-vehicle) for supported vehicles to send coordinates to the vehicle's navigation. ```curl Send Destination POST /vehicles/navigation/destination { "latitude": 37.4292, "longitude": -122.1381 } ``` ## FAQs Scheduled polling is recommended for passive monitoring of vehicle data. For real-time use cases, such as finding the nearest charging station based on current range and location, sending requests on-demand is more efficient. To locate nearby charging stations, you will need external data sources to locate nearby charging stations. This data can be sourced from Charge Point Operators (CPOs) or third-party services like Google’s Places API. You may also use public databases such as the National Renewable Energy Laboratory (NREL) API for detailed information on charging station availability and locations. You may also wish to use Google’s Distance Matrix API to help calculate drive distance and time based on real-time traffic conditions. Yes, Smartcar’s API enables integration with any charging station network by providing vehicle data through our platform. # Plan Your Integration There are 3 main steps to integrate Smartcar into your application to make API requests to vehicles: 1. Launch Connect to get consent from the vehicle owner 2. Fetch an access token 3. Make a request to the vehicle ## The architecture that's right for you [Smartcar Connect](/connect/what-is-connect) is Smartcar’s [OAuth 2.0](https://oauth.net/2/) authorization flow. It is your users’ first and only touchpoint with Smartcar. After a user enters the Smartcar Connect flow and authorizes their vehicle(s), your application is able to make requests to the Smartcar API. Those requests allow your application to retrieve information and send commands to the user’s vehicle(s), such as reading the odometer and unlocking the doors. Depending on your web or mobile application architecture, you can implement the Smartcar Connect flow in different ways.

Using the Smartcar iOS SDK or the Smartcar Android SDK, your application launches Smartcar Connect in a browser view. The user logs in with the username and password of their vehicle’s connected services account and grants your application access to their vehicle. The browser view gets redirected to a special custom-scheme `REDIRECT_URI`. For more details on how to configure a custom-scheme `REDIRECT_URI`, see our API reference. Once the user has completed the Smartcar Connect flow, the completion handler in the iOS or Android SDK is invoked with the authorization code. Your mobile application sends the authorization `code` to its back-end service. In order to exchange the authorization `code` for an `ACCESS_TOKEN`, your application makes a request to the Smartcar API. This request must contain the authorization code along with your application’s `CLIENT_ID` and `CLIENT_SECRET`. In response, Smartcar returns an `ACCESS_TOKEN` and a `REFRESH_TOKEN`. These should be stored in your application’s database. Using the `ACCESS_TOKEN`, your application can now make API requests to the user’s vehicle.

Using the [Smartcar JavaScript SDK](https://github.com/smartcar/javascript-sdk), your application launches Smartcar Connect in a pop-up window. The user logs in with the username and password of their vehicle’s connected services account and grants your application access to their vehicle. If you are interested in building a web application that uses Node for API access, check out our [starter applications on Github](https://github.com/smartcar/starter-app-react-node). The user’s browser gets redirected to a special Smartcar-hosted `REDIRECT_URI`. For more details on how to configure a Smartcar-hosted `REDIRECT_URI`, see our [API reference](/api-reference). Once the user has completed the Smartcar Connect flow, the `onComplete` callback in the JavaScript SDK is invoked with the authorization `code`. Your application front end sends the authorization `code` to its back-end service. In order to exchange the authorization `code` for an `ACCESS_TOKEN`, your application makes a request to the Smartcar API. This request must contain the authorization code along with your application’s `CLIENT_ID` and `CLIENT_SECRET`. In response, Smartcar returns an `ACCESS_TOKEN` and a `REFRESH_TOKEN`. These should be stored in your application’s database. Using the `ACCESS_TOKEN`, your application can now make API requests to the user’s vehicle.

You can use your preferred language framework for a server-side setup as long as you use [OAuth2 Retrieval protocol](https://oauth.net/2/). In this case: 1. Your application redirects the user’s browser to Smartcar Connect. 2. The user logs in with the username and password of their vehicle’s connected services account. 3. The user grants your application access to their vehicle. The Smartcar Connect flow is now complete and the user’s browser gets redirected to a specified `REDIRECT_URI`. Your application’s server, which is listening at the `REDIRECT_URI`, retrieves the authorization `code` from query parameters in the `REDIRECT_URI`. In order to exchange the authorization `code` for an `ACCESS_TOKEN`, your application makes a request to the Smartcar API. This request must contain the authorization `code` along with your application’s `CLIENT_ID` and `CLIENT_SECRET`. In response, Smartcar returns an `ACCESS_TOKEN` and a `REFRESH_TOKEN`. These should be stored in your application’s database. Using the `ACCESS_TOKEN`, your application can now make API requests to the user’s vehicle. ## Let's get building Now you have an idea of how Smartcar works, take a look at one of our Getting Started guides in the tutorials section to get connected to a vehicle. {/*

*/} {/* ## 2. Adapt Smartcar Connect to your use case ### Fit Smartcar Connect into the user journey To increase conversions and maximize your users’ satisfaction, it is crucial to launch Smartcar Connect at the right moment in your product’s user journey. We recommend prompting the user to connect their car through Smartcar Connect while they are onboarding their vehicle to your application for the first time. ### Standard: Let the user connect one or more vehicles In the standard Smartcar Connect flow, the user selects their car brand and logs in with the username and password of their vehicle’s connected services account. On the next screen, the user can see all vehicles associated with their account. The user can select one or multiple of these vehicles and grant your application access to them. We recommend using the standard Smartcar Connect flow whenever you don’t yet know the make or VIN of your user’s vehicle(s). If you know the make or VIN of your user’s vehicle(s), we recommend personalizing the Smartcar Connect flow in the following ways: ### Optional: Skip the car brand selection screen If you know the make of your user’s vehicle(s) prior to launching Smartcar Connect, we recommend using [Brand Select](https://smartcar.com/docs/api#brand-select). Brand Select causes the user to automatically skip the car brand selection screen. Instead, the user lands directly on their vehicle brand’s login screen. This speeds up the onboarding experience and increases conversions.

### Optional: Check a vehicle’s eligibility before launching Smartcar Connect If you know the VIN of your user’s vehicle prior to launching Smartcar Connect, we recommend using the [Compatibility API](/api-reference). The Compatibility API lets you verify a vehicle’s eligibility before sending a user through Smartcar Connect. That way, your application will show Smartcar Connect to users with compatible vehicles only. The Compatibility API is only available for vehicles sold in the United States. ### Optional: Make sure the user connects the right vehicle If you know the VIN of your user’s vehicle prior to launching Smartcar Connect, we recommend using [Single Select](https://smartcar.com/docs/api#single-select). Single Select causes the user to skip the car brand selection screen. It also limits them to connecting only the vehicle with that specific VIN, even if the user has registered multiple vehicles under the same connected services account. This simplifies the user experience and guarantees that the user connects the right vehicle to your application.

## 3. Set optional and/or required permissions When [redirecting a user to Smartcar Connect](https://smartcar.com/docs/api#smartcar-connect), you need to include a `scope` parameter that indicates which permissions your application requests access to. Every vehicle endpoint has a permission name associated with it. For example, the permission name for the [/fuel endpoint](/api-reference/EVs/EV-charging-limit) is `read_fuel`. Please see our [API reference](/api-reference) for a full list of all permission names. ### Optional permissions Not all vehicles are capable of all permissions. For example, Tesla vehicles aren’t capable of the `read_fuel` permission, because they don’t have fuel tanks. In order to handle this smoothly, all permissions that your application requests access to in Smartcar Connect are optional by default. For example, let’s assume that your app requests access to the `read_location` and the `read_fuel` permissions. A user connects their Tesla vehicle through Smartcar Connect. The user is able to successfully authorize their vehicle, because both, the `read_location` and the `read_fuel` permission are optional. In the background, your application is granted permission to the `read_location` endpoint only, because the vehicle is incapable of the read_fuel permission. In order to verify which permissions your application was granted access to, make a request to the [/permissions endpoint](/api-reference/vehicles/revoke-access): ```java Node const permissions = await vehicle.permissions(); console.log(permissions); ``` ```python Python response = vehicle.permissions() print(response) ``` ```java Java ApplicationPermissions response = vehicle.permissions(); System.out.println(response); ``` ```ruby Ruby response = vehicle.permissions puts response.permissions ``` ### Required permissions If certain permissions are essential to your application’s use case, you can make them required by adding the `required`: prefix to each pertaining permission within the `scope` parameter (e.g. `required:read_fuel`). The user is then able to authorize a vehicle only if the vehicle is capable of all required permissions. For example, let’s assume that you mark both `read_location` and `read_fuel` as required in the scope parameter. A user tries to connect their Tesla vehicle through Smartcar Connect. As Tesla vehicles are incapable of the read_fuel permission, the user isn’t able to successfully authorize their vehicle. Instead, Smartcar sends the vehicle_incompatible error back to your application. ```java Node const client = new smartcar.AuthClient({ clientId: CLIENT_ID, clientSecret: CLIENT_SECRET, redirectUri: REDIRECT_URI, }); const scope = ["required:read_location", "required:read_fuel"]; const authUrl = client.getAuthUrl(scope); ``` ```python Python client = smartcar.AuthClient( client_id=CLIENT_ID, client_secret=CLIENT_SECRET, redirect_uri=REDIRECT_URI, ) scope = ['required:read_location', 'required:read_fuel'] auth_url = client.get_auth_url(scope=scope) ``` ```java Java AuthClient authClient = new AuthClient.Builder() .clientId(CLIENT_ID) .clientSecret(CLIENT_SECRET) .redirectUri(REDIRECT_URI) .build(); String[] scope = new String[]{"required:read_location", "required:read_fuel"}; String authUrl = authClient.authUrlBuilder(scope).build(); ``` ```ruby Ruby client = Smartcar::AuthClient.new({ client_id: CLIENT_ID, client_secret: CLIENT_SECRET, redirect_uri: REDIRECT_URI, }) scope = %w(required:read_location required:read_fuel) auth_url = client.get_auth_url(scope) ``` */} # Introduction to Smartcar's API Learn about how to build applications that connect to millions of vehicles around the world.

Smartcar is the only car API built with the highest standard for privacy and security. We allow your application to communicate with millions of vehicles easily and securely while giving vehicle owners the choice of how they share their data. Below are a few concepts to help you get familiar with Smartcar's API. Let’s get building! ## What you need before you get started Before making requests to a vehicle, the owner must grant your application permission to access their data. To request permission from the vehicle owner, you must present the Smartcar Connect flow to the user. To launch Smartcar Connect, you need to: Register an application and get your `CLIENT_ID` and `CLIENT_SECRET`. Set a `REDIRECT_URI` to the path where Smartcar will redirect your users after they grant permission to your app. You can get these from the [Smartcar Dashboard](https://dashboard.smartcar.com/). With your `CLIENT_ID` and `REDIRECT_URI` you can launch [Connect](/connect). This is how you and your users can add vehicles to your application. Once users authorize your app to access their vehicles, you receive a `code` that you can exchange for an `ACCESS_TOKEN` and `REFRESH_TOKEN`. Make sure to store these tokens in a secure place (like your application's database). You need the access token to make requests to the Smartcar API. More information can be found in our [Token Management Overview](https://smartcar.com/docs/connect/token-management/overview). # Test Your Integration Before launching your integration, use Smartcar’s simulated mode to quickly test your application. If you prefer to control the vehicle type and receive consistent data in API responses, consider using Smartcar’s [Vehicle Simulator](/getting-started/dashboard/simulator) If you are not testing with a simulated vehicle, Simulated mode will randomized data for every API request. ## Test successful API requests ### 1. Enabling simulated mode When launching Smartcar Connect, pass in the query parameter `mode=simulated` to enable simulated mode. Smartcar’s SDKs provide a convenient option to facilitate this: ```node Node const client = new smartcar.AuthClient({ clientId: CLIENT_ID, clientSecret: CLIENT_SECRET, redirectUri: REDIRECT_URI, mode: 'simulated', }); ``` ```python Python client = smartcar.AuthClient( client_id=CLIENT_ID, client_secret=CLIENT_SECRET, redirect_uri=REDIRECT_URI, mode='simulated' ) ``` ```java Java AuthClient authClient = new AuthClient.Builder() .clientId(CLIENT_ID) .clientSecret(CLIENT_SECRET) .redirectUri(REDIRECT_URI) .mode("simulated") .build(); ``` ```ruby Ruby client = Smartcar::AuthClient.new({ client_id: CLIENT_ID, client_secret: CLIENT_SECRET, redirect_uri: REDIRECT_URI, mode: 'simulated' }) ``` ### 2. Log into a simulated connected services account User your simulated vehicle credentials to log in, or select any vehicle brand and log in with any email address `(anything@anything.com)` and any password. ### 3. Send an API request to the simulated vehicle Our API will return simulated data for each endpoint the simulated vehicle is able to provide, or randomized data for each other endpoint. For example, a simulated Tesla will return battery capacity consistently, but will return randomized data if fuel level is requested. See our API reference to learn more about the randomized data you should expect. If you use Single Select, use the below VIN and make a request as follows. | Email | VIN | | --------------------------------- | ----------------- | | `smartcar@successful-request.com` | 0SCAUDI037A5ADB1C | ```node Node const scope = ["read_vehicle_info"] const options = singleSelect: {vin: '0SCAUDI037A5ADB1C'} authUrl = client.getAuthUrl(scope, options); ``` ```python Python scope = ['read_vehicle_info'] options = { single_select={'vin': '0SCAUDI037A5ADB1C'} } auth_url = client.get_auth_url(scope, options) ``` ```java Java String authUrl = authClient.authUrlBuilder() .singleSelect(true) .singleSelectVin("0SCAUDI037A5ADB1C") .build(); ``` ```ruby Ruby scope = %w(read_vehicle_info) options = { "singleSelect": { vin: "0SCAUDI037A5ADB1C" } } auth_url = client.get_auth_url(scope, options) ``` ## Test successful API requests with specific VINs If you need a test vehicle with a specific VIN, you can still use simulated mode. When logging into a test mode connected services account (step 2 above), follow this format for the email address: `@.smartcar.com` **VIN**: This can be any 17-character alphanumeric string. Note: This string does not need to be a real VIN. Smartcar does not perform any VIN-specific validations. **Compatibility level**: This string determines which permissions the test mode vehicle is capable of. The following table contains all valid compatibility levels and their corresponding permissions: | Compatibility level | Permissions | | ------------------- | ---------------------------------------------------- | | compatible OR phev | All permissions | | incompatible | No permissions | | fuel | Permissions that apply to a gasoline vehicle | | bev | Permissions that apply to a battery-electric vehicle | To use Single Select in test mode with a specific VIN, follow step 3 above and replace the Smartcar-provided VIN with the VIN of your choice. Then follow the email format `@.smartcar.com` using the same VIN. ## Test with multiple vehicles In some cases, you may want to test the Connect flow with an account that has more vehicles than our default test accounts to help ensure your application is paginating and fetching data for a large number of vehicles correctly. You can do this with the following email format in Test mode and any password: `-vehicles@smartcar.com` Number: Any number from 1-999. Smartcar will show this many vehicles on the permission grant screen and return this many vehicles from the /vehicles endpoint, with pagination. # Android Tutorial In this tutorial, we will use the Android SDK to integrate Connect into your application. 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.](/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](/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 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 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 [Setup step 2](/tutorials/ios#setup) 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](/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 1. Instantiate a `SmartcarAuth` object in the `viewdidLoad` function of the `ViewController`. {/* Smartcar TODO: testMode: true --> mode: "test" and remove the Info box when the SDK gets updated!!! - Travis J.*/} ```swift ViewController.swift {/* TODO: Authorization Step 1: Initialize the SmartcarAuth object */} appDelegate.smartcar = SmartcarAuth( clientId: Constants.clientId, redirectUri: "sc\(Constants.clientId)://exchange", testMode: true, scope: ["required:read_vehicle_info"], completion: completion ) ``` The iOS SDK does not support `simulated` mode at this time - only `test` and `live`. Feel free to set `testMode: false` where you instantiate your `SmartcarAuth` object to connect to a real vehicle. 2. The iOS application will launch a `SafariView` with Connect to request access to a user’s vehicle. On Connect, the user logs in with the username and password for their vehicle’s connected services account and grants the application access to their vehicle. To launch Connect, we can use the `launchAuthFlow` function that our `SmartcarAuth` object has access to. We can place this within the `connectPressed` action function. ```swift ViewController.swift @IBAction func connectPressed(_ sender: UIButton) { {/* TODO: Authorization Step 2: Launch Connect */} let smartcar = appDelegate.smartcar! smartcar.launchAuthFlow(viewController: self) } ```
# Registering your Custom Scheme Once a user has authorized the application to access their vehicle, the user is redirected to the `REDIRECT_URI` with an authorization code as a query parameter. iOS applications use custom URI schemes to intercept calls and launch the relevant application. This is defined within the `Info.plist`. 1. Open up `Info.plist` and click on the grey arrow next to **URL types**. 2. Next, click on the grey arrow next to the `Item 0` dictionary and `URL Schemes` array. 3. Finally, set your `Item 0` string to the redirect URI you set up in the [Prerequisites](/tutorials/ios#prerequisites) section (i.e. 'sc' + clientId).

# 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 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.](/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](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`. # Dynamic Webhooks (Early Access) Dynamic webhooks make it incredibly easy to receive data from a vehicle at the optimal frequency supported by the OEM. Specifically, once a certain condition is met, you will be able to receive data more frequently from the vehicle to stay up-to-date with the state of the vehicle when it matters most to you. ## Prerequisites For this tutorial it is recommended to have the following in place: * To receive webhooks you’ll need to set up a callback URI on your server. * To [**subscribe**](https://smartcar.com/docs/api-reference/webhooks/subscribe-webhook) a vehicle you’ll want to have [**Connect**](https://smartcar.com/docs/connect/dashboard-config) integrated into your application. ## Setting up a Dynamic Webhook Navigate to **Webhooks** from the Smartcar Dashboard, select **+ Add webhook** and select **Dynamic** from the Webhooks config wizard.

Name your webhook and specify a `callback URI`. Your `callback URI` is where Smartcar will send payloads from vehicles connected to your webhook. Click **Next**.

Confirm everything looks good and hit **Add**.

Currently Dynamic Webhooks only support returning data from the [location](/api-reference/get-location), [charge](/api-reference/evs/get-charge-status), and [battery](/api-reference/evs/get-battery-level) endpoints. Changes in data frequency are only supported based on the plugged in state for EVs. After adding your webhook, you’ll need to verify your callback URI. This is to ensure Smartcar is sending data to the correct place!

Please see our API reference on how to [verify a webhook](/api-reference/webhooks/callback-verification), or **Part II** on [this blog post](https://smartcar.com/blog/how-to-use-scheduled-webhooks#-part-ii-verify-webhook) for a more in depth guide. ## Subscribing vehicles to a webhook Now you’ve got your webhook set up, you can subscribe vehicles to start getting data. If you haven’t done so already, please set up [Connect](http://localhost:3000/connect/dashboard-config) for your application. After going through Connect and receiving your initial `access_token`, you’ll first want to hit the [All Vehicles](/api-reference/all-vehicles) endpoint to fetch the Smartcar `vehicle_ids` of the authorized vehicles.
With your `access_token` and `webhook_id` you can hit the [Subscribe](/api-reference/webhooks/subscribe-webhook) endpoint for each `vehicle_id` to start receiving data.
## Example payload ```json dynamicWebhook.json { "version": "2.0", "webhookId": "865ca68d-a9b6-4d74-856e-605db0209eca", "eventName": "dynamic", "mode": "live", "payload": { "vehicles": [ { "vehicleId": "00000000-0000-4000-A000-000000000000", "requestId": "25d743b8-14cf-4744-b067-bd8d7daf3f1a", "data": [ { "path": "/battery", "code": 200, "body": { "range": 283.244544, "percentRemaining": 0.58 }, "headers": { "sc-data-age": "2024-09-20T21:58:06.000Z" } }, { "path": "/charge", "code": 200, "body": { "isPluggedIn": false, "state": "NOT_CHARGING" }, "headers": { "sc-data-age": "2024-09-20T21:58:06.000Z" } }, { "path": "/location", "code": 200, "body": { "latitude": 37.4292, "longitude": 122.1381, }, "headers": { "sc-data-age": "2024-09-20T21:58:48.000Z" } } ] } ] } } ``` ## FAQs By default Smartcar will deliver data every hour from the time a vehicle is subscribed. From that point on, once we detect the relevant state changes we'll increase this to every 30 minutes, dropping back down to hourly once the state returns to what it was. Where more frequent data delivery is supported by an OEM, Smartcar will deliver data at those speeds. Please reach out to your Solutions Architect for more information. Yes! You can distinguish between webhook types based on the `eventName` field. Dynamic Webhooks will have `eventName` set to `dynamic`. Smartcar will attempt to resend payloads with an exponential backoff. Once your server is back online you'll continue to receive data from the vehicles. * Once a webhook is configured and a vehicle is subscrbied, we’ll begin sending data to your Callback URI. We’ll expect a 2xx response to each. In the event that we don’t receive a 2xx response, we’ll retry 6 times with exponential backoff. **If we continue not to receive a successful response, we’ll automatically disable your webhook.** * If you haven't made any major changes to your callback URI, commonly our request payload may have hit the request size limit for you server. Smartcar will attempt to get data from the vehicle with retries. However if we are unable to we'll return the relevant error response in the payload for that vehicle. For example, if a vehicle owner changes the credentials to their connected services account we'll return a [CONNECT\_SERVICES\_ACCOUNT:AUTHENTICATION\_FAILED](/errors/api-errors/connected-services-account-errors#authentication-failed) error prompting you to have the vehicle owner go through Connect again to reauthenticate their vehicle. To unsubscribe a vehicle you can hit the [unsubscribe](/api-reference/webhooks/unsubscribe-webhook) endpoint or [disconnect](/api-reference/management/delete-vehicle-connections) the vehicle from your application. # Scheduled Webhooks Scheduled webhooks make it incredibly easy to receive vehicle data on a cadence of your choosing. You can set up a webhook for any Smartcar endpoint that allows you to read data from a vehicle. This tutorial is split into four steps: 1. Creating your webhook 2. Verifying your callback URI 3. Confirmation with a test payload 4. Subscribing your first vehicle # Prerequisites For this tutorial it is recommended to have the following in place: * To receive webhooks you'll need to set up a callback URI on your server. * To [subscribe](/api-reference/webhooks/subscribe-webhook) a vehicle you'll want to have [Connect](/connect/dashboard-config) set up. # Creating your first webhook 1. Navigate to the **Webhooks** section of Dashboard and hit **+ Add Webhook**. 2. Next, name your webhook, enter in your callback URI, and select **Scheduled** as the type.

3. After selecting the type, you'll need to: * set how often you want receive data * select which endpoints you want to receive data from * select the units you want to receive data

4. Once you're happy with the configuration, hit **Add Webhook** and move on to verifying your callback URI. # Verifying your callback URI After adding your webhook, you'll be prompted to verify it. After hitting **Verify this webhook** Smartcar will post a challenge request to your callback URI to ensure we're sending payloads to the correct place.

This is a **one time** event and will be in the following format where the `eventName` will be `verify` ```json verificationRequest.body { "version": "2.0", "webhookId": "", "eventName": "verify", "payload": { "challenge": "" } } ``` Upon receiving the request, your server will need respond to the challenge by hashing `payload.challenge` with your `APPLICATION_MANAGEMENT_TOKEN` to create a `SHA-256` based `HMAC`. You can find your `APPLICATION_MANAGEMENT_TOKEN` in the Configuration section of Dashboard for your application. Return the hex-encoded hash as the value for `challenge` in your response body with a `2XX status code`. ```json verificationResponse.body { "status" : 204, "headers" : { "Content-Type": "application/json" }, "body" : { "challenge" : "{HMAC}" } } ``` See the [callback verification](/api-reference/webhooks/callback-verification) section on our API Reference for more information. # Confirmation with a test payload Once verified you can send a test payload to your callback URI. Payloads from vehicles will have `eventName` set to `scheduled`. The `mode` field will reflect the type of vehicle you've subscribed - either `live`, `test` or `simulated`. ```json Test Request Body { "version": "2.0", "webhookId": "6f9c7e43-2278-4a9b-b273-cdacab9ed83c", "eventName": "scheduled", "mode": "test", "payload": { "vehicles": [ { "vehicleId": "1a9fdd59-b65e-4bf1-8264-5448812eac83", "requestId": "6c22cd5c-34df-48ae-ad90-b324170629be", "data": [ { "path": "/", "code": 200, "body": { "id": "1a9fdd59-b65e-4bf1-8264-5448812eac83", "make": "BMW", "model": "i3 94 (+ REX)", "year": 2017 }, "headers": {} }, { "path": "/fuel", "code": 200, "body": { "range": 44.12, "percentRemaining": 0.57, "amountRemaining": 1.32 }, "headers": { "sc-data-age": "2020-05-11T23:44:31.000Z", "sc-unit-system": "imperial" } }, { "path": "/vin", "code": 200, "body": { "vin": "WBY1Z8C54HV550878" }, "headers": {} } ], "timestamp": "2020-05-13T22:00:01.288Z" } ] } } ``` ```json Test Request Headers { "sc-signature": "61e60e2e149ccc0c63680ca3a9df09e071ea450dffc1f0e844f962f9df019b44", "content-type": "application/json", "user-agent": "Smartcar-Webhooks/2.0", } ```
# Subscribing your first vehicle Now you've got your webhook set up, you can subscribe vehicles to start getting data at your desired frequency. If you haven't done so already, please set up the [Connect](connect/dashboard-config) for your application. After receiving your initial `ACCESS_TOKEN` from the [auth code exchange](connect/auth-code-exchange) step for Connect, you'll first want to hit the [All Vehicles](/api-reference/management/all-vehicles) endpoint to fetch the Smartcar `vehicle_id`s of the authorized vehicles.
With your `ACCESS_TOKEN` and `WEBHOOK_ID` you can hit the [Subscribe](/api-reference/webhooks/subscribe-webhook) endpoint for each `vehicle_id` to start receiving data.
# FAQs Data will post to the endpoint depending on your selected cadence. For example: * if a car is subscribed to an hourly interval webhook at 15:45 UTC, you'll get start to get data after 16:00UTC. * if a car is subscribed to a monthly interval, we'll process the webhooks at 00:00UTC for the selected day. No, you'll need to set up a webhook for each webhook type. Yes! You can distinguish between webhook types based on the `eventName` field - `scheduled` or `eventBased`. * Once a webhook is configured, we’ll begin sending events to your Callback URI on the cadence that you’ve chosen. We’ll expect a 2xx response to each. In the event that we don’t receive a 2xx response, we’ll retry 5 times over the next 10 minutes. **If we continue not to receive a successful response, we’ll automatically disable your webhook.** * Check that your server didn't experience down time for more than 10 minutes recently resulting in 2XX responses not being sent back to Smartcar. * If you haven't made any major changes to your callback URI, commonly our request payload may have hit the request size limit for you server. While we aim for 1 to 5 minutes after your selected cadence, the delivery time largely depends on the number of vehicles you have subscribed as well as the average OEM latency. Smartcar will try to fulfill requests for your webhook within 15 minutes of the scheduled time. If we were unable to fulfill a request during that time, we'll try again over the course of subsequent 15 minute intervals and post them to your webhook. # Testing with Postman In this guide we'll go over how to use Vehicle Simulator to test out Smartcar using Postman. ## What is Postman? Postman is a collaboration platform for API development. Postman's features simplify each step of building an API and streamline collaboration so you can create better APIs - faster. You’ll need a few things to start making API calls with Smartcar and Postman: * [A Postman Account](https://identity.getpostman.com/signup?continue=https%3A%2F%2Fgo.postman.co%2Fbuild) * [Smartcar’s Postman Collection](https://www.postman.com/smartcar/workspace/smartcar-api/collection/13172949-37efba9a-c68c-4f45-b123-af9154d7a0a6?action=share\&creator=9829117) * [A Smartcar Developer Account](https://dashboard.smartcar.com/signup) ## Configuring the Connect flow in Postman 1. Install the latest [Postman app](https://www.postman.com/downloads/) and log in 2. Import the [Smartcar collection](https://www.postman.com/smartcar/workspace/smartcar-api/collection/13172949-37efba9a-c68c-4f45-b123-af9154d7a0a6?action=share\&creator=9829117) into your local Postman workspace. Hit Import. 3. Click Link, paste in [the link](https://www.postman.com/smartcar/workspace/smartcar-api/collection/13172949-37efba9a-c68c-4f45-b123-af9154d7a0a6?action=share\&creator=9829117) to the collection and hit Continue. 4. On the next screen, hit Import.

## 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 in to 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. # Smartcar Usage Limits Learn about limits you may encounter when using Smartcar. ## Overview There are several types of limits that govern your use of Smartcar. The nature of telematics requires us to carefully manage vehicle connections and traffic to ensure the stability of our platform and those of our upstream providers. There are two major types of limits - **Billing Limits** and **Operational Rate Limits**. # Billing Limits ### [BILLING : VEHICLE\_REQUEST\_LIMIT](/errors/api-errors/billing-errors#vehicle-request-limit) Your Smartcar plan specifies a maximum number of API calls you are permitted to make to each single vehicle in a given month. If you exceed this limit, you will receive the `VEHICLE_REQUEST_LIMIT` error. For example: you have been allocated 500 API calls per vehicle per month, but you made the 501^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. # Brand Quirks Brand specific quirks to keep in mind while building out your application. ## Acura ### Ignition On Depending on model year, certain Acura vehicles do not return data when the ignition/engine is on. ### Sleep State Most Acuras will go into a sleep state after about a week of inactivity, ## Audi ### Primary Key User In order to have access to all vehicle functionality the account that connects to Smartcar will need to be flagged as a Key User by Audi. ## BMW/MINI ### CONNECTED\_SERVICES\_ACCOUNT - SUBSCRIPTION errors Smartcar API will throw a CONNECTED\_SERVICES\_ACCOUNT - SUBSCRIPTION when the data we receive from the vehicle is older than a month as this normally indicates a subscription issue. ## Ford/Lincoln ### Authentication Ford requires the use of an SDK to authenticate vehicles. Smartcar's Connect SDKs will redirect to Ford’s site to handle the authentication process when the user logs in. Web consent flows are not possible at this time. See [Connect SDKs](/docs/connect/connect-sdks) for our latest SDKs. ## GM (Buick, Chevrolet, Cadillac, GMC) ### VEHICLE\_STATE - ASLEEP errors After 3-4 days of no activity, GM vehicles will enter a deep sleep state at which point they will no longer respond to API requests to preserve their 12v battery. In order to get data from the vehicle again, the car will need to go through an ignition cycle. ### UPSTREAM - RATE\_LIMIT errors In order to avoid hitting UPSTREAM - RATE\_LIMIT errors use batch requests and ping no more than once every 30 minutes. Use of the OEM app also counts towards the rate limit. ## Hyundai/Kia ### Lock/Unlock Support for Hyundai US vehicles. Hyundai has limitations in place that limit how many lock/unlock requests can be made in a given period. As a result, we want to avoid the case where a user accidentally makes too many lock/unlock requests, potentially blocking them from using an app until Hyundai’s rate limit for the vehicle has reset. ### Polling Limitations Hyundai/Kia vehicles have a limitation where only 20 requests can be made in a 24 hour period. Smartcar allows one requests every 72 minutes to go to the vehicle directly. All other requests will be sent to the OEM's cloud which may be updated after events such as: * Every 10% of SoC while charging * 5 minutes after ignition off * Vehicle doors are left unlocked for 5 minutes * After a command successfully completes * Whenever charging stops ## Nissan ### “Vehicle has been found” MyNISSAN notifications Vehicle owners may receive a notification from the MyNISSAN app stating “Success! We found the location of your vehicle. Check the map for the location of your YYYY Model.” every time the location endpoint is hit. The app appears to have an option to edit notifications, but as of Feb 2024 they are not available in the app. Notifications may need to be turned off at the iOS/Android level by the vehicle owner. ## PSA Group (Citroen, DS, Opel, Peugeot, Vauxhall) ### Requesting control\_charge permissions If you request control\_charge permissions for PSA EVs, upon login owners will be presented with a PIN and MFA screen in Connect upon submitting their credentials. They will need to have set this up on their OEMs application in order to grant your application this permission. ## Rivian ### MFA If MFA is enabled the vehicle owner will need to re-authorize via Connect about every 2 weeks. ## Tesla ### Remote Access It may take a few hours or up to a full day for the REMOTE\_ACCESS\_DISABLED errors to subside after remote access is enabled. ### Charge Billing Records In order to retrieve charge billing records, the main Tesla account must connect the vehicle, as driver profiles do not have access to this data. ### Virtual Key Tesla now requires virtual keys for 3rd-party applications in order to issue commands for the following models: * All Cybertrucks, Model 3 and Model Y * 2021+ Model S and X ## Toyota/Lexus ### Prius Prime - Location Due to very low reliability/accuracy of the location endpoint for Prius Primes, we currently do not support that endpoint for the Prius Prime vehicles specifically. The regular Prius vehicle **do** support location. ## Volkswagen ### Control charge limits Volkswagen only allows 15 charge commands (start/stop charge) before the vehicle needs to be driven again in order to start responding to start/stop requests. ### CONNECTED\_SERVICES\_ACCOUNT errors on lock/unlock commands In addition to verifying the VW account with the activation code, some cars will need to undergo the VW Ident Process before you can access remote lock/unlock functionality. This involves contacting the dealership to verify your ownership of the vehicle. ### Missing Subscription (European VWs) Upon purchasing (or activating the free trial), VW needs to review the request. You will get an email confirmation once they've cleared everything on their side. ### Primary Driver Status In order to fully interact with Smartcar, the credentials need to be flagged as the primary driver. You'll need to tap the "become primary driver" flow in the VW app. Depending on the model, this may require you to be in the car to interact with the infotainment system. ## Volvo ### Lock/unlock commands Volvo is an outlier regarding how unlock requests are processed. After initiating the request, after about 10 seconds you'll need to open the trunk (boot) to successfully complete the request. You'll know the car is ready to unlock the trunk as the hazard lights will flash. We recommend adding a notification for Volvos as part of the request loading animation to inform the user of this process. ### Phone number username Smartcar Connect currently checks for an email format, as such phone number usernames cannot be used. The owner will need to add their email to their Volvo account via the web portal. ### Compatibility Some models are not compatible because the device needs to be physically in the vehicle during authentication, which Connect doesn’t support at the moment: * 2021+: XC40 Recharge * 2022+: S90, S90 Recharge, V90, V90 Recharge, V90 Cross Country, XC60, XC60 Recharge, C40 Recharge * 2023+: All models with the exception of the XC40 Even if the vehicle has been connected to and shows up in the Volvo app, if they go through Connect the account will present as if there are no vehicles on the account. # Brand Subscription Information Below you can find the connected service name for each brand as well as any specific subscription packages needed to connect to the vehicle via Smartcar. | Make | Region | Connected Service | Package | Subscription Cost | | ---------- | --------------------------- | ------------------------------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | Acura | US, Canada | ACURALINK | Remote | 3 year free trial (2023 and Newer Models), 6 month free trial (2022 and Older Models). \$110/year thereafter. | | Alfa Romeo | US, Europe | My Alfa Connect | My Car and My Remote | 3 - 5 years included. | | Audi | US | myAudi | CARE | - | | | Europe, Canada | Audi Connect | Remote | Free for three years after delivery of a new vehicle. \~£120/year thereafter. | | BMW | All | BMW Connected | - | Free trial varies with model year. \~\$120/year thereafter. | | Buick | US, Canada | OnStar | Remote Access | Free trial varies with model year. \$14.99/month for standalone Remote Access package. | | Cadillac | US, Canada | OnStar | Remote Access | Free trial varies with model year. \$14.99/month for standalone Remote Access package. | | Chevrolet | US, Canada | OnStar | Remote Access | Free trial varies with model year. \$14.99/month for standalone Remote Access package. | | Chrysler | US, Canada | Uconnect | Sirius XM Guardian (Remote Package) | 1 year free trial. \$12.99/month for the Remote Package thereafter. | | Citroën | Europe | My Citroën | ë-remote services needed for remote commands | - | | CUPRA | Europe | CUPRA CONNECT | Remote Access Services | 3 years free for the Born model, 1 year free for others. Price varies with region. | | Dacia | Europe | My Dacia | - | | | Dodge | US, Canada | Uconnect | Sirius XM Guardian (Remote Package) | 1 year free trial. \$12.99/month for the Remote Package thereafter. | | DS | Europe | MyDS | E-TENSE Remote | - | | Fiat | Europe | FIAT | My Car and My Remote | 6 month free trial. | | | US | FIAT Connect | Assistance Package | 3 month free trial with select vehicles. \$14.99/month. | | Ford | All | FordPass | - | - | | GMC | US, Canada | OnStar | Remote Access | Free trial varies with model year. \$14.99/month for standalone Remote Access package. | | Honda | US | HondaLink | EV Access for EV Data. Remote Access for Commands | EV Access 8 year trial. \$14.99/month for standalone Remote Access package. | | Hyundai | All | Hyundai BlueLink | - | 3 year free trial for new vehicles. \$9.90/month per package thereafter. | | | US | Hyundai BlueLink (2023 IONIQ 6 & all 2024+) | BlueLink+ | - | | Infiniti | US | MyINFINITI | - | 1 year free trial. \$12.99/month thereafter. | | Jaguar | All | Jaguar InControl | - | 3 year free trial. \~\$100/year thereafter. | | Jeep | US, Canada | Uconnect | Sirius XM Guardian (Remote Package) | 1 year free trial. \$12.99/month for the Remote Package thereafter. | | | US, Canada | Jeep Connect | Sirius XM Guardian (Remote Package) | 1 year free trial. \$12.99/month for the Remote Package thereafter. | | Kia | US, Canada | Kia Access | Plus | 1 year free trial. \$149/year thereafter. | | | Europe | Kia Connect | - | 7 year free trial starting on sale to the first owner. | | Land Rover | All | Land Rover InControl | - | 3 year free trial. \~\$100/year thereafter. | | Lexus | US, Canada | Lexus Enform | REMOTE | Free trial up to 3 years, varies with model year. \$80/year thereafter. | | Lincoln | US | Lincoln Way | - | - | | Mercedes | All | MeConnect | - | 1 year free trial. \~\$15/year there after. | | Mini | All | Mini Connected | - | Free trial varies with model year. \~\$120/year thereafter. | | Mazda | US, Europe | MyMazda | - | 3 year free trial. Pricing thereafter has not been established. | | Nissan | US (non-Leaf) | NissanConnect Services | Convenience | 6 month free trial. \$8.00/month thereafter. | | | US (Leaf) | NissanConnect EV Services | Convenience | 6 month free trial. \$8.00/month thereafter. | | | Europe | NissanConnect | - | Free trial varies with model year. \~£1.99/month thereafter. | | Opel | Europe | myOpel | e-Remote services needed for remote commands | - | | Peugeot | Europe | MYPEUGEOT | E-REMOTE CONTROL needed for remote commands | - | | Porsche | US, Europe | My Porsche | | 1 year free trial after initial purchase. \$299/year there after. | | RAM | US, Canada | Uconnect | Sirius XM Guardian (Remote Package) | 1 year free trial. \$12.99/month for the Remote Package thereafter. | | | US, Canada | Ram Connect | Sirius XM Guardian (Remote Package) | 1 year free trial. \$12.99/month for the Remote Package thereafter. | | Renault | Europe | My Renault | - | - | | Rivian | US | Rivian | - | - | | Skoda | Europe | MySKODA | Care Connect | \~£36/year. | | Subaru | US | MySubaru | STARLINK Security Plus | 6-month free trial. \$4.95/month thereafter. | | Tesla | All | Tesla | - | - | | Toyota | US, Canada | Toyota Connected Services | Remote Connect | 1 year free trial. \$80/year thereafter. | | Vauxhall | Europe | myVauxhall | e-Remote services needed for remote commands | - | | Volvo | All | Volvo Cars | - | Free trial varies with model year. \~\$200/year thereafter. | | Volkswagen | US | Car-Net | Remote Access | - | | | Europe (non-ID) 2018 - 2022 | Car-Net | - | - | | | Europe (non-ID) ≤ 2023 | We Connect | - | - | | | Europe (non-ID) 2024+ | VW Connect | - | - | | | Europe (ID) Firmware \<3 | We Connect Start | - | - | | | Europe (ID) Firmware v3+ | We Connect ID | - | - | ## Notes ### Audi * Owners will need to ensure they're the Primary or Key user for the vehicle connected to their account in order to access all Smartcar functionality. ### Ford and Lincoln * Owners that use a username to login to their connected services app will need to migrate to using their email address under account settings in their Ford Pass or Lincoln Way portal. ### Onstar * Chevy Bolts MY 2020+ come with the **EV Mobile Command** service included for 5 years with the purchase of a new vehicle. Location data is not included in the package. Bolt owners will need to also subscribe to **Remote Access** to be able to get access to location data. * For all other OnStar accounts, we require the modern **Remote Access** plan as our base subscription. This plan comes with the **Vehicle Status** feature set, which is what enables our remote access to data from cars. More information can be found [in this PDF](https://my.chevrolet.com/content/dam/gmownercenter/gmna/dynamic/onstar/comparePlans/nbm/OC_Compare-Plans-Chevy.pdf). * There are certain legacy OnStar accounts floating around with similar names. A good check on whether a customer has the correct plan or not is the ability to view vehicle information like fuel level, EV battery level, odometer, or tire pressure from within their vehicle’s mobile app. ### Nissan US * Convenience features are included as part of the Premium package. ### Toyota * The Remote Connect subscription is tied to the audio package purchased with the vehicle. Compatible audio package availability is determined based on the trim of the vehicle model and varies model year to model year. Toyota provides PDFs for Remote Connect availability [here](https://www.toyota.com/connected-services/#:~:text=Learn%20about%20your%20Connected%20Services). ### Uconnect * For all Uconnect accounts, we require the ability to interact with vehicle information through the UConnect portal * A Uconnect account may have access to Mopar, but not all Mopar accounts have access to UConnect. If a user can see information in Mopar but not UConnect, they’ll need to reach out to UConnect support to set up the right UConnect plan for their vehicle. * 2021+ Jeeps have their own connected service - Jeep Connect * 2022+ Rams have their own connected service - Ram Connect * 2022+ Jeep Wagoneers have their own connected service - Wagoneer Connect * Canada has limited support listed [here](https://www.driveuconnect.ca/en/sirius-xm-guardian-vehicles) ### Volkswagen ID Series * Model year 2021 and certain 2022 Volkswagen ID vehicles require an upgrade to vehicle software version 3 which will allow you to get location and odometer data. This is a requirement for both US and European vehicles. ### Volvo The following models are not currently compatible with Smartcar: * 2021+ : XC40 Recharge * 2022+ : S90, S90 Recharge, V90, V90 Recharge, V90 Cross Country, XC60, XC60 Recharge * 2023+ : All models with the exception of the XC40 # Compatible Vehicles # Connect your car # Diagnostic Systems To support our System Status endpoint, reference the below list of unified systems. The [System Status](https://smartcar.com/docs/api-reference/get-system-status) endpoint returns a list of systems reported by any given vehicle, as well as their current state which may be "OK" or "ALERT". ## System IDs | | | | --------------------------------- | --------------------------------------------------------- | | `SYSTEM_ABS` | Antilock Braking Systems | | `SYSTEM_ACTIVE SAFETY` | Active Safety Systems | | `SYSTEM_AIRBAG` | Airbag Systems | | `SYSTEM_BRAKE_FLUID` | Brake Fluid Level | | `SYSTEM_DRIVER_ASSISTANCE` | Driver Assistance Systems | | `SYSTEM_EMISSIONS` | Emissions Systems | | `SYSTEM_ABS` | Antilock Braking Systems | | `SYSTEM_ENGINE` | Engine Systems | | `SYSTEM_EV_BATTERY_CONDITIONING` | EV Battery Conditioning Systems | | `SYSTEM_EV_CHARGING` | EV Charging Systems | | `SYSTEM_EV_DRIVE_UNIT` | EV Drive Unit Systems | | `SYSTEM_EV_HV_BATTERY` | EV High-Voltage Battery Systems | | `SYSTEM_LIGHTING` | Lighting Systems | | `SYSTEM_MIL` | Malfunction Indiciator Lamp Systems (Check Engine Lights) | | `SYSTEM_OIL_LIFE` | Oil Life Systems | | `SYSTEM_OIL_PRESSURE` | Oil Pressure Systems | | `SYSTEM_OIL_TEMPERATURE` | Oil Temperature Systems | | `SYSTEM_TELEMATICS` | Telematics Systems | | `SYSTEM_TIRE_PRESSURE` | Tire Pressure Systems | | `SYSTEM_TIRE_PRESSURE_MONITORING` | Tire Pressure MonitoringSystems | | `SYSTEM_TRANSMISSION` | Transmission Systems | | `SYSTEM_WASHER_FLUID` | Washer Fluid Systems | | `SYSTEM_WATER_IN_FUEL` | Water in Fuel Detection Systems | # Early Access Understand Smartcar's approach to Early Access features. Early Access is a program that allows developers to test and integrate new Smartcar features before they are fully released. Early Access refers to a phase where certain features are made available for testing and feedback prior to general availability. These features are functional but may still be under development or refinement. ## Benefits of Early Access Participating in Early Access allows developers to get a head start on integrating new features, a chance to influence the feature in development through feedback and help Smartcar ensure your app’s needs are met. ## Considerations for Early Access When working with Early Access features, keep in mind that features may change before final release. As such, extra caution is advised when using these features in production environments. ## How to Participate If you would like to get involved in testing an Early Access feature, contact your Account Manager or our [Support](support@smartcar.com) team for guidance. # Frequently Asked Questions (FAQs) Below you'll find answers to some of the most frequently asked questions about Smartcar. 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