Service Intervals

Service Intervals represent a duration of time or miles driven before a Vehicle requires maintenance.

CreateServiceInterval

Creates a Service Interval based on mileage or time. As Vehicles update odometer or time each Service Interval will be checked. Any Vehicle that exceeds a Service Interval will trigger a reminder that the vehicle requires maintenance.

If both mileage and time are provided the reminder will be sent after either is triggered.

Request

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

-d 'vehicle_key={VEHICLE_KEY}&odometer={ODOMETER}&time={TIME}&notes={NOTES}'
-H 'Accept: application/json'
-H 'Authorization: Bearer {APIKEY}'

Parameter	Description	Requirement	Max Size
`vehicle_key`	Unique key belonging to the Vehicle to be assigned a Service Interval.	Required	40
`odometer`	Vehicle mileage when service is required.	Optional	1000000
`time`	Timestamp for when maintenance is required.	Optional	-
`notes`	Description of what will be serviced at provided mileage/time.	Optional	65535

odometer and time are optional, but at least one must be provided.

Error Responses

An error response is returned if the request is invalid or cannot be processed.

    HTTP/1.1 400 Bad Request

/// Vehicle belonging to provided vehicle_key can not be found
{ "error":"Vehicle does not exist!" }

/// Provided notes are too long
{ "error":"notes can not be more than 65535 characters!" }

// Negative numbers and extremely large values are not allowed
{ "error":"odometer is outside of valid range!" }

// Timestamp must be between present day and next year
{ "error":"time is outside of valid range!" }

/// While both optional, at least one (mileage/time) must be provided
{ "error":"Service interval must be based on mileage or time!" }

Success Responses

On success, a service_id will be returned. This identifier is used to update and remove the created Service Intervals.

Service Interval was created successfully.

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

GenerateServiceInterval

Automatically create predefined Service Intervals for a Vehicle based on its current mileage. This helps quickly set up a Vehicle's maintenance schedule without manually creating each interval. Once generated, these intervals can be used to trigger service notifications as the Vehicle reaches specified thresholds.

Creates the following Service Intervals:

Name of Service	Supports Mileage	Supports Time
Oil Change	`TRUE`	`TRUE`
Tire Rotation	`TRUE`	`TRUE`
Replace Cabin Air Filter	`TRUE`	`TRUE`
Replace Engine Air Filter	`TRUE`	`TRUE`
Replace Brake Pads	`TRUE`	`TRUE`
Replace Spark Plugs	`TRUE`	`TRUE`
Replace Brake Fluid	`TRUE`	`TRUE`
Replace Transmission Fluid	`TRUE`	`TRUE`

This request will create each Service Interval above for every vehicle unless vehicle_key is defined. In which case, the Service Intervals will be created only for the specified Vehicle.

Specific Service Intervals not listed above can be created.

Service Intervals can be "generated" automatically by changing your Settings.

Request

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

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

Parameter	Description	Requirement
`vehicle_key`	Unique key belonging to the Vehicle that Service Intervals will be generated for.	Optional

Error Responses

    HTTP/1.1 400 Bad Request

/// Vehicle belonging to provided vehicle_key can not be found
{ "error":"Vehicle does not exist!" }

Success Responses

Service Intervals were generated successfully.

{ "error":"Success!" }

GetAllServiceIntervals

Get a list of all Service Intervals optionally filtered by a need for maintenance.

Request

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

-d 'maintenance_required={MAINTENANCE_REQUIRED}'
-H 'Accept: application/json'
-H 'Authorization: Bearer {APIKEY}'

`maintenance_required`
-	Returns all Service Intervals
0	Returns Service Intervals where associated Vehicle has not reached set mileage or time threshold
1	Returns Service Intervals where associated Vehicle has reached or exceeded set mileage or time threshold

Example Response

Response "service_intervals" can be empty if the provided Vehicle has no Service Intervals associated with it.

{ 
    "error":"Success!", "service_intervals":[
        {
            "id":"",
            "created_at":"",
            "last_updated":"",
            "notes":"",
            "service_at_mileage":"",
            "service_at_date":""
        }
    ] 
}

If a Service Intervals was created with mileage and not time it will be returned with "service_at_mileage", and not "service_at_date" included.

GetServiceIntervals

Get a list of all Service Intervals associated with the requested Vehicle. Use this to view which Service Intervals are defined, how far they are from being reached, and whether any maintenance actions should be anticipated.

Request

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

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

Parameter	Description
`vehicle_key`	Unique key belonging to the provided Vehicle.

Error Responses

An error response is returned if the request is invalid or cannot be processed.

    HTTP/1.1 400 Bad Request

/// Vehicle belonging to provided vehicle_key can not be found
{ "error":"Vehicle does not exist!" }

Success Responsess

Response "service intervals" can be empty if the provided Vehicle has no Service Intervals associated with it.

{ 
    "error":"Success!", "service_intervals":[
        {
            "id":"",
            "created_at":"",
            "last_updated":"",
            "notes":"",
            "service_at_mileage":"",
            "service_at_date":""
        }
    ] 
}

If a Service Intervals was created with mileage and not time it will be returned with "service_at_mileage", and not "service_at_date" included.

RemoveServiceInterval

Delete a created Service Interval from the provided Vehicle. This action dissociates the Service Interval so it no longer triggers notifications or appears in requests for that Vehicle. Use this when a Service Interval is no longer needed or was created in error.

Request

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

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

Parameter	Description
`vehicle_key`	Unique key belonging to the provided Vehicle.
`id`	Unique identifier of a Service Interval.

Error Responses

Error responses occur when the request cannot be processed, such as if the interval id is invalid, missing, or the caller is not authorized to delete the interval.

    HTTP/1.1 400 Bad Request

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

// Service interval identifier was invalid
{ "error":"Requires non-zero identifier!" }

Success Responses

Service Interval was removed successfully.

{ "error":"Success!" }

UpdateServiceInterval

Update Service Interval notes. A new note will be appended onto the previous note. Should the new note (in addition to the previous note) exceed the maximum note size, the new note will overwrite the previous note.

Request

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

-d 'vehicle_key={VEHICLE_KEY}&id={ID}&notes={NOTES}'
-H 'Accept: application/json'
-H 'Authorization: Bearer {APIKEY}'

Parameter	Description
`vehicle_key`	Unique key belonging to the Vehicle to be updated.
`id`	Unique identifier belonging to a previously created Service Interval.
`notes`	Description of what will be serviced at provided mileage/time.

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!" }

// Could not find provided service interval
{ "error":"Could not find requested service interval!" }

Success Responses

Service Interval was updated successfully.

{ "error":"Success!" }