Vehicles

A representation of a real-world car or truck.

AddVehicle

Link a Vehicle created by one User to another target User. Where the target User is the User that will be linked. A single Vehicle can be associated with many different Users.

Request

curl -L -X POST 'https://{DOMAIN}/voyorequest/AddVehicle

-d 'user_key={USER_KEY}&vehicle_key={VEHICLE_KEY}&target_key={TARGET_KEY}'
-H 'Accept: application/json'
-H 'Authorization: Bearer {APIKEY}'

Parameter	Description
`user_key`	Unique key belonging to a User that is already linked to provided Vehicle.
`target_key`	Unique key belonging to the User the Vehicle will be linked to.
`vehicle_key`	Unique key belonging to the provided Vehicle.

Error Responses

    HTTP/1.1 400 Bad Request
    HTTP/1.1 401 Unauthorized

// A user matching target key was not found
{ "error":"Target user does not exist!" }

// Target user has been deleted
{ "error":"Target user no longer valid!" }

// A vehicle matching provided key does not exist or no longer exists
{ "error":"Vehicle does not exist!" }

// Target user is not part of your network
{ "error":"Unauthorized user!" }

Success Responses

Vehicle was linked successfully.

{ "error":"Success!" }

CreateVehicle

Creates a Vehicle based on the provided VIN. A Vehicle becomes associated automatically with a provided User.

The following attributes are filled in automatically based on VIN, but can be changed later via UpdateVehicle:
1. Make
2. Model
3. Vehicle Year
4. Name

If the Setting automate_intervals is enabled a series of predefined Service Intervals will be created. If the Settings automate_intervals and user_defined_intervals are both enabled, all Service Interval Settings will be applied to create a series of user defined Service Intervals.

Request

curl -L -X POST 'https://{DOMAIN}/voyorequest/CreateVehicle

-d 'user_key={USER_KEY}&vin={VIN}&odometer={ODOMETER}'
-H 'Accept: application/json'
-H 'Authorization: Bearer {APIKEY}'

Parameter	Description	Requirement
`user_key`	Unique key belonging to provided User.	Required
`vin`	Valid 17 digit Vehicle Identification Number.	Required
`odometer`	Current odometer reading (expected to be in km).	Optional

If odometer is provided and automate_intervals is enabled, Service Intervals will be created based on provided. If odometer is not provided Service Intervals can still be automatically generated for mileage at a later time via UpdateVehicle.

Error Responses

Error responses are returned when required inputs are missing or invalid. Common issues include missing VIN, improperly formatted VIN (must be a 17-character string), or using an invalid VIN.

    HTTP/1.1 400 Bad Request

/// Can not create a "Vehicle" without a VIN
{ "error":"Requires VIN!" }

/// A valid VIN is a 17 character string
{ "error":"A valid VIN is 17 characters!" }

// VIN can not be decoded
{ "error":"Not a valid VIN!" }

Success Responses

On success, vehicle_key will be returned. This key is an important identifier used to distinguish between Vehicles.

{ "error":"Success!", "vehicle_key":"" }

DeleteVehicle

Invalidates a created Vehicle. A deleted Vehicle will impact any and all associated Users. The Vehicle must be in the network of the provided User.

Request

curl -L -X POST 'https://{DOMAIN}/voyorequest/DeleteVehicle

-d 'user_key={USER_KEY}&vehicle_key={VEHICLE_KEY}'
-H 'Accept: application/json'
-H 'Authorization: Bearer {APIKEY}'

Parameter	Description
`user_key`	Unique key belonging to provided User.
`vehicle_key`	Unique key belonging to Vehicle to be deleted.

Error Responses

    HTTP/1.1 400 Bad Request

/// Could not find vehicle matching provided key
{ "error":"Vehicle does not exist!" }

Success Responses

Vehicle was deleted successfully.

{ "error":"Success!" }

GetVehicles

Get a list of all Vehicles associated with the requested user_key.

Request

curl -L -X POST 'https://{DOMAIN}/voyorequest/GetVehicles

-d 'user_key={USER_KEY}'
-H 'Accept: application/json'
-H 'Authorization: Bearer {APIKEY}'

Parameter	Description
`user_key`	Unique key belonging to provided User.

Example Response

Response vehicles can be empty if the provided user_key has no Vehicles associated with it.

{ 
    "error":"Success!", "vehicles":[
        {
            "vin":"",
            "latitude":"",
            "longitude":"",
            "vehicle_name":"",
            "make":"",
            "model":"",
            "vehicle_year":"",
            "odometer":"",
            "left_front_tire_pressure":"",
            "right_front_tire_pressure":"",
            "left_rear_tire_pressure":"",
            "right_rear_tire_pressure":"",
            "fuel_level":"",
            "oil_life":"",
            "mil_status":"",
            "ambient_air_temperature":"",
            "update_time":""
        }
    ] 
}

RemoveVehicle

Removes the association between a Vehicle and a specific User.

Request

curl -L -X POST 'https://{DOMAIN}/voyorequest/RemoveVehicle

-d 'user_key={USER_KEY}&vehicle_key={VEHICLE_KEY}'
-H 'Accept: application/json'
-H 'Authorization: Bearer {APIKEY}'

Parameter	Description
`user_key`	Unique key belonging to a User that is linked the the provided Vehicle.
`vehicle_key`	Unique key belonging to the Vehicle to be removed.

Error Responses

Indicates why the removal failed, such as non-existent or invalid vehicle key.

    HTTP/1.1 400 Bad Request

// Vehicle matching provided key does not exist
{ "error":"Vehicle does not exist!" }

Success Responses

Vehicle was removed successfully.

{ "error":"Success!" }

UpdateVehicle

Update Vehicle's information. Vehicles support a number of parameters that may be useful to keep up to date. Updating this information keeps Vehicle records accurate and supports services like maintenance scheduling and telemetry. Parameters can be updated all-at-once, one-by-one, or in any combination inbetween.

If the Settings automate_intervals and automate_intervals_on_intial_odometer are enabled, and this Vehicle was created without optional parameter odometer, then by updating odometer with an initial value a series of predefined Service Intervals will be created.

If the Setting user_defined_intervals is also enabled, all Service Interval Settings will be applied to create a series of defined Service Intervals.

Request

The following example updates the vehicle's GPS location only:

curl -L -X POST 'https://{DOMAIN}/voyorequest/UpdateVehicle

-d 'user_key={USER_KEY}&vehicle_key={VEHICLE_KEY}&latitude={LATITUDE}&longitude={LONGITUDE}'
-H 'Accept: application/json'
-H 'Authorization: Bearer {APIKEY}'

Parameter	Description	Requirement	Restrictions
`user_key`	Unique key belonging to provided User.	Required	-
`vehicle_key`	Unique key belonging to Vehicle to be deleted.	Required	-
`latitude`	GPS latitude.	Optional	Between -90 and 90
`longitude`	GPS longitude.	Optional	Between -180 and 180
`make`	Make of this Vehicle.	Optional	Less than 50 characters
`model`	Model of this Vehicle.	Optional	Less than 20 characters
`year`	Vehicle model year.	Optional	Integer greater than 1980
`name`	User defined identifier for this Vehicle.	Optional	Less than 50 characters
`time`	Unix timestamp indicating the last time this Vehicle was connected.	Optional	Integer greater than 0
`odometer`	Current odometer reading.	Optional	km expected
`lft_pressure`	Left front tire pressure.	Optional	kPa expected
`rft_pressure`	Right front tire pressure.	Optional	kPa expected
`rlt_pressure`	Rear left tire pressure.	Optional	kPa expected
`rrt_pressure`	Rear right tire pressure.	Optional	kPa expected
`fuel_level`	Percentage of fuel remaining in Vehicle.	Optional	Up to 2 decimals of precision
`oil_life`	Percentage of oil remaining before oil change is needed.	Optional	Up to 2 decimals of precision
`mil_status`	1: Check engine light is on, 2: Check engine light is off.	Optional	-
`ambient_air`	Ambient air temperature.	Optional	Celcius expected

Update request MUST include at least one parameter. GPS Coordinates are floats supporting up to 8 digits of precision. When updating latitude and longitude together BOTH values can not be 0.

Error Responses

    HTTP/1.1 400 Bad Request

For a more detailed response check the following error descriptions:

// Attempting to update a Vehicle that does not exist:
{ "error":"Vehicle does not exist!" }

// If both latitude and longitude are 0:
{ "error":"Invalid latitude/longitude pair!" }

// Attempt to update with no parameters in request body:
{ "error":"Nothing to update!" }

// A provided parameter {PARAM} is outside of valid range. 
// For example, a negative odometer reading:
{ "error":"{PARAM} is outside of valid range!" }

Success Responses

Vehicles was updated successfully.

{ "error":"Success!" }

When a Vehicle updates odometer or time it may now require maintenance. Vehicle was updated successfully and triggered a Service Intervals:

{ 
    "error":"Success!", "maintenance_required":[
        {
            "id":"",
            "notes":"",
            "date_created":""
        }
    ] 
}