Alerts

Alerts are events with significance to a Vehicle or connected User. For example, a common Vehicle Alert would be a DTC. Additionally, the option to make a more generic Custom Alert also exists. An Alert that is no longer of interest can be resolved via UpdateAlert.

CreateAlert

Creates an Alert. Alerts require a Vehicle (what created the alert) and a User (who created the alert).

Requests

The following parameters are required for DTC and Custom Alerts:

Parameter	Description	Requirement
user_key	Unique key belonging to a user who is attributed to the creation of this alert.	Required
vehicle_key	Unique key belonging to the vehicle this alert was created on.	Required
time	Unix timestamp representing the start time of this alert.	Optional

DTC

A standardized vehicle fault code with the option to include a description explaining the issue.

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

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

Parameter	Description	Requirement
dtc	5 character Diagnostic Trouble Code.	Required
description	A short description of the DTC.	Optional

Custom Alert

Any relevant non-DTC occurrence.

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

-d 'user_key={USER_KEY}&vehicle_key={VEHICLE_KEY}&title={TITLE}&detail={DETAIL}&time={TIME}'
-H 'Accept: application/json'
-H 'Authorization: Bearer {APIKEY}'

Parameter	Description	Requirement
title	Name of the alert.	Required
detail	A short description of the alert.	Optional

Error Responses

Returned when the request cannot be processed due to validation errors, authorization issues, or malformed input.

    HTTP/1.1 400 Bad Request

For a more detailed response check the following error descriptions:

// Attempting to create an Alert for a Vehicle that does not exist:
{ "error":"Vehicle does not exist!" }

// Attempting to create an Alert for a User that does not exist:
{ "error":"User does not exist!" }

// Attempt to update with no parameters in request body:
// Attempt to create an alert with no DTC or TITLE
{ "error":"Requires alert information!" }

// DTC is not 5 characters
{ "error":"Invalid DTC!!" }

// Provided timestamp is outside of valid range
{ "error":"Update timestamp is outside of valid range!" }

Success Responses

When the Alert is created successfully alert_id will be part of the response. The returned alert_id is required to use UpdateAlert.

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

GetAlerts

Get a list of all Alerts for a specified Vehicle. Optionally, you can request all active ("1") or inactive ("0") Alerts.

Request

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

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

Parameter	Description	Requirement
user_key	Unique key belonging to the provided user.	Required
vehicle_key	Unique key belonging to the provided vehicle.	Required
active	"1": Active or "0": Inactive.	Optional

Error Responses

    HTTP/1.1 400 Bad Request

For a more detailed response check the following error descriptions:

// Provided VIN does not belong to any Vehicle
{"error":"Vehicle does not exist!"}

// Valid "active" options are 1: Active Alerts and 0: Inactive Alerts
{"error":"Active flag is outside of valid range!"}

Success Responses

A successful response will include the parameter "alerts". The "alerts" array may be empty if no Alerts have been created or there are none that match the provided search criteria.

{
    "success":1, "alerts":[
        {
            "id":"",
            "time":"",
            "active":"",
            "dismissed":"",
            "dtc":"",
            "description":""
        },
        {
            "id":"",
            "time":"",
            "active":"",
            "dismissed":"",
            "title":"",
            "description":""
        }
    ]
}

UpdateAlert

An Alert can be set inactive ("0") or active ("1"). For example, an Alert representing a DTC on a Vehicle that has had its codes cleared can be marked inactive ("0").

Request

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

-d 'user_key={USER_KEY}&id={ID}&active={ACTIVE}&time={TIME}&dismiss={DISMISS}'
-H 'Accept: application/json'
-H 'Authorization: Bearer {APIKEY}'

Parameter	Description	Requirement
id	Unique identifier representing a previously generated Alert.	Required
time	Unix timestamp.	Required
user_key	Unique key belonging to the provided user.	Required
active	"1": Active or "0": Inactive.	Optional
dismiss	"1": Dismissed or "0": Enabled.	Optional

Please note that while time and active are both optional parameters this request can not be made without either.

Error Responses

An error response is returned if the request can not be completed due to invalid input, missing required parameters, authorization issues, or a failure to locate the specified Alert. No changes are applied when an error occurs.

    HTTP/1.1 400 Bad Request

// "id" was not provided
{"error":"Requires alert identifier!"}

// Provided "id" does not belong to this account
{"error":"Account does not have access to this alert!"}

// Must provide at least "time" or "active" as a parameter
{"error":"Requires a parameter to update!"}

Success Responses

Alert was updated successfully.

{"error":"Success!"}