Pricing

Docs

Smartcar API reference

Welcome to Smartcar! Below you'll find everything you need to get started with Smartcar. If you have any questions, please email us at support@smartcar.com!

Smartcar makes it easy to read vehicle data and send commands to vehicles of any brand using HTTP requests. The Smartcar API is organized around REST. We use built-in HTTP features like HTTP verbs and HTTP authentication so you can use any HTTP client. All responses are returned in standard JSON and are documented in our API Reference.

All requests made to our API require an access token. Our API uses the OAuth2 authorization framework and provides a granular permissioning system that authorizes API endpoints based on vehicle owner preferences. This allows applications to easily authorize and interact with vehicles through the Smartcar API.

SDKs

Smartcar provides back-end and front-end SDKs to simplify integrations. All of our SDKs are open source and are maintained within their own GitHub repositories. Our API Reference contains code examples and a more detailed SDK reference can be found in each GitHub repository.

Smartcar API SDKs

Our API SDKs simplify the process of integrating Smartcar Connect, our OAuth authorization flow, and making API calls.

Smartcar Connect SDKs

Our Connect SDKs simplify the process of integrating Smartcar Connect, our OAuth authorization flow.

Registration

To get started, register your application with Smartcar by navigating to our developer dashboard.

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 (https://auth.smartcar.com).

Authorization

Smartcar uses the OAuth2 authorization framework. This allows applications to authorize and interact with vehicles using the Smartcar API.

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/redirect-{version}?app_origin={localhost-or-HTTPS-origin} https://javascript-sdk.smartcar.com/redirect-2.0.0?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.

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.

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.

Smartcar Connect

Smartcar Connect uses the OAuth 2.0 protocol to provide a secure and elegant authorization flow for your users. By going through Connect, your users can easily and securely grant your application permissions to interact with their vehicle.

Connect contains the following steps:

  1. Redirect to Smartcar Connect - Your application redirects the user to the Smartcar Connect OAuth flow.
  2. Authenticate user and obtain consent - Smartcar Connect prompts the user to log in with their vehicle's connected service username and password. Once logged in, the user will be asked to grant your application access to a specific scope of permissions.
  3. Handle response - If the user successfully accepts the permissions, Smartcar Connect will redirect the user back to your application using the specified redirect_uri with an authorization code. If an error occurs, Smartcar Connect will redirect the user to your application with an error message.

1. Redirect to Connect

When your application needs access to a user's vehicle(s), redirect them to Connect.

Construct the Connect redirect with the parameters below:

Parameter Required Description
client_id true The application's unique identifier. This is available on the Credentials tab of the dashboard.
redirect_uri true 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.
response_type true This value must be set to code. OAuth2 outlines multiple authorization types. Connect utilizes the 'Authorization Code' flow.
scope true A space-separated list of permissions that your application is requesting access to. The valid permission names can be found in the Scope 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 Scope guide in our docs for more information.
state false 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.
approval_prompt false 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.
mode false An optional value that indicates whether Connect should be run in test or live mode. Test mode lets you make requests to the Smartcar API on a simulated vehicle.
make false An optional parameter that allows users to bypass the car brand selection screen. We are compatible with the following makes: AUDI, BMW, BUICK, CADILLAC, CHEVROLET, CHRYSLER, DODGE, FORD, GMC, HYUNDAI, JEEP, LEXUS, LINCOLN, RAM, TESLA, and VOLKSWAGEN. Please refer to the Connect Direct guide for more information.
single_select false An optional value that sets the vehicle selection behavior of the grant dialog. Defaults to false. If set to true, then the user is only allowed to select a single vehicle. Please refer to the Connect Match guide for more information.
single_select_vin false An optional value that 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. 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 Connect Match guide for more information.

For running the API in test mode, please refer to the Testing section of our documentation.

Example
https://connect.smartcar.com/oauth/authorize?
response_type=code
&client_id=8229df9f-91a0-4ff0-a1ae-a1f38ee24d07
&scope=read_odometer read_vehicle_info required:read_location
&redirect_uri=https://example.com/home
&state=0facda3319

There are two parts in this step. First, the user will be asked to select their make and to log in with their vehicle's connected service username and password. If the login is successful, Connect will display a consent window that shows the name of your application and the scope of permissions your application is requesting access to. The vehicle owner can approve or deny the set of permissions.

3. Handle response

Connect sends the vehicle owner's approval or denial back to your application's server via the specified redirect URI.

Success

If the user grants your application access, the redirect to your application will contain the following query parameters:

HTTP/1.1 302 Found
Location: https://example.com/home?
code=90abecb6-e7ab-4b85-864a-e1c8bf67f2ad
&state=0facda3319
Parameter Required Description
code true An authorization code that will be used to obtain an access token in the following step. The authorization code expires after 10 minutes.
state false If the redirect to Connect contains a state parameter, that parameter will be returned here.

Error

If the user does not or cannot successfully grant your application access to their vehicle, Connect will return an error instead.

HTTP/1.1 302 Found
Location: https://example.com/home?
error=access_denied
&error_description=User+denied+access+to+application.
&state=0facda3319

There are three potential errors that Connect may return.

access_denied

The vehicle owner denied your application access to the requested scope of permissions.

Parameter Required Description
error true access_denied
error_description true User denied access to the requested scope of permissions.
state false If the redirect to Connect contains a state parameter, that parameter will be returned here.

vehicle_incompatible

The user's vehicle is not compatible. A compatible vehicle is one that:

  1. Has the hardware required for internet connectivity.
  2. Belongs to the makes and models Smartcar is compatible with.
  3. Is compatible with the required permissions that your app is requesting access to.

Connect will return the VIN, make, model, and year if possible.

Parameter Required Description
error true vehicle_incompatible
error_description true The user's vehicle is not compatible.
vin false The VIN of the vehicle.
make false The manufacturer of the vehicle.
model false The model of the vehicle.
year false The year of production of the vehicle.
state false If the redirect to Connect contains a state parameter, that parameter will be returned here.

invalid_subscription

The user's vehicle has an inactive or expired connected services subscription. A vehicle with an invalid subscription is one that:

  1. Has the hardware required for internet connectivity.
  2. Does not have an active connected services account, because the account is either expired or has never been activated.
Parameter Required Description
error true invalid_subscription
error_description true User does not have an active connected vehicle subscription.

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.

Request

The following headers must be provided with the request:

Header Description
Authorization HTTP Basic Auth header containing the client_id and client_secret. The header is formed by concatenating the word "Basic", followed by a space, and a base64 encoded string of the client_id, a colon :, and the client_secret.
Content-Type Must be set to application/x-www-form-urlencoded, matching the format of the request body.

The following parameters must be provided in the request body encoded in form-urlencoded format:

Parameter Required Description
code true The authorization code received in the handle response step.
grant_type true This value must be set to authorization_code. OAuth2 outlines multiple authorization types, Smartcar utilizes the 'Authorization Code' flow.
redirect_uri true The redirect_uri provided in the redirect to Connect step. This value is checked to match the URI sent when the user was directed to Connect.

Response

Parameter Description
access_token A string representing an access token used to make requests to the Smartcar API. This token is used in the authorization header.
expires_in The number of seconds the access token is valid for. This is always set to 7200 (2 hours).
refresh_token A string representing a refresh token, which is used to renew access when the current access token expires. The refresh token expires after 60 days.
token_type Always set to Bearer. Token type is used in forming the authorization header used by the Smartcar API in the following step.
Example request
curl https://auth.smartcar.com/oauth/token \
  -X POST \
  -H 'Authorization: Basic base64({client_id}:{client_secret})' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=authorization_code \
      &code=35a59c0b-745c-436c-a8a2-7758e718dcb8 \
      &redirect_uri=https://example.com/home'
Example response
{
  "access_token": "cf7ba7e9-8c5d-417d-a99f-c386cfc235cc",
  "token_type": "Bearer",
  "expires_in": 7200,
  "refresh_token": "3e565aed-d4b2-4296-9b4c-aec35825a6aa"
}

Refresh token exchange

Your access token will expire 2 hours after it is issued. When this happens, your application can retrieve a new one by using the refresh_token returned in the Auth code exchange step. An example request is provided to the right.

Request

The following headers must be provided with the request:

Header Description
Authorization HTTP Basic Auth header containing the client_id and client_secret. The header is formed by concatenating the word "Basic" followed by a space, and a base64 encoded string of the client_id, a colon :, and the client_secret.
Content-Type Must be set to application/x-www-form-urlencoded, matching the format of the request body.

The following parameters must be provided in the request body encoded in form-urlencoded format:

Parameter Required Description
grant_type true This value must be set to refresh_token. OAuth2 outlines multiple authorization types, Smartcar utilizes the 'Refresh Token' flow to allow applications to renew access.
refresh_token true The refresh token received in the response with the access token in the Auth code exchange step.

Response

This new access token can now be used to use Smartcar's API.

Parameter Description
access_token A string representing a new access token to be used in requests to the Smartcar API. This token is used in the authorization header.
expires_in The number of seconds the access token is valid for. This is always set to 7200 (2 hours).
refresh_token A string representing a new refresh token, the previous refresh token is invalidated immediately once it is used. The refresh token expires in 60 days.
token_type Always set to Bearer. The type is used in forming the authorization header used by the Smartcar API.
Example request
curl https://auth.smartcar.com/oauth/token \
  -X POST \
  -H 'Authorization: Basic base64({client_id}:{client_secret})' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=refresh_token \
      &refresh_token=3e565aed-d4b2-4296-9b4c-aec35825a6aa'
Example response
{
  "access_token": "11016e76-610c-41c6-9688-1f5613889932",
  "token_type": "Bearer",
  "expires_in": 7200,
  "refresh_token": "09337f8a-da3a-46c0-95e7-9c19180b06c0"
}

Permissions

Permissions are specified by the scope parameter, a space-separated list of permissions that your application is requesting access to during Smartcar Connect. Valid permission names are:

Please refer to the Scope guide in our docs for more information.

Headers

Smartcar supports additional HTTP headers in both requests and responses. Our headers are prefixed with SC-.

Request headers

Smartcar uses HTTP request headers for authorization and configuration of API responses.

Header Description
Authorization Bearer authorization header, which is formed by concatenating the word "Bearer" with the access token, separated by a space.
SC-Unit-System Smartcar supports both Metric and Imperial unit systems of measurement. Set the SC-Unit-System header to metric or imperial to configure your preferred unit system. If no header is specified, Smartcardefaults to use the Metric system.
Example request
curl https://api.smartcar.com/v1.0/vehicles/{id}/odometer
-H "Authorization: Bearer 653200d2-10b4-495a-ab95-289faa0ab273"
-H "SC-Unit-System: imperial"
-X "GET"

Response headers

Smartcar's additional response headers provide additional information about the data contained in responses.

Header Description
SC-Data-Age Indicates the timestamp (ISO-8601 format) of when the returned data was recorded by the vehicle.
SC-Unit-System Indicates whether the unit system used in the returned data is imperial or metric.
SC-Request-Id Each response from Smartcar's API has a unique request identifier. If you need to contact us about a specific request, providing the request identifier will ensure the fastest possible resolution.
Example response
HTTP/1.1 200 OK
Content-Type: application/json
SC-Data-Age: 2018-06-20T01:33:37.078Z
SC-Unit-System: metric
SC-Request-Id: 26c14915-0c26-43c5-8e42-9edfc2a66a0f

{
  "distance": 104.32
}

Connect Compatibility

Connect Compatibility is a feature that lets developers verify whether a vehicle is eligible to use Smartcar. Using this endpoint, developers can confirm whether specific vehicles are compatible before sending a user through Smartcar Connect.

A compatible vehicle is one that:

  1. Has the hardware required for internet connectivity
  2. Belongs to the makes and models Smartcar is compatible with
  3. Is compatible with the required permissions that your app is requesting access to

Connect Compatibility is a Connect Pro feature. Please contact us if you'd like to request access.

Request

The following headers must be provided with the request:

Header Description
Authorization HTTP Basic Auth header containing the client_id and client_secret. The header is formed by concatenating the word "Basic", a space, and a base64 encoded string of the client_id, a colon :, and the client_secret.

The following query parameters must be provided:

Parameter Required Description
vin true The VIN (Vehicle Identification Number) of the vehicle.
scope true A space-separated list of permissions. The valid permission names can be found in the Scope section.

The VIN is a required parameter for this endpoint. Connect Compatibility should only be used if you already know the vehicle's VIN prior to sending a user through Smartcar Connect.

When defining the scope parameter, please include only the permissions that are required for your application's functionality. This will maximize the number of vehicles that are compatible with your app.

Response body

Parameter Type Description
compatible boolean false if the vehicle is not compatible. true if the vehicle is likely compatible.*

*Note: as we are only using the VIN, we can only guarantee if a vehicle is NOT compatible with the platform.

Example request
curl https://api.smartcar.com/v1.0/compatibility?vin={vin}&scope={scope} \
  -X GET \
  -H 'Authorization: Basic base64({client_id}:{client_secret})' \
Example response
{
  "compatible": true
}

Connect Match

Connect Match is a feature that lets developers limit users to only authorizing a single vehicle during Smartcar Connect.

Connect Match is a Connect Pro feature. Please contact us if you'd like to request access.

If your application collects VINs and you would like to limit the user to selecting a specific vehicle, you can use Connect Match with VIN. Pass in the VIN of the vehicle using the single_select_vin parameter in addition to including the single_select parameter.

Parameter Required Description
single_select false An optional value that sets the behavior of the permissions screen in Smartcar Connect. Defaults to false. If set to true, then the user is only allowed to select a single vehicle.
single_select_vin false An optional value that 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. 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 (see Connect Direct).
Example
https://connect.smartcar.com/oauth/authorize?
response_type=code
&client_id=8229df9f-91a0-4ff0-a1ae-a1f38ee24d07
&scope=read_odometer read_vehicle_info required:read_location
&redirect_uri=https://example.com/home
&state=0facda3319
&mode=live
&single_select=true
&single_select_vin=5YJSA1E14FF101307

Connect Direct

Connect Direct is a feature that lets users bypass the car brand selection step when going through Smartcar Connect.

Connect Direct is a Connect Pro feature. Please contact us if you'd like to request access.

If you know the make of the vehicle your user is trying to authorize in Smartcar Connect, you can include the make as a parameter in your Connect Authorization URL. This will let the user automatically skip the car brand selection screen in Smartcar Connect.

Parameter Required Description
make false An optional parameter that allows users to bypass the car brand selection screen. Compatible makes are: AUDI, BMW, BUICK, CADILLAC, CHEVROLET, CHRYSLER, DODGE, FORD, GMC, HYUNDAI, JEEP, LEXUS, LINCOLN, RAM, TESLA, and VOLKSWAGEN. The single_select_vin parameter takes precedence over the make parameter (see Connect Match).
Example
https://connect.smartcar.com/oauth/authorize?
response_type=code
&client_id=8229df9f-91a0-4ff0-a1ae-a1f38ee24d07
&scope=read_odometer read_vehicle_info required:read_location
&redirect_uri=https://example.com/home
&state=0facda3319
&make=TESLA

Errors

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

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

Error response

All Smartcar errors contain the following fields:

Name Type Description
error string A string describing the error type
message string A message explaining the error
code string An error code indicating the specific instance of the error.

Error types

Error Status Description
validation_error 400 The request was malformed due to incorrect syntax or missing parameters.
vehicle_owner_action_required 400 The owner of the vehicle must take action to remediate the situation.
authentication_error 401 The provided application credentials were incorrect.
permission_error 403 The application credentials have insufficient permissions to access the requested resource.
resource_not_found_error 404 The requested resource does not exist.
vehicle_state_error 409 The vehicle is not capable of performing the request in its current state. The vehicle may be unreachable ( e.g. in an underground parking lot).
rate_limiting_error 429 The application has sent too many requests in a short time span.
monthly_limit_exceeded 430 The application has exceeded its monthly request limit.
server_error 500 The server experienced an unexpected error.
vehicle_not_capable_error 501 The vehicle is not capable of performing the request. For example, a vehicle without a sunroof cannot perform an 'open sunroof' command.
smartcar_not_capable_error 501 Smartcar is currently not capable of performing the request.

Vehicle owner action required codes

Code Description
VOA_000 Vehicle authentication failed. Please prompt the vehicle owner to log in again using Connect.
VOA_001 Connected services subscription invalid or expired. Please prompt the vehicle owner to reactivate their subscription.

Vehicle state error codes

Code Description
VS_000 Vehicle state cannot be determined.
VS_001 Some of the vehicle's doors are open.
VS_002 Some of the vehicle's trunks are open.
VS_003 The vehicle's hood is open.
VS_004 Charging plug is not connected to the vehicle.
VS_005 Vehicle is fully charged.
VS_006 Vehicle is asleep.
VS_007 Vehicle is offline.
VS_008 Vehicle's ignition is switched on.
VS_009 Vehicle is moving.
VS_010 Remote access is disabled.
VS_011 Vehicle is charging.
Example error response
{
  "error": "validation_error",
  "message": "Invalid or missing request parameters."
}
{
  "error": "vehicle_owner_action_required",
  "message": "Vehicle authentication failed. Please prompt the vehicle owner to log in again using Connect.",
  "code": "VOA_000"
}
{
  "error": "authentication_error",
  "message": "Invalid or expired token provided."
}
{
  "error": "permission_error",
  "message": "Insufficient permissions to access requested resource."
}
{
  "error": "resource_not_found_error",
  "message": "The requested resource was not found."
}
{
  "error": "vehicle_state_error",
  "message": "Vehicle state cannot be determined.",
  "code": "VS_000"
}
{
  "error": "rate_limiting_error",
  "message": "The application has sent too many requests and cannot be served due to the application's rate limit being exhausted."
}
{
  "error": "monthly_limit_exceeded",
  "message": "The application has exceeded its monthly limit. Please upgrade the billing plan on the account dashboard."
}
{
  "error": "server_error",
  "message": "Unexpected server error, please try again."
}
{
  "error": "vehicle_not_capable_error",
  "message": "Vehicle is not capable of performing the request."
}
{
  "error": "smartcar_not_capable_error",
  "message": "Smartcar is currently not capable of performing the request."
}

get All vehicles

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

Query parameters

Parameter Type Required Description
limit integer false Number of vehicles to return (default: 10).
offset integer false Index to start vehicle list at

Response body

Name Type Description
vehicles array An array of vehicle IDs.
vehicles.[] string A vehicle ID (UUID v4).
paging object Metadata about the current list of elements.
paging.count integer The total number of elements for the entire query (not just the given page).
paging.offset integer The current start index of the returned list of elements.
get
https://api.smartcar.com/v1.0/vehicles
Example request
curl https://api.smartcar.com/v1.0/vehicles \
-H "Authorization: Bearer {token}" \
-X "GET"
Example response
{
  "paging": {
    "count": 25,
    "offset": 10
  },
  "vehicles": [
    "36ab27d0-fd9d-4455-823a-ce30af709ffc"
  ]
}

get Application permissions

Returns a list of the permissions that have been granted to your application in relation to this vehicle.

Query parameters

Parameter Type Required Description
limit integer false Number of permissions to return (default: 25).
offset integer false Index to start permission list at

Response body

Name Type Description
permissions array An array of permissions.
permissions.[] string A permission.
paging object Metadata about the current list of elements.
paging.count integer The total number of elements for the entire query (not just the given page).
paging.offset integer The current start index of the returned list of elements.
get
https://api.smartcar.com/v1.0/vehicles/{id}/permissions
Example request
curl https://api.smartcar.com/v1.0/vehicles/{id}/permissions \
-H "Authorization: Bearer {token}" \
-X "GET"
Example response
{
  "paging": {
    "count": 25,
    "offset": 10
  },
  "permissions": [
    "read_vehicle_info"
  ]
}

post Batch request

Returns a list of responses from multiple Smartcar endpoints, all combined into a single request. Note: This is currently a beta feature. Please contact us if you'd like to request access.

Request body

Name Type Required Description
requests array true The array of requests to make.
requests.[].path string true The Smartcar endpoint to request data from.

Response body

Name Type Description
responses array The responses from Smartcar.
responses.[].headers object The header of this particular response.
headers.sc-unit-system string The unit system to use for the request.
headers.sc-data-age string The timestamp (ISO-8601 format) of when the returned data was recorded by the vehicle.
responses.[].code number The HTTP resonse code.
responses.[].body The response body of this request. The structure of this object will vary by endpoint. See the according endpoint specification.
responses.[].path string The Smartcar endpoint to request data from.
post
https://api.smartcar.com/v1.0/vehicles/{id}/batch
Example request
curl https://api.smartcar.com/v1.0/vehicles/{id}/batch \
-H "Authorization: Bearer {token}" \
-X "POST" \
-H "Content-Type: application/json" \
-d '{"requests": [{ "path" : "/odometer" }, { "path" : "/location" }]}'
Example response
{
  "responses": [
    {
      "path": "/odometer",
      "body": {
        "distance": 37829
      },
      "code": 200,
      "headers": {
        "sc-data-age": "2019-10-24T00:43:46.000Z",
        "sc-unit-system": "metric"
      }
    },
    {
      "path": "/location",
      "body": {
        "latitude": 37.4292,
        "longitude": 122.1381
      },
      "code": 200,
      "headers": {
        "sc-data-age": "2019-10-24T00:43:46.000Z"
      }
    }
  ]
}

delete Disconnect

Revoke access for the current requesting application. This is the correct way to disconnect a user.

Response body

Name Type Description
status string This will always be set to success for HTTP 200.
delete
https://api.smartcar.com/v1.0/vehicles/{id}/application
Example request
https://api.smartcar.com/v1.0/vehicles/{id}/application \
-H "Authorization: Bearer {token}" \
-X "DELETE"
Example response
{
  "status": "success"
}

get EV battery

Returns the state of charge (SOC) and remaining range of an electric or plug-in hybrid vehicle's battery.

Permission

read_battery

Response body

Name Type Description
percentRemaining number An EV battery's state of charge (in percent).
range number The estimated remaining distance the vehicle can travel (in kilometers by default or in miles using the sc-unit-system).
get
https://api.smartcar.com/v1.0/vehicles/{id}/battery
Example request
curl https://api.smartcar.com/v1.0/vehicles/{id}/battery \
-H "Authorization: Bearer {token}" \
-X "GET"
Example response
{
  "percentRemaining": 0.3,
  "range": 40.5
}

get EV charging status

Returns the current charge status of the vehicle.

Permission

read_charge

Response body

Name Type Description
isPluggedIn boolean Indicates whether the charging cable is currently plugged in.
state string Indicates the current state of the charge system.
Options: CHARGING FULLY_CHARGED NOT_CHARGING
get
https://api.smartcar.com/v1.0/vehicles/{id}/charge
Example request
curl https://api.smartcar.com/v1.0/vehicles/{id}/charge \
-H "Authorization: Bearer {token}" \
-X "GET"
Example response
{
  "isPluggedIn": true,
  "state": "FULLY_CHARGED"
}

get Engine oil life

Returns the remaining life span of a vehicle's engine oil. Note: This is currently a beta feature. Please contact us if you'd like to request access.

Permission

read_engine_oil

Response body

Name Type Description
lifeRemaining number The engine oil's remaining life span (as a percentage). Oil life is based on the current quality of the oil. (in percent).
get
https://api.smartcar.com/v1.0/vehicles/{id}/engine/oil
Example request
curl https://api.smartcar.com/v1.0/vehicles/{id}/engine/oil \
-H "Authorization: Bearer {token}" \
-X "GET"
Example response
{
  "lifeRemaining": 0.35
}

get Fuel tank

Returns the status of the fuel remaining in the vehicle's gas tank.

Permission

read_fuel

Response body

Name Type Description
range number The estimated remaining distance the car can travel (in kilometers by default or in miles using the sc-unit-system).
percentRemaining number The remaining level of fuel in the tank (in percent).
amountRemaining number The amount of fuel in the tank (in liters by default or in gallons (U.S.) using the sc-unit-system).
get
https://api.smartcar.com/v1.0/vehicles/{id}/fuel
Example request
curl https://api.smartcar.com/v1.0/vehicles/{id}/fuel \
-H "Authorization: Bearer {token}" \
-X "GET"
Example response
{
  "amountRemaining": 53.2,
  "percentRemaining": 0.3,
  "range": 40.5
}

get Location

Returns the last known location of the vehicle in geographic coordinates.

Permission

read_location

Response body

Name Type Description
latitude number The latitude (in degrees).
longitude number The longitude (in degrees).
get
https://api.smartcar.com/v1.0/vehicles/{id}/location
Example request
curl https://api.smartcar.com/v1.0/vehicles/{id}/location \
-H "Authorization: Bearer {token}" \
-X "GET"
Example response
{
  "latitude": 37.4292,
  "longitude": 122.1381
}

post Lock/unlock

Lock or unlock the vehicle.

Permission

control_security

Request body

Name Type Required Description
action string true The action to take on the security system.
Options: LOCK UNLOCK

Response body

Name Type Description
status string This will always be set to success for HTTP 200.
post
https://api.smartcar.com/v1.0/vehicles/{id}/security
Example request
curl https://api.smartcar.com/v1.0/vehicles/{id}/security \
-H "Authorization: Bearer {token}" \
-X "POST" \
-H "Content-Type: application/json" \
-d '{"action": "LOCK"}'
Example response
{
  "status": "success"
}

get Odometer

Returns the vehicle's last known odometer reading.

Permission

read_odometer

Response body

Name Type Description
distance number The current odometer of the vehicle (in kilometers by default or in miles using the sc-unit-system).
get
https://api.smartcar.com/v1.0/vehicles/{id}/odometer
Example request
curl https://api.smartcar.com/v1.0/vehicles/{id}/odometer \
-H "Authorization: Bearer {token}" \
-X "GET"
Example response
{
  "distance": 104.32
}

get Tire pressure

Returns the air pressure of each of the vehicle's tires. Note: This is currently a beta feature. Please contact us if you'd like to request access.

Permission

read_tires

Response body

Name Type Description
frontLeft number The current air pressure of the front left tire (in kilopascals by default or in pounds per square inch using the sc-unit-system).
frontRight number The current air pressure of the front right tire (in kilopascals by default or in pounds per square inch using the sc-unit-system).
backLeft number The current air pressure of the back left tire (in kilopascals by default or in pounds per square inch using the sc-unit-system).
backRight number The current air pressure of the back right tire (in kilopascals by default or in pounds per square inch using the sc-unit-system).
get
https://api.smartcar.com/v1.0/vehicles/{id}/tires/pressure
Example request
curl https://api.smartcar.com/v1.0/vehicles/{id}/tires/pressure \
-H "Authorization: Bearer {token}" \
-X "GET"
Example response
{
  "backLeft": 219.3,
  "backRight": 219.3,
  "frontLeft": 219.3,
  "frontRight": 219.3
}

get User

Returns the id of the vehicle owner who granted access to your application. This should be used as the static unique identifier for storing the access token and refresh token pair in your database. NOTE: A single user can own multiple vehicles, and multiple users can own the same vehicle.

Response body

Name Type Description
id string A user ID (UUID v4).
get
https://api.smartcar.com/v1.0/user
Example request
curl https://api.smartcar.com/v1.0/user \
-H "Authorization: Bearer {token}" \
-X "GET"
Example response
{
  "id": "e0514ef4-5226-11e8-8c13-8f6e8f02e27e"
}

get VIN

Returns the vehicle's manufacturer identifier.

Permission

read_vin

Response body

Name Type Description
vin string The manufacturer unique identifier.
get
https://api.smartcar.com/v1.0/vehicles/{id}/vin
Example request
curl https://api.smartcar.com/v1.0/vehicles/{id}/vin \
-H "Authorization: Bearer {token}" \
-X "GET"
Example response
{
  "vin": "1234A67Q90F2T4567"
}

get Vehicle attributes

Returns a single vehicle object, containing identifying information.

Permission

read_vehicle_info

Response body

Name Type Description
id string A vehicle ID (UUID v4).
make string The manufacturer of the vehicle.
model string The model of the vehicle.
year integer The model year.
get
https://api.smartcar.com/v1.0/vehicles/{id}
Example request
curl https://api.smartcar.com/v1.0/vehicles/{id} \
-H "Authorization: Bearer {token}" \
-X "GET"
Example response
{
  "id": "36ab27d0-fd9d-4455-823a-ce30af709ffc",
  "make": "TESLA",
  "model": "Model S",
  "year": 2014
}
Show examples in: