Authenticating with Smartcar

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

Register

To get started, first register your application with Smartcar.

Upon registering, 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).

When registering you will also be asked to provide one or more redirect URIs. This is a url located on your application's server which will be redirected to upon completion of the authorization flow. We will discuss it in more in the next step.

Authorize User

In order for your application to interact with a vehicle, a user must first consent to providing your application access to the necessary permissions.

In order to allow a user to log in to their vehicle's account and consent to the scope of permissions, your application must direct the user to the Smartcar authorization dialog. The Smartcar authorization dialog URL requires query parameters to identify your application:

https://<make>.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
&state=0facda3319

Note <make> should be replaced by the vehicle make.

For testing set the make to mock to make API requests on a simulated vehicle: https://mock.smartcar.com/oauth/authorize. When logging in to a mock vehicle, credentials that match <anything>@<anything>.com along with any password will work.

Parameter Required Description
client_id true The application's unique identifier. This is available on the Apps 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 Apps tab of the dashboard.
response_type true This value must be set to code . OAuth2 outlines multiple authorization types, Smartcar utilizes the 'Authorization Code' flow.
scope true A space separated list of permissions your application is requesting access to. The valid permission names are found in the API Reference .
state false An optional value which will be 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.

The steps of the flow are as follows:

  1. Your application directs a user to the Smartcar authentication dialog with the query parameters specified above.

  2. Smartcar prompts the user to log in with their credentials. Once logged in, the user will be asked to grant your application access to the specific scope of permissions requested. The user can choose to either "Allow" or "Deny".

  3. Smartcar redirects the user back to your application using the redirect_uri.

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 Description
code A short-lived authorization code which will be used in the following step to obtain an access token.
state If the state parameter was set in the redirect to the Smartcar authorization dialog, it will returned here.

If the user denies your application, an error will be returned instead:

HTTP/1.1 302 Found
Location: https://example.com/home?
error=access_denied
&error_description=User+denied+access+to+application.
&state=0facda3319
Parameter Description
error This will be set to access_denied if the user decided to deny your application access to the requested scope of permissions.
error_description Detailed description of the error.
state If the state parameter was set in the redirect to the Smartcar authorization dialog, it will returned here.

Request Access Token

In order 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 for a scope of permissions, but does not alone provide access to interact with a vehicle. To request an access token, make the following request:

POST https://auth.smartcar.com/oauth/token

Authorization: Basic base64(<client_id>:<client_secret>)
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=35a59c0b-745c-436c-a8a2-7758e718dcb8&
redirect_uri=https://example.com/home
Header Description
Authorization HTTP Basic Auth header containing the client_id and client_secret . The header is formed by concatenating the word "Basic" with 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 response of Authorize User 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 Authorize User step. This value is checked to match the URI sent when the user was directed to the Smartcar authorization dialog. (Here it is not used for redirecting the user agent).

Response

{
  "access_token":"cf7ba7e9-8c5d-417d-a99f-c386cfc235cc",
  "token_type":"Bearer",
  "expires_in":7200,
  "refresh_token":"3e565aed-d4b2-4296-9b4c-aec35825a6aa"
}
Parameter Description
access_token A string representing an access token to be used in requests to the Smartcar API.
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 in 60 days.
token_type Always set to Bearer . The type is used in forming the Authorization header used by the Smartcar API in the following step.

Use Smartcar API

Now that you have an access token, your application can make requests to the Smartcar API.

Remember that your application can only interact with the endpoints your application was granted access to in the authorization flow. In our example in Authorize User step, the user granted our application permission to read_vehicle_info and read_odometer.

All vehicle endpoints require a vehicle id. Send a request to the /vehicles endpoint to retrieve a list of the user's authorized vehicles.

GET https://api.smartcar.com/v1.0/vehicles

Authorization: Bearer cf7ba7e9-8c5d-417d-a99f-c386cfc235cc
Header Description
Authorization Bearer authorization header containing an access_token . The header is formed by concatenating the word "Bearer" with an access token as shown above.

Response

{
  "paging": {
    "count": 3,
    "offset": 0
  },
  "vehicles": [
    "36ab27d0-fd9d-4455-823a-ce30af709ffc",
    "d6f36bb5-cea9-4963-bbf1-7eb4641e7466",
    "ea2ec8d3-cf26-46dc-8957-c4d0a14af67c"
  ]
}

Now that your application has the user's vehicle ids, you can make requests to the vehicle. For example, you can retrieve the vehicle's make, model, and year by making a request to the Basic Vehicle Info resource:

GET https://api.smartcar.com/v1.0/vehicles/36ab27d0-fd9d-4455-823a-ce30af709ffc

Authorization: Bearer cf7ba7e9-8c5d-417d-a99f-c386cfc235cc

Response

{
  "id": "36ab27d0-fd9d-4455-823a-ce30af709ffc",
  "make": "TESLA",
  "model": "Model S",
  "year": 2014
}

Next, you can check what permissions your application has been granted access to by making a request to the Application Permissions resource:

GET https://api.smartcar.com/v1.0/vehicles/36ab27d0-fd9d-4455-823a-ce30af709ffc/permissions

Authorization: Bearer cf7ba7e9-8c5d-417d-a99f-c386cfc235cc

Response

{
  "permissions": [
    "read_vehicle_info",
    "read_odometer"
  ]
}

Next, you can check the odometer by making a request to the Odometer resource:

GET https://api.smartcar.com/v1.0/vehicles/36ab27d0-fd9d-4455-823a-ce30af709ffc/odometer

Authorization: Bearer cf7ba7e9-8c5d-417d-a99f-c386cfc235cc

Response

{
  "distance": 104.32
}

Renew Access

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 Step 3. To request a new access token, make the following request:

POST https://auth.smartcar.com/oauth/token

Authorization: Basic base64(<client_id>:<client_secret>)
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=3e565aed-d4b2-4296-9b4c-aec35825a6aa
Header Description
Authorization HTTP Basic Auth header containing the client_id and client_secret . The header is formed by concatenating the word "Basic" with 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 of Step 3.

Response

{
  "access_token":"11016e76-610c-41c6-9688-1f5613889932",
  "token_type":"Bearer",
  "expires_in":7200,
  "refresh_token":"09337f8a-da3a-46c0-95e7-9c19180b06c0"
}

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

get All Vehicles

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

Required Permissions

read_vehicle_info

Response Body

Name Type Description
vehicles array An array of vehicle IDs
paging object Metadata about the current list of elements
get
https://api.smartcar.com/v1.0/vehicles

Example Request

curl https://api.smartcar.com/v{{version}}/vehicles
-H "Authorization: Bearer {{token}}"
-X "GET"

Example Response

{
  "paging": {
    "count": 25,
    "offset": 10
  },
  "vehicles": [
    "36ab27d0-fd9d-4455-823a-ce30af709ffc"
  ]
}

get Basic Vehicle Info

Returns a single vehicle object, containing identifying information.

Required Permissions

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/v{{version}}/vehicles/{{id}}
-H "Authorization: Bearer {{token}}"
-X "GET"

Example Response

{
  "id": "36ab27d0-fd9d-4455-823a-ce30af709ffc",
  "make": "TESLA",
  "model": "Model S",
  "year": 2014
}

get Accelerometer

Returns the current reading of the vehicle's accelerometer.

Required Permissions

read_accelerometer

Response Body

Name Type Description
x number The acceleration on the X axis
y number The acceleration on the Y axis
z number The acceleration on the Z axis
get
https://api.smartcar.com/v1.0/vehicles/{{id}}/accelerometer

Example Request

curl https://api.smartcar.com/v{{version}}/vehicles/{{id}}/accelerometer
-H "Authorization: Bearer {{token}}"
-X "GET"

Example Response

{
  "x": 12.2,
  "y": 3.08,
  "z": 5.83
}

get Airbags

Returns the state of the vehicle's airbags.

Required Permissions

read_airbags

Response Body

Name Type Description
airbags array An array of airbags
get
https://api.smartcar.com/v1.0/vehicles/{{id}}/airbags

Example Request

curl https://api.smartcar.com/v{{version}}/vehicles/{{id}}/airbags
-H "Authorization: Bearer {{token}}"
-X "GET"

Example Response

{
  "airbags": [
    {
      "isActive": true,
      "isDeployed": false,
      "location": "FRONT_LEFT",
      "type": "FRONTAL"
    }
  ]
}

get Altimeter

Returns the vehicle's current altitude.

Required Permissions

read_altimeter

Response Body

Name Type Description
altitude number The altitude
get
https://api.smartcar.com/v1.0/vehicles/{{id}}/altimeter

Example Request

curl https://api.smartcar.com/v{{version}}/vehicles/{{id}}/altimeter
-H "Authorization: Bearer {{token}}"
-X "GET"

Example Response

{
  "altitude": 1020.43
}

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/v{{version}}/vehicles/{{id}}/application
-H "Authorization: Bearer {{token}}"
-X "DELETE"

Example Response

{
  "status": "success"
}

get Barometer

Returns the current reading of the vehicle's barometer.

Required Permissions

read_barometer

Response Body

Name Type Description
pressure number The barometric pressure at the vehicle ' s current altitude
get
https://api.smartcar.com/v1.0/vehicles/{{id}}/barometer

Example Request

curl https://api.smartcar.com/v{{version}}/vehicles/{{id}}/barometer
-H "Authorization: Bearer {{token}}"
-X "GET"

Example Response

{
  "pressure": 97.71
}

get Battery

Returns the state of the electric vehicle's battery.

Required Permissions

read_battery

Response Body

Name Type Description
percentRemaining number The remaining level of charge in the battery
range number The estimated remaining distance the vehicle can travel
get
https://api.smartcar.com/v1.0/vehicles/{{id}}/battery

Example Request

curl https://api.smartcar.com/v{{version}}/vehicles/{{id}}/battery
-H "Authorization: Bearer {{token}}"
-X "GET"

Example Response

{
  "percentRemaining": 0.3,
  "range": 40.5
}

get Battery Voltmeter

Returns the voltage of the electric vehicle's battery.

Required Permissions

read_battery_voltmeter

Response Body

Name Type Description
voltage number The current reading of the voltmeter
get
https://api.smartcar.com/v1.0/vehicles/{{id}}/battery/voltmeter

Example Request

curl https://api.smartcar.com/v{{version}}/vehicles/{{id}}/battery/voltmeter
-H "Authorization: Bearer {{token}}"
-X "GET"

Example Response

{
  "voltage": 350
}

get Battery Ammeter

Returns the amperage of the electric vehicle's battery.

Required Permissions

read_battery_ammeter

Response Body

Name Type Description
amperage number The current reading of the ammeter
get
https://api.smartcar.com/v1.0/vehicles/{{id}}/battery/ammeter

Example Request

curl https://api.smartcar.com/v{{version}}/vehicles/{{id}}/battery/ammeter
-H "Authorization: Bearer {{token}}"
-X "GET"

Example Response

{
  "amperage": 1000
}

get Charge

Returns the current charge status of the vehicle.

Required Permissions

read_charge

Response Body

Name Type Description
isPluggedIn boolean Indicates whether the charge cable is currently plugged in
state string Indicates the current state of the charge system
get
https://api.smartcar.com/v1.0/vehicles/{{id}}/charge

Example Request

curl https://api.smartcar.com/v{{version}}/vehicles/{{id}}/charge
-H "Authorization: Bearer {{token}}"
-X "GET"

Example Response

{
  "isPluggedIn": false,
  "state": "FULLY_CHARGED"
}

post Charge

Start or stop charging the vehicle.

Required Permissions

control_charge, control_charge:start, control_charge:stop

Request Body

Name Type Required Description
action string true The action to take on the charge system

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}}/charge

Example Request

curl https://api.smartcar.com/v{{version}}/vehicles/{{id}}/charge
-H "Authorization: Bearer {{token}}"
-X "POST"
-H "Content-Type: application/json"
-d '{"action": "START"}'

Example Response

{
  "status": "success"
}

get Charge Limit

Returns the current charge limit of the vehicle.

Required Permissions

read_charge_limit

Response Body

Name Type Description
limit number Indicates the level at which the vehicle will stop charging and be considered fully charged
get
https://api.smartcar.com/v1.0/vehicles/{{id}}/charge/limit

Example Request

curl https://api.smartcar.com/v{{version}}/vehicles/{{id}}/charge/limit
-H "Authorization: Bearer {{token}}"
-X "GET"

Example Response

{
  "limit": 0.8
}

post Charge Limit

Enable or disable the vehicle's charge limit setting, optionally changing this limit.

Required Permissions

control_charge_limit, control_charge_limit:enable, control_charge_limit:disable

Request Body

Name Type Required Description
action string true The action to take on the charge limit setting
limit number false The charge limit. The default will be the last set limit. This is unnecessary for the DISABLE action. Indicates the level at which the vehicle will stop charging and be considered fully charged

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}}/charge/limit

Example Request

curl https://api.smartcar.com/v{{version}}/vehicles/{{id}}/charge/limit
-H "Authorization: Bearer {{token}}"
-X "POST"
-H "Content-Type: application/json"
-d '{"action":"ENABLE", "limit": 0.9}'

Example Response

{
  "status": "success"
}

get Charge Schedule

Returns the current charge schedule of the vehicle.

Required Permissions

read_charge_schedule

Response Body

Name Type Description
state string Indicates the current state of the charge scheduler
startTime string The time the scheduler will begin charging (in HH:MM format where HH is a 24 hour clock in UTC time)
get
https://api.smartcar.com/v1.0/vehicles/{{id}}/charge/schedule

Example Request

curl https://api.smartcar.com/v{{version}}/vehicles/{{id}}/charge/schedule
-H "Authorization: Bearer {{token}}"
-X "GET"

Example Response

{
  "startTime": "18:30",
  "state": "ENABLED"
}

post Charge Schedule

Enable or disable the vehicle's charge schedule with a set time.

Required Permissions

control_charge_schedule, control_charge_schedule:enable, control_charge_schedule:disable

Request Body

Name Type Required Description
action string true The action to take on the charge scheduler
startTime string false The time the scheduler will begin charging (in HH:MM format where HH is a 24 hour clock in UTC time). This time will default to the previously set time. This property is unnecessary when sending the ' DISABLE ' action

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}}/charge/schedule

Example Request

curl https://api.smartcar.com/v{{version}}/vehicles/{{id}}/charge/schedule
-H "Authorization: Bearer {{token}}"
-X "POST"
-H "Content-Type: application/json"
-d '{"action": "ENABLE"}'

Example Response

{
  "status": "success"
}

get Charge Voltmeter

Returns the voltage of the electric vehicle's charger.

Required Permissions

read_charge_voltmeter

Response Body

Name Type Description
voltage number The current reading of the voltmeter
get
https://api.smartcar.com/v1.0/vehicles/{{id}}/charge/voltmeter

Example Request

curl https://api.smartcar.com/v{{version}}/vehicles/{{id}}/charge/voltmeter
-H "Authorization: Bearer {{token}}"
-X "GET"

Example Response

{
  "voltage": 350
}

get Charge Ammeter

Returns the amperage of the electric vehicle's charger.

Required Permissions

read_charge_ammeter

Response Body

Name Type Description
amperage number The current reading of the ammeter
get
https://api.smartcar.com/v1.0/vehicles/{{id}}/charge/ammeter

Example Request

curl https://api.smartcar.com/v{{version}}/vehicles/{{id}}/charge/ammeter
-H "Authorization: Bearer {{token}}"
-X "GET"

Example Response

{
  "amperage": 1000
}

get Climate

Returns the current state of the vehicle's climate control system.

Required Permissions

read_climate

Response Body

Name Type Description
temperature number The target temperature of the climate system
isOn boolean Indicates whether the climate control system is currently running
get
https://api.smartcar.com/v1.0/vehicles/{{id}}/climate

Example Request

curl https://api.smartcar.com/v{{version}}/vehicles/{{id}}/climate
-H "Authorization: Bearer {{token}}"
-X "GET"

Example Response

{
  "isOn": false,
  "temperature": 35.3
}

post Climate

Turn the climate control system on or off in addition to setting its temperature.

Required Permissions

control_climate, control_climate:start, control_climate:stop

Request Body

Name Type Required Description
action string true The action to take on the climate control system
temperature number false The temperature to set. The default will be the last set temperature. This is unnecessary for the STOP action. If the provided temperature is out of the bounds allowed by the climate control system, the actual temperature will be set to the minimum / maximum value allowed by the climate control system

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}}/climate

Example Request

curl https://api.smartcar.com/v{{version}}/vehicles/{{id}}/climate
-H "Authorization: Bearer {{token}}"
-X "POST"
-H "Content-Type: application/json"
-d '{"action": "START", "temperature": 28.5}'

Example Response

{
  "status": "success"
}

get Collision Sensor

Returns the current state of the vehicle's collision sensor.

Required Permissions

read_collision_sensor

Response Body

Name Type Description
isTriggered boolean Indicates whether the collision sensor was triggered
get
https://api.smartcar.com/v1.0/vehicles/{{id}}/collision_sensor

Example Request

curl https://api.smartcar.com/v{{version}}/vehicles/{{id}}/collision_sensor
-H "Authorization: Bearer {{token}}"
-X "GET"

Example Response

{
  "isTriggered": false
}

get Compass

Returns the current heading of the vehicle as indicated by the compass.

Required Permissions

read_compass

Response Body

Name Type Description
heading number The current compass heading
get
https://api.smartcar.com/v1.0/vehicles/{{id}}/compass

Example Request

curl https://api.smartcar.com/v{{version}}/vehicles/{{id}}/compass
-H "Authorization: Bearer {{token}}"
-X "GET"

Example Response

{
  "heading": 4.23
}

get Convertible Roof

Returns the state of the convertible vehicle's roof.

Required Permissions

read_convertible_roof

Response Body

Name Type Description
isOpen boolean Indicates whether the convertible roof is currently open
get
https://api.smartcar.com/v1.0/vehicles/{{id}}/convertible_roof

Example Request

curl https://api.smartcar.com/v{{version}}/vehicles/{{id}}/convertible_roof
-H "Authorization: Bearer {{token}}"
-X "GET"

Example Response

{
  "isOpen": false
}

post Convertible Roof

Control a convertible vehicle's roof.

Required Permissions

control_convertible_roof, control_convertible_roof:open, control_convertible_roof:close

Request Body

Name Type Required Description
action string true The action to take on the convertible roof

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}}/convertible_roof

Example Request

curl https://api.smartcar.com/v{{version}}/vehicles/{{id}}/convertible_roof
-H "Authorization: Bearer {{token}}"
-X "POST"
-H "Content-Type: application/json"
-d '{"action": "OPEN"}'

Example Response

{
  "status": "success"
}

get Cruise Control

Returns the state of the vehicle's cruise control system.

Required Permissions

read_cruise_control

Response Body

Name Type Description
isOn boolean Indicates whether the cruise control system is currently on and is set to a given speed
speed number The currently set speed
followDistance number The space to maintain from the vehicle ahead. Only available in vehicles featuring adaptive cruise control
get
https://api.smartcar.com/v1.0/vehicles/{{id}}/cruise_control

Example Request

curl https://api.smartcar.com/v{{version}}/vehicles/{{id}}/cruise_control
-H "Authorization: Bearer {{token}}"
-X "GET"

Example Response

{
  "followDistance": 200,
  "isOn": false,
  "speed": 100.3
}

get Dimensions

Returns the physical dimensions of the vehicle.

Required Permissions

read_dimensions

Response Body

Name Type Description
height number The height of the vehicle
width number The width of the vehicle
length number The length of the vehicle
weight number The weight of the vehicle
get
https://api.smartcar.com/v1.0/vehicles/{{id}}/dimensions

Example Request

curl https://api.smartcar.com/v{{version}}/vehicles/{{id}}/dimensions
-H "Authorization: Bearer {{token}}"
-X "GET"

Example Response

{
  "height": 3.4,
  "length": 3,
  "weight": 2000,
  "width": 2.2
}

get Child Safety Locks

Returns the state of the child safety lock for each door.

Required Permissions

read_child_safety_locks

Response Body

Name Type Description
childSafetyLocks array An array containing safety lock information for each door
get
https://api.smartcar.com/v1.0/vehicles/{{id}}/doors/child_safety_locks

Example Request

curl https://api.smartcar.com/v{{version}}/vehicles/{{id}}/doors/child_safety_locks
-H "Authorization: Bearer {{token}}"
-X "GET"

Example Response

{
  "childSafetyLocks": [
    {
      "isLocked": false,
      "location": "BACK_RIGHT"
    }
  ]
}

post Child Safety Locks

Lock or unlock the child safety lock on each door.

Required Permissions

control_child_safety_locks, control_child_safety_locks:lock, control_child_safety_locks:unlock

Request Body

Name Type Required Description
action string true The action to take on the child safety locks
childSafetyLocks array true An array of child safety locks

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}}/doors/child_safety_locks

Example Request

curl https://api.smartcar.com/v{{version}}/vehicles/{{id}}/doors/safety_locks
-H "Authorization: Bearer {{token}}"
-X "POST"
-d '{"action": "LOCK", "childSafetyLocks": [{"location": "BACK_LEFT"}]}'

Example Response

{
  "status": "success"
}

get Doors

Returns the state of the vehicle doors.

Required Permissions

read_doors

Response Body

Name Type Description
doors array An array containing information for each vehicle door
get
https://api.smartcar.com/v1.0/vehicles/{{id}}/doors

Example Request

curl https://api.smartcar.com/v{{version}}/vehicles/{{id}}/doors
-H "Authorization: Bearer {{token}}"
-X "GET"

Example Response

{
  "doors": [
    {
      "isOpen": false,
      "location": "FRONT_LEFT"
    }
  ]
}

get Drive Mode

Returns the state of the vehicle's drive mode.

Required Permissions

read_drive_mode

Response Body

Name Type Description
mode string The vehicle ' s current drive mode
get
https://api.smartcar.com/v1.0/vehicles/{{id}}/drive_mode

Example Request

curl https://api.smartcar.com/v{{version}}/vehicles/{{id}}/drive_mode
-H "Authorization: Bearer {{token}}"
-X "GET"

Example Response

{
  "mode": "COMFORT"
}

get Engine Coolant

Returns the state of the vehicle's engine coolant.

Required Permissions

read_engine_coolant

Response Body

Name Type Description
level number Coolant remaining
temperature number The temperature of the coolant
get
https://api.smartcar.com/v1.0/vehicles/{{id}}/engine/coolant

Example Request

curl https://api.smartcar.com/v{{version}}/vehicles/{{id}}/engine/coolant
-H "Authorization: Bearer {{token}}"
-X "GET"

Example Response

{
  "level": 0.78,
  "temperature": 94.4
}

get Engine Hood

Indicates whether the hood is open or closed.

Required Permissions

read_engine_hood

Response Body

Name Type Description
isOpen boolean Indicates whether the engine hood is currently open
get
https://api.smartcar.com/v1.0/vehicles/{{id}}/engine/hood

Example Request

curl https://api.smartcar.com/v{{version}}/vehicles/{{id}}/engine/hood
-H "Authorization: Bearer {{token}}"
-X "GET"

Example Response

{
  "isOpen": false
}

post Engine Hood

Open or close the vehicle's engine hood. The engine hood may be located in the front or rear depending on where the engine is located.

Required Permissions

control_engine_hood, control_engine_hood:open, control_engine_hood:close

Request Body

Name Type Required Description
action string true The action to take on the engine hood

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}}/engine/hood

Example Request

curl https://api.smartcar.com/v{{version}}/vehicles/{{id}}/engine/hood
-H "Authorization: Bearer {{token}}"
-X "POST"
-H "Content-Type: application/json"
-d '{"action": "OPEN"}'

Example Response

{
  "status": "success"
}

get Engine Oil

Returns the state of the vehicle's engine oil.

Required Permissions

read_engine_oil

Response Body

Name Type Description
changeIndicator boolean Indicates whether the oil change indicator is on
percentRemaining number The amount of oil remaining
lifeRemaining number The amount of oil life remaining. Oil life is based on the current quality of the oil, and may be measured using electric conductivity, viscosity, soot concentration or wetness
pressure number The current oil pressure
temperature number The oil temperature
get
https://api.smartcar.com/v1.0/vehicles/{{id}}/engine/oil

Example Request

curl https://api.smartcar.com/v{{version}}/vehicles/{{id}}/engine/oil
-H "Authorization: Bearer {{token}}"
-X "GET"

Example Response

{
  "changeIndicator": false,
  "lifeRemaining": 0.35,
  "percentRemaining": 0.78,
  "pressure": 275.7,
  "temperature": 94.4
}

get Engine Throttle

Returns the position of the vehicle's engine throttle.

Required Permissions

read_engine_throttle

Response Body

Name Type Description
percentOpen number The position of the engine throttle
get
https://api.smartcar.com/v1.0/vehicles/{{id}}/engine/throttle

Example Request

curl https://api.smartcar.com/v{{version}}/vehicles/{{id}}/engine/throttle
-H "Authorization: Bearer {{token}}"
-X "GET"

Example Response

{
  "percentOpen": 0.35
}

get Engine

Returns the current state of the vehicle's engine.

Required Permissions

read_engine

Response Body

Name Type Description
isOn boolean Indicates whether the vehicle ' s engine is on
get
https://api.smartcar.com/v1.0/vehicles/{{id}}/engine

Example Request

curl https://api.smartcar.com/v{{version}}/vehicles/{{id}}/engine
-H "Authorization: Bearer {{token}}"
-X "GET"

Example Response

{
  "isOn": false
}

get Gyroscope

Returns the vehicle's current gyroscope reading.

Required Permissions

read_gyroscope

Response Body

Name Type Description
yawRate number The current yaw rate of the vehicle
get
https://api.smartcar.com/v1.0/vehicles/{{id}}/gyroscope

Example Request

curl https://api.smartcar.com/v{{version}}/vehicles/{{id}}/gyroscope
-H "Authorization: Bearer {{token}}"
-X "GET"

Example Response

{
  "yawRate": 20
}

get Ignition

Returns the current state of the vehicle's ignition/accessory power.

Required Permissions

read_ignition

Response Body

Name Type Description
state string Indicates the state of the vehicle ' s ignition. ACCESSORY: the vehicle has the first-level of accessory power turned on (the first turn in a standard vehicle or first press in a keyless vehicle) ON: the vehicle has the second-level of accessory power turned on (the second turn in a standard vehicle or second press in a keyless vehicle); note: the vehicle ' s engine may or may not be running while in this state
get
https://api.smartcar.com/v1.0/vehicles/{{id}}/ignition

Example Request

curl https://api.smartcar.com/v{{version}}/vehicles/{{id}}/ignition
-H "Authorization: Bearer {{token}}"
-X "GET"

Example Response

{
  "state": "ON"
}

post Ignition

Start or stop the vehicle's engine/accessory modes. This also includes the vehicles with electric motors. `START` allows the driver to start moving the vehicle.

Required Permissions

control_ignition, control_ignition:start, control_ignition:on, control_ignition:accessory, control_ignition:off

Request Body

Name Type Required Description
action string true The action to take on the ignition. The ` START ` action will result in the ignition state being set to ` ON `

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}}/ignition

Example Request

curl https://api.smartcar.com/v{{version}}/vehicles/{{id}}/ignition
-H "Authorization: Bearer {{token}}"
-X "POST"
-d '{"action": "START"}'

Example Response

{
  "status": "success"
}

get Fuel

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

Required Permissions

read_fuel

Response Body

Name Type Description
range number The estimated remaining distance the car can travel
percentRemaining number The remaining level of fuel in the tank
amountRemaining number The amount of fuel in the tank
get
https://api.smartcar.com/v1.0/vehicles/{{id}}/fuel

Example Request

curl https://api.smartcar.com/v{{version}}/vehicles/{{id}}/fuel
-H "Authorization: Bearer {{token}}"
-X "GET"

Example Response

{
  "amountRemaining": 53.2,
  "percentRemaining": 0.3,
  "range": 40.5
}

post Horn

Honk the vehicle's horn.

Required Permissions

control_horn, control_horn:honk

Request Body

Name Type Required Description
action string true The action to take on the horn

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}}/horn

Example Request

curl https://api.smartcar.com/v{{version}}/vehicles/{{id}}/horn
-H "Authorization: Bearer {{token}}"
-X "POST"
-H "Content-Type: application/json"
-d '{"action": "HONK"}'

Example Response

{
  "status": "success"
}

get Hazard Lights

Returns the state of the vehicle's hazard lights.

Required Permissions

read_hazard

Response Body

Name Type Description
isOn boolean Indicates whether the hazard lights are currently on
get
https://api.smartcar.com/v1.0/vehicles/{{id}}/lights/hazard

Example Request

curl https://api.smartcar.com/v{{version}}/vehicles/{{id}}/lights/hazard
-H "Authorization: Bearer {{token}}"
-X "GET"

Example Response

{
  "isOn": false
}

get Headlights

Returns the state of the vehicle's headlights.

Required Permissions

read_headlights

Response Body

Name Type Description
headlights array An array containing information for each headlight
get
https://api.smartcar.com/v1.0/vehicles/{{id}}/lights/headlights

Example Request

curl https://api.smartcar.com/v{{version}}/vehicles/{{id}}/lights/headlight
-H "Authorization: Bearer {{token}}"
-X "GET"

Example Response

{
  "headlights": [
    {
      "isOn": true,
      "type": "HIGH_BEAM"
    }
  ]
}

post Headlights

Control the vehicle's headlights.

Required Permissions

control_headlights, control_headlights:flash, control_headlights:on, control_headlights:off

Request Body

Name Type Required Description
action string true The action to take on the headlights
type string true The type of headlights to take action on

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}}/lights/headlights

Example Request

curl https://api.smartcar.com/v{{version}}/vehicles/{{id}}/lights/headlights
-H "Authorization: Bearer {{token}}"
-X "POST"
-H "Content-Type: application/json"
-d '{"action": "FLASH", "type": "LOW_BEAM"}'

Example Response

{
  "status": "success"
}

get Interior Lights

Returns the state of the vehicle's interior lights.

Required Permissions

read_interior_lights

Response Body

Name Type Description
lights array An array containing information on each light
get
https://api.smartcar.com/v1.0/vehicles/{{id}}/lights/interior

Example Request

curl https://api.smartcar.com/v{{version}}/vehicles/{{id}}/lights/interior
-H "Authorization: Bearer {{token}}"
-X "GET"

Example Response

{
  "lights": [
    {
      "isOn": true,
      "location": "FRONT_RIGHT"
    }
  ]
}

get Turn Indicator

Returns the state of the vehicle's turn indicator.

Required Permissions

read_turn_indicator

Response Body

Name Type Description
state string Current state of the turn indicator
get
https://api.smartcar.com/v1.0/vehicles/{{id}}/lights/turn_indicator

Example Request

curl https://api.smartcar.com/v{{version}}/vehicles/{{id}}/lights/turn_indicator
-H "Authorization: Bearer {{token}}"
-X "GET"

Example Response

{
  "state": "LEFT"
}

get Location

Returns the location of the vehicle in terms of coordinates.

Required Permissions

read_location

Response Body

Name Type Description
latitude number The latitude
longitude number The longitude
get
https://api.smartcar.com/v1.0/vehicles/{{id}}/location

Example Request

curl https://api.smartcar.com/v{{version}}/vehicles/{{id}}/location
-H "Authorization: Bearer {{token}}"
-X "GET"

Example Response

{
  "latitude": 37.4292,
  "longitude": 122.1381
}

get Side View Mirrors

Returns the current side view mirror settings of the vehicle.

Required Permissions

read_side_view_mirrors

Response Body

Name Type Description
mirrors array An array containing information on each mirror
get
https://api.smartcar.com/v1.0/vehicles/{{id}}/mirrors/side_view

Example Request

curl https://api.smartcar.com/v{{version}}/vehicles/{{id}}/mirrors/side_view
-H "Authorization: Bearer {{token}}"
-X "GET"

Example Response

{
  "mirrors": [
    {
      "location": "RIGHT",
      "xTilt": 0.1,
      "yTilt": 0.1
    }
  ]
}

post Side View Mirrors

Set the current side view mirror settings of the vehicle.

Required Permissions

control_side_view_mirrors

Request Body

Name Type Required Description
action string true The action to take on the mirrors
mirrors array true An array containing information on each mirror

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}}/mirrors/side_view

Example Request

curl https://api.smartcar.com/v{{version}}/vehicles/{{id}}/mirrors/side_view
-H "Authorization: Bearer {{token}}"
-X "POST"
-H "Content-Type: application/json"
-d '{"action": "TILT", mirrors: [{"location": "LEFT", "xTilt": 0.3, "yTilt": 0.5"}]}'

Example Response

{
  "status": "success"
}

get Navigation

Returns the status of the navigation system's current route.

Required Permissions

read_navigation

Response Body

Name Type Description
arrivalTime dateTime Estimated arrival time at destination
timeRemaining integer Estimated time remaining to reach destination (ISO 8601 format)
distance number Current distance from vehicle to destination
destination object The location of the destination
get
https://api.smartcar.com/v1.0/vehicles/{{id}}/navigation

Example Request

curl https://api.smartcar.com/v{{version}}/vehicles/{{id}}/navigation
-H "Authorization: Bearer {{token}}"
-X "GET"

Example Response

{
  "arrivalTime": "2017-02-23T16:32:39.000Z",
  "destination": {
    "latitude": 37.4292,
    "longitude": 122.1381
  },
  "distance": 32.3,
  "timeRemaining": 1565
}

post Navigation

Start or cancel the navigation destination.

Required Permissions

control_navigation, control_navigation:start, control_navigation:cancel

Request Body

Name Type Required Description
action string true The action to take on the navigation system
destination object false The location to set the navigation system to. Only used when the action is ` START `

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}}/navigation

Example Request

curl https://api.smartcar.com/v{{version}}/vehicles/{{id}}/navigation
-H "Authorization: Bearer {{token}}"
-X "POST"
-H "Content-Type: application/json"
-d '{"action": "START", "destination": {"latitude": 37.3996847, "longitude": -122.0476105}}'

Example Response

{
  "status": "success"
}

get Odometer Trips

Returns the vehicle's current odometer trips.

Required Permissions

read_odometer_trips

Response Body

Name Type Description
trips array An array containing information on each trip
get
https://api.smartcar.com/v1.0/vehicles/{{id}}/odometer/trips

Example Request

curl https://api.smartcar.com/v{{version}}/vehicles/{{id}}/odometer/trips
-H "Authorization: Bearer {{token}}"
-X "GET"

Example Response

{
  "trips": [
    {
      "distance": 32.11,
      "label": "a"
    }
  ]
}

get Odometer

Returns the vehicle's current odometer total.

Required Permissions

read_odometer

Response Body

Name Type Description
distance number The current odometer of the vehicle
get
https://api.smartcar.com/v1.0/vehicles/{{id}}/odometer

Example Request

curl https://api.smartcar.com/v{{version}}/vehicles/{{id}}/odometer
-H "Authorization: Bearer {{token}}"
-X "GET"

Example Response

{
  "distance": 104.32
}

post Panic Mode

Start or stop the vehicle's panic mode.

Required Permissions

control_panic, control_panic:start, control_panic:stop

Request Body

Name Type Required Description
action string true The action to take on the vehicle ' s panic mode

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}}/panic

Example Request

curl https://api.smartcar.com/v{{version}}/vehicles/{{id}}/panic
-H "Authorization: Bearer {{token}}"
-X "POST"
-H "Content-Type: application/json"
-d "{{body}}"

Example Response

{
  "status": "success"
}

get Accelerator Pedal

Returns the position of the vehicle's accelerator pedal.

Required Permissions

read_accelerator_pedal

Response Body

Name Type Description
percentDepressed number The position of the pedal
get
https://api.smartcar.com/v1.0/vehicles/{{id}}/pedals/accelerator

Example Request

curl https://api.smartcar.com/v{{version}}/vehicles/{{id}}/pedals/accelerator
-H "Authorization: Bearer {{token}}"
-X "GET"

Example Response

{
  "percentDepressed": 0.35
}

get Brake Pedal

Returns the position of the vehicle's brake pedal.

Required Permissions

read_brake_pedal

Response Body

Name Type Description
percentDepressed number The position of the brake pedal
get
https://api.smartcar.com/v1.0/vehicles/{{id}}/pedals/brake

Example Request

curl https://api.smartcar.com/v{{version}}/vehicles/{{id}}/pedals/brake
-H "Authorization: Bearer {{token}}"
-X "GET"

Example Response

{
  "percentDepressed": 0.35
}

get Application Permissions

Returns a paged list of all permissions currently associated with this vehicle.

Response Body

Name Type Description
permissions array An array of permissions
paging object Metadata about the current list of elements
get
https://api.smartcar.com/v1.0/vehicles/{{id}}/permissions

Example Request

curl https://api.smartcar.com/v{{version}}/vehicles/{{id}}/permissions
-H "Authorization: Bearer {{token}}"
-X "GET"

Example Response

{
  "paging": {
    "count": 25,
    "offset": 10
  },
  "permissions": [
    "read_vehicle_info"
  ]
}

post Charge Port

Open the lid of the charge port.

Required Permissions

control_charge_port, control_charge_port:open, control_charge_port:close

Request Body

Name Type Required Description
action string true The action to take on the charge port

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}}/ports/charge

Example Request

curl https://api.smartcar.com/v{{version}}/vehicles/{{id}}/ports/charge
-H "Authorization: Bearer {{token}}"
-X "POST"
-H "Content-Type: application/json"
-d '{"action": "OPEN"}'

Example Response

{
  "status": "success"
}

post Fuel Port

Open the lid of the fuel port.

Required Permissions

control_fuel_port, control_fuel_port:open, control_fuel_port:close

Request Body

Name Type Required Description
action string true The action to take on the fuel port

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}}/ports/fuel

Example Request

curl https://api.smartcar.com/v{{version}}/vehicles/{{id}}/ports/fuel
-H "Authorization: Bearer {{token}}"
-X "POST"
-H "Content-Type: application/json"
-d '{"action": "OPEN"}'

Example Response

{
  "status": "success"
}

get Rain Sensor

Returns the status of the vehicle's rain sensor.

Required Permissions

read_rain_sensor

Response Body

Name Type Description
isRaining boolean Indicates whether the rain sensor is currently detecting rain
get
https://api.smartcar.com/v1.0/vehicles/{{id}}/rain_sensor

Example Request

curl https://api.smartcar.com/v{{version}}/vehicles/{{id}}/rain_sensor
-H "Authorization: Bearer {{token}}"
-X "GET"

Example Response

{
  "isRaining": true
}

get Seats

Returns the state of the vehicle's seats.

Required Permissions

read_seats

Response Body

Name Type Description
seats array An array containing information on each seat
get
https://api.smartcar.com/v1.0/vehicles/{{id}}/seats

Example Request

curl https://api.smartcar.com/v{{version}}/vehicles/{{id}}/seats
-H "Authorization: Bearer {{token}}"
-X "GET"

Example Response

{
  "seats": [
    {
      "isBuckled": false,
      "isOccupied": false,
      "location": "FRONT_MIDDLE"
    }
  ]
}

get Security

Returns whether the vehicle is locked or unlocked.

Required Permissions

read_security

Response Body

Name Type Description
isLocked boolean Indicates whether the vehicle is locked/unlocked
get
https://api.smartcar.com/v1.0/vehicles/{{id}}/security

Example Request

curl https://api.smartcar.com/v{{version}}/vehicles/{{id}}/security
-H "Authorization: Bearer {{token}}"
-X "GET"

Example Response

{
  "isLocked": true
}

post Security

Lock or unlock the vehicle.

Required Permissions

control_security, control_security:unlock, control_security:lock

Request Body

Name Type Required Description
action string true The action to take on the security system

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/v{{version}}/vehicles/{{id}}/security
-H "Authorization: Bearer {{token}}"
-X "POST"
-H "Content-Type: application/json"
-d '{"action": "LOCK"}'

Example Response

{
  "status": "success"
}

get SLI Battery

Returns the state of the vehicle's Starting, Lighting, Ignition (SLI) battery. This is often referred to as the "battery" in vehicles with an Internal Combustion Engine (ICE).

Required Permissions

read_sli_battery

Response Body

Name Type Description
current number The battery current
voltage number The battery voltage
percentRemaining number The remaining level of charge in the battery
get
https://api.smartcar.com/v1.0/vehicles/{{id}}/sli_battery

Example Request

curl https://api.smartcar.com/v{{version}}/vehicles/{{id}}/sli_battery
-H "Authorization: Bearer {{token}}"
-X "GET"

Example Response

{
  "current": 0.05,
  "percentRemaining": 0.3,
  "voltage": 12.6
}

get Speedometer

Returns the vehicle's current speed.

Required Permissions

read_speedometer

Response Body

Name Type Description
speed number The vehicle ' s current speed
get
https://api.smartcar.com/v1.0/vehicles/{{id}}/speedometer

Example Request

curl https://api.smartcar.com/v{{version}}/vehicles/{{id}}/speedometer
-H "Authorization: Bearer {{token}}"
-X "GET"

Example Response

{
  "speed": 104.32
}

get Steering Wheel

Returns the location and orientation of the steering wheel.

Required Permissions

read_steering_wheel

Response Body

Name Type Description
location string Position of the steering wheel relative to the vehicle
turnPercent number The turn orientation of the vehicle. A value of 0 indicates the vehicle is pointed directly ahead. A value of -1 indicates the vehicle is turned fully to the left. A value of 1 indicates the vehicle is turned fully to the right
get
https://api.smartcar.com/v1.0/vehicles/{{id}}/steering_wheel

Example Request

curl https://api.smartcar.com/v{{version}}/vehicles/{{id}}/steering_wheel
-H "Authorization: Bearer {{token}}"
-X "GET"

Example Response

{
  "location": "LEFT",
  "turnPercent": 0.25
}

get Sunroof

Returns the state of the vehicle's sunroof.

Required Permissions

read_sunroof

Response Body

Name Type Description
state string Indicates the current state of the vehicle ' s sunroof
percentOpen number Indicates how far the sunroof is open. This is meaningful only when the sunroof ' s state is ' OPEN ' . If the state is ' VENTED ' or ' CLOSED ' , this will always be 0. Note that a ' VENTED ' sunroof will be slightly ajar
get
https://api.smartcar.com/v1.0/vehicles/{{id}}/sunroof

Example Request

curl https://api.smartcar.com/v{{version}}/vehicles/{{id}}/sunroof
-H "Authorization: Bearer {{token}}"
-X "GET"

Example Response

{
  "percentOpen": 0.25,
  "state": "CLOSED"
}

post Sunroof

Control the vehicle's sunroof.

Required Permissions

control_sunroof, control_sunroof:open, control_sunroof:close, control_sunroof:vent

Request Body

Name Type Required Description
action string true The action to take on the sunroof
percentOpen number false Indicates how far the sunroof should be opened. Can only be used in conjunction with the ' OPEN ' action. By default, the sunroof will fully open

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}}/sunroof

Example Request

curl https://api.smartcar.com/v{{version}}/vehicles/{{id}}/sunroof
-H "Authorization: Bearer {{token}}"
-X "POST"
-H "Content-Type: application/json"
-d '{"action": "OPEN"}'

Example Response

{
  "status": "success"
}

get Tachometer

Returns the RPM gauge indicating the speed of the engine.

Required Permissions

read_tachometer

Response Body

Name Type Description
engineSpeed number Current speed of the engine
get
https://api.smartcar.com/v1.0/vehicles/{{id}}/tachometer

Example Request

curl https://api.smartcar.com/v{{version}}/vehicles/{{id}}/tachometer
-H "Authorization: Bearer {{token}}"
-X "GET"

Example Response

{
  "engineSpeed": 1500
}

get Outside Temperature

Returns the current reading of the vehicle's exterior temperature sensors.

Required Permissions

read_exterior_thermistor

Response Body

Name Type Description
temperature number Temperature
get
https://api.smartcar.com/v1.0/vehicles/{{id}}/thermistors/exterior

Example Request

curl https://api.smartcar.com/v{{version}}/vehicles/{{id}}/thermistors/exterior
-H "Authorization: Bearer {{token}}"
-X "GET"

Example Response

{
  "temperature": 35.2
}

get Inside Temperature

Returns the current reading of the vehicle's interior temperature sensors.

Required Permissions

read_interior_thermistor

Response Body

Name Type Description
temperature number Temperature
get
https://api.smartcar.com/v1.0/vehicles/{{id}}/thermistors/interior

Example Request

curl https://api.smartcar.com/v{{version}}/vehicles/{{id}}/thermistors/interior
-H "Authorization: Bearer {{token}}"
-X "GET"

Example Response

{
  "temperature": 35.2
}

get Tires

Returns the state of the vehicle's tires.

Required Permissions

read_tires

Response Body

Name Type Description
tires array An array containing information on each tire
get
https://api.smartcar.com/v1.0/vehicles/{{id}}/tires

Example Request

curl https://api.smartcar.com/v{{version}}/vehicles/{{id}}/tires
-H "Authorization: Bearer {{token}}"
-X "GET"

Example Response

{
  "tires": [
    {
      "location": "FRONT_LEFT",
      "pressure": 219.3
    }
  ]
}

get Transmission Fluid

Returns the state of the vehicle's transmission fluid.

Required Permissions

read_transmission_fluid

Response Body

Name Type Description
temperature number The current temperature of the fluid
wear number The quality of the fluid. 0 indicates fresh/unworn fluid. 1 indicates fully worn
get
https://api.smartcar.com/v1.0/vehicles/{{id}}/transmission/fluid

Example Request

curl https://api.smartcar.com/v{{version}}/vehicles/{{id}}/transmission/fluid
-H "Authorization: Bearer {{token}}"
-X "GET"

Example Response

{
  "temperature": 20.3,
  "wear": 0.35
}

get Transmission

Returns the type of transmission the vehicle has and its current state.

Required Permissions

read_transmission

Response Body

Name Type Description
type string The type of engine
state string The current state of the vehicle
get
https://api.smartcar.com/v1.0/vehicles/{{id}}/transmission

Example Request

curl https://api.smartcar.com/v{{version}}/vehicles/{{id}}/transmission
-H "Authorization: Bearer {{token}}"
-X "GET"

Example Response

{
  "state": "PARK",
  "type": "MANUAL"
}

get Trips

Returns a paged list of all trips. A trip is the duration between ignition on and ignition off. Trips are sorted from newest to oldest.

Required Permissions

read_trips

Response Body

Name Type Description
trips array An array containing information on each trip
paging object Metadata about the current list of elements
get
https://api.smartcar.com/v1.0/vehicles/{{id}}/trips

Example Request

curl https://api.smartcar.com/v{{version}}/vehicles/{{id}}/trips
-H "Authorization: Bearer {{token}}"
-X "GET"

Example Response

{
  "paging": {
    "count": 25,
    "offset": 10
  },
  "trips": [
    {
      "end": {
        "battery": {
          "percentRemaining": 0.15,
          "range": 24.14
        },
        "fuel": {
          "amountRemaining": 12.42,
          "percentRemaining": 0.29,
          "range": 116.02
        },
        "location": {
          "latitude": 37.3678,
          "longitude": -122.0384
        },
        "odometer": {
          "distance": 1063.63
        },
        "timestamp": "2017-02-22T16:41:56-0800"
      },
      "id": "idzvGyNYsYxrvDUrih85Kv6+nK7XC4YzrrLNXzZNuoJA",
      "start": {
        "battery": {
          "percentRemaining": 0.3,
          "range": 48.28
        },
        "fuel": {
          "amountRemaining": 12.85,
          "percentRemaining": 0.3,
          "range": 120.02
        },
        "location": {
          "latitude": 37.3918,
          "longitude": -122.0476
        },
        "odometer": {
          "distance": 1044.32
        },
        "timestamp": "2017-02-22T16:28:57-0800"
      },
      "stats": {
        "averageSpeed": 35.2,
        "battery": {
          "percentConsumed": 0.15
        },
        "distance": 19.31,
        "duration": 779,
        "fuel": {
          "amountConsumed": 0.43,
          "percentConsumed": 0.01
        }
      }
    }
  ]
}

get Single Trip

Returns information on a single trip. A trip is the duration between ignition on and ignition off.

Required Permissions

read_trips

Response Body

Name Type Description
id string Unique identifier of the trip
start object Snapshot of vehicle status at the start of a trip
end object Snapshot of vehicle status at the end of a trip
stats object Summary statistics calculated from start and end snapshots
get
https://api.smartcar.com/v1.0/vehicles/{{id}}/trips/{{tid}}

Example Request

curl https://api.smartcar.com/v{{version}}/vehicles/{{id}}/trips/{{tid}}
-H "Authorization: Bearer {{token}}"
-X "GET"

Example Response

{
  "end": {
    "battery": {
      "percentRemaining": 0.15,
      "range": 24.14
    },
    "fuel": {
      "amountRemaining": 12.42,
      "percentRemaining": 0.29,
      "range": 116.02
    },
    "location": {
      "latitude": 37.3678,
      "longitude": -122.0384
    },
    "odometer": {
      "distance": 1063.63
    },
    "timestamp": "2017-02-22T16:41:56-0800"
  },
  "id": "idzvGyNYsYxrvDUrih85Kv6+nK7XC4YzrrLNXzZNuoJA",
  "start": {
    "battery": {
      "percentRemaining": 0.3,
      "range": 48.28
    },
    "fuel": {
      "amountRemaining": 12.85,
      "percentRemaining": 0.3,
      "range": 120.02
    },
    "location": {
      "latitude": 37.3918,
      "longitude": -122.0476
    },
    "odometer": {
      "distance": 1044.32
    },
    "timestamp": "2017-02-22T16:28:57-0800"
  },
  "stats": {
    "averageSpeed": 35.2,
    "battery": {
      "percentConsumed": 0.15
    },
    "distance": 19.31,
    "duration": 779,
    "fuel": {
      "amountConsumed": 0.43,
      "percentConsumed": 0.01
    }
  }
}

get Front Trunk

Returns the state of the vehicle's front trunk.

Required Permissions

read_front_trunk

Response Body

Name Type Description
isOpen boolean Indicates whether the front trunk is currently open
get
https://api.smartcar.com/v1.0/vehicles/{{id}}/trunks/front

Example Request

curl https://api.smartcar.com/v{{version}}/vehicles/{{id}}/trunks/front
-H "Authorization: Bearer {{token}}"
-X "GET"

Example Response

{
  "isOpen": false
}

post Front Trunk

Open or close the vehicle's front trunk.

Required Permissions

control_front_trunk, control_front_trunk:open, control_front_trunk:close

Request Body

Name Type Required Description
action string true The action to take on the front trunk

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}}/trunks/front

Example Request

curl https://api.smartcar.com/v{{version}}/vehicles/{{id}}/trunks/front
-H "Authorization: Bearer {{token}}"
-X "POST"
-H "Content-Type: application/json"
-d '{"action": "OPEN"}'

Example Response

{
  "status": "success"
}

get Rear Trunk

Returns the state of the vehicle's rear trunk.

Required Permissions

read_rear_trunk

Response Body

Name Type Description
isOpen boolean Indicates whether the rear trunk is currently open
get
https://api.smartcar.com/v1.0/vehicles/{{id}}/trunks/rear

Example Request

curl https://api.smartcar.com/v{{version}}/vehicles/{{id}}/trunks/rear
-H "Authorization: Bearer {{token}}"
-X "GET"

Example Response

{
  "isOpen": false
}

post Rear Trunk

Open or close the vehicle's rear trunk.

Required Permissions

control_rear_trunk, control_rear_trunk:open, control_rear_trunk:close

Request Body

Name Type Required Description
action string true The action to take on the rear trunk

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}}/trunks/rear

Example Request

curl https://api.smartcar.com/v{{version}}/vehicles/{{id}}/trunks/rear
-H "Authorization: Bearer {{token}}"
-X "POST"
-H "Content-Type: application/json"
-d '{"action": "OPEN"}'

Example Response

{
  "status": "success"
}

get VIN

Returns the vehicle's manufacturer identifier.

Required Permissions

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/v{{version}}/vehicles/{{id}}/vin
-H "Authorization: Bearer {{token}}"
-X "GET"

Example Response

{
  "vin": "1234A67Q90F2T4567"
}

get Washer Fluid

Returns the state of the windshield washer fluid.

Required Permissions

read_washer_fluid

Response Body

Name Type Description
percentRemaining number Washer fluid remaining
get
https://api.smartcar.com/v1.0/vehicles/{{id}}/washer_fluid

Example Request

curl https://api.smartcar.com/v{{version}}/vehicles/{{id}}/washer_fluid
-H "Authorization: Bearer {{token}}"
-X "GET"

Example Response

{
  "percentRemaining": 0.37
}

get Wheel Speeds

Returns wheel speed information.

Required Permissions

read_wheel_speeds

Response Body

Name Type Description
wheelSpeeds array An array containing speed information about each wheel
get
https://api.smartcar.com/v1.0/vehicles/{{id}}/wheels/speeds

Example Request

curl https://api.smartcar.com/v{{version}}/vehicles/{{id}}/wheels/speeds
-H "Authorization: Bearer {{token}}"
-X "GET"

Example Response

{
  "wheelSpeeds": [
    {
      "location": "FRONT_LEFT",
      "speed": 20.42
    }
  ]
}

get Wheels

Returns wheel information.

Required Permissions

read_wheels

Response Body

Name Type Description
wheels array An array containing information about each wheel
get
https://api.smartcar.com/v1.0/vehicles/{{id}}/wheels

Example Request

curl https://api.smartcar.com/v{{version}}/vehicles/{{id}}/wheels
-H "Authorization: Bearer {{token}}"
-X "GET"

Example Response

{
  "wheels": [
    {
      "diameter": 48.6,
      "location": "FRONT_RIGHT"
    }
  ]
}

get Windows

Returns window information.

Required Permissions

read_windows

Response Body

Name Type Description
windows array An array containing information about each window
get
https://api.smartcar.com/v1.0/vehicles/{{id}}/windows

Example Request

curl https://api.smartcar.com/v{{version}}/vehicles/{{id}}/windows
-H "Authorization: Bearer {{token}}"
-X "GET"

Example Response

{
  "windows": [
    {
      "isLocked": true,
      "location": "CENTER_LEFT",
      "percentOpen": 0.35
    }
  ]
}

post Windows

Control the vehicle's windows.

Required Permissions

control_windows, control_windows:open, control_windows:close, control_windows:lock, control_windows:unlock

Request Body

Name Type Required Description
action string true The action to take on the windows
windows array true An array of Window objects. Only the specified windows will be affected

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}}/windows

Example Request

curl https://api.smartcar.com/v{{version}}/vehicles/{{id}}/windows
-H "Authorization: Bearer {{token}}"
-X "POST"
-H "Content-Type: application/json"
-d '{"action": "CLOSE", "windows": [{"location": "FRONT_RIGHT"}]}'

Example Response

{
  "status": "success"
}
Show examples in: