Download OpenAPI specification:Download
This is the reference documentation for the V2 Zubie API. Zubie customers on a Premium plan can access the full API for their account using an encrypted API Key. Third-party developers with apps registered in the ZinC Developer platform will have access a restricted set of API's using Oauth authentication. If you are a developer, visit the ZinC Developer Portal for information on setting up apps and using Oath authentication.
For support, contact us at support@zubie.com.
https://api.zubiecar.com/api/v2/zinc
.Zubie Customers The Zubie API uses an encrypted API Key to provide account-level API accesss, added to the header of every request.
Zubie-Api-Key: {api key}
To generate an API Key, contact us.
Third Party Developers You must first register an app via the ZinC developer platform. Once registered, you are granted a client id and key that can be used through an Oauth authentication exchange to generate a token on behalf of a Zubie user. The client token is added in the Authorization header. Note that third party apps default to read-only scope for a limited set of endpoints.
Authorization: Bearer {oauth token}
Note that Zubie adds new properties from time to time as new features are released without an API version change. We do not recommend using the API docs to perform schema validation.
Zubie uses standard HTTP response codes to indicate success or failure of an API request.
Responses | Description |
---|---|
200 - OK | A GET request succeeded. JSON dictionary response. |
201 - Created | A POST response succeeded. JSON dictionary response. |
400 - Bad Request | The request was unacceptable, often due to missing a required parameter. JSON dictionary response { "errors": "This was a bad request because..." } |
401 - Unauthorized | No valid API key provided. Empty body. |
403 - Forbidden | The requested action is restricted based on your account profile. Empty body. |
404 - Not Found | The requested resource doesn't exist. Empty body. |
500, 502, 503 | Something is wrong on the Zubie side. |
Many endpoints that return large lists of results are paginated. In instances where the number of results exceeds the size parameter (per-endpoint default, or optionally specified with the request), a cursor value is included in the response. Callers may repeat the request, including the original query parameters, with the addition of the cursor parameter, to retrieve the next set of results. Once all results have been returned, the cursor will be omitted from the last response.
Query Parameters
Response Data
The response will be a dictionary containing the account’s data.
Successful.
Update account-wide settings.
nickname | string The account name, i.e. the business name. |
external_id | string An optional, external id string associated with the account. |
street | string The street address for the account. |
city | string The city for the account. |
state | string The street address for the account. |
zipcode | string The zipcode for the account. |
Successful update.
Lists the subscriptions associated with the account. All devices with the same plan will be grouped under the same subscription.
cursor | string The cursor string used for pagination, signifying the object ID where to start the results. |
size | string The number of results to return per call. Defaults to 100 if not provided. |
Successful.
Lists all active and pending devices (vehicle connected hardware) in account.
q | string Search devices by serial. |
cursor | string The cursor string used for pagination, signifying the object ID where to start the results. |
size | string The number of results to return per call. Defaults to 50 if not provided. |
Successful.
key required | string Unique device key. |
Successful.
Update a Device subscription status.
key required | string Unique device key. |
subscription_status | string Specify value |
Successful update.
Lists groups available in the account, based on the group permissions of the user. Groups are a way to provide hierarchical structure to account vehicles and restrict user permissions.
group_keys | Array of string Optional list of group_keys (as repeated parameters) to further filter results, only includes those groups and below. Multiple tag values may be provided. (e.g. “?group_keys=foo&group_keys=bar”). |
show_inactive | boolean Optional boolean, defaults False. Whether to include deactivated groups in hierarchy response. |
Successful.
Create a new group.
name | string |
parent_group_key | string The key of the parent group. If omitted, will use the account as parent, for a level 2 node. Parent group must be active. |
Successfully created.
group_key required | string Unique group key |
Successful.
Update a Group name or status.
group_key required | string Unique group key |
name | string Group name. |
Successful update.
Deactivate a Group. Must have no members, or child groups.
group_key required | string Unique group key |
Successful update.
Error if the group or its children still have active members.
Modify group memberships. Adds or removes group set from a list of member entities. Note that users are not allowed to edit their own group memberships. It is an error if group removal would escalate a member higher in the hierarchy than the caller (e.g. an user with groups assigned tries to remove all groups from a car).
action required | string Default: "add" Enum:"add" "remove" "replace" The action to apply. One of |
member_keys | Array of string A list of entity keys to act on. Must be of a groupable resource (Car and User). Up to 20 member keys may be provided per call. |
group_keys | Array of string A list of group keys to act with. Groups must be all be accessible the user, unique, and no groups may be a descendant of another group. |
Successful update.
Error due to invalid group operation.
Lists places for the entire account.
cursor | string The cursor string used for pagination, signifying the object ID where to start the results. |
size | string The number of results to return per call. Defaults to 50 if not provided. |
Successful.
Create a new place.
category | string One of the following |
point | object (LocationPoint) |
name | string Place name |
address | string Address of location. |
from_time | string Required. A string timestamp in the form |
to_time | string Required. A string timestamp in the form |
active_weekdays | Array of any Required. An array of integers indicating days of the week to detect geofence events, where Monday is 0 and Sunday is 6. Define as a comma separated list of numbers. |
notifying_arrival | boolean Flag determines whether arrival notifications will be generated. The default behavior (if null), is to generate notifications. If disabled, place visits will still be tracked based on the weekday/time windows. |
notifying_departure | boolean Flag determines whether departure notifications will be generated. The default behavior (if null), is to generate notifications. If disabled, place visits will still be tracked based on the weekday/time windows. |
radius | number <double> Radius for triggering arrival/departure. |
radius_um | string Unit of measure for radius, mi or km. |
Successfully created.
place_key required | string Unique place key |
Successful.
Update a Place name or status.
place_key required | string Unique place key |
category | string One of the following |
point | object (LocationPoint) |
name | string Place name |
address | string Address of location. |
from_time | string Required. A string timestamp in the form |
to_time | string Required. A string timestamp in the form |
active_weekdays | Array of any Required. An array of integers indicating days of the week to detect geofence events, where Monday is 0 and Sunday is 6. Define as a comma separated list of numbers. |
notifying_arrival | boolean Flag determines whether arrival notifications will be generated. The default behavior (if null), is to generate notifications. If disabled, place visits will still be tracked based on the weekday/time windows. |
notifying_departure | boolean Flag determines whether departure notifications will be generated. The default behavior (if null), is to generate notifications. If disabled, place visits will still be tracked based on the weekday/time windows. |
radius | number <double> Radius for triggering arrival/departure. |
radius_um | string Unit of measure for radius, mi or km. |
Successful update.
List of vehicle schedules available in account. Schedules are attached to vehicles and trigger permitted driving notifications, if enabled. A schedule can be any set of start/end times across a week. The recommended schedule is a weekday/weekend schedule.
cursor | string The cursor string used for pagination, signifying the object ID where to start the results. |
size | string The number of results to return per call. Defaults to 50 if not provided. |
Successful.
Create a new schedule.
category | string Type of schedule. Currently |
name | string Optional name for this schedule. If not provided, will default to |
periods | Array of object A list of objects that define a set of days/times for the schedule. Required to have 1 or more periods. |
Successfully created.
schedule_key required | string Unique schedule key |
Successful.
Update a Schedule.
schedule_key required | string Unique schedule key |
category | string Type of schedule. Currently |
name | string Optional name for this schedule. If not provided, will default to |
periods | Array of object A list of objects that define a set of days/times for the schedule. Required to have 1 or more periods. |
Successful update.
Deactivates a schedule. Schedule should be removed from vehicles first.
schedule_key required | string Unique schedule key |
Successfully removed schedule. The response will be empty.
Lists tags available in the account, including tags for Trips, Cars and Users. Tags are a free-form way to categorize things across an account.
Successful.
Create a new tag available for the whole account.
Tag properties.
color | string Hex color value used for tag display in app. |
type | string Type of tag. Must be |
value | string Tag name. |
Successfully created.
tag_key required | string Unique tag key |
Successful.
Update a Tag name or color.
tag_key required | string Unique tag key |
color | string |
value | string |
Successful update.
Apply Tags to Trips, Cars or Users.
tag_key required | string Unique tag key |
action | string Default: "add" Whether to |
entity_keys | Array of string Must be valid keys associated with tag type - |
Successful update.
Returns the profile for the current autthenticated user.
Successful.
Lists users and drivers in account. Restricted based on API user's group permissions.
cursor | string The cursor string used for pagination, signifying the object ID where to start the results. |
size | string The number of results to return per call. Defaults to 100 if not provided. |
expand | Array of string Default: ["tags","groups","apps","vehicle_location"] Items Enum:"tags" "groups" "apps" "vehicle_location" Optional list of expanded properties to include in results |
Successful.
Create a new user or driver.
account_role | string The user’s role within the parent account. Possible values are |
device_events | boolean User subscribed for device notifications. |
string User email address. | |
email_notification | boolean User subscribed to receive notifications via email. |
first_name | string First name |
hard_braking_events | boolean User subscribed for hard brake notifications. |
last_name | string Last name. |
low_fuel_events | string User subscribed for low fuel notifications. Possible values are |
low_fuel_threshold | integer Default: 15 A number indicating the percentage under which the user receives low fuel notifications. Range of 1 - 50 inclusive. Defaults to 15. |
marketing_opt_out | boolean Default: false User subscribed for Zubie marketing emails. |
over_speed_events | boolean User subscribed for speeding notifications. |
preferred_locale | string The user’s locale preference, optional. |
profile_image | string The URL of the profile image for this user |
push_notification | boolean User subscribed to receive notifications via app push notification. |
sms_phone_number | string User sms phone number. |
speed_threshold | integer Threshold to trigger speeding notifications, if enabled. |
speed_threshold_um | string Unit of measure for speed threshold. Defaul mph. |
trip_events | any User subscribed for trip-end notifications. Possible values are |
vehicle_health_events | boolean A boolean indicating whether the user receives vehicle health notifications. |
vehicle_location_events | string User subscribed for arrival/departure notifications for places where arrival or departure events are enabled. Possible values are |
vehicle_maintenance_events | string User subscribed for scheduled maintenance notifications. Possible values are |
vehicle_schedule_events | string User subscribed for schedule-based notifications (off hour trips). Possible values are |
tag_keys | Array of string Tags assigned to the user. Multiple values can be provided. Can be cleared by posting empty value. |
group_keys | Array of string Groups assigned to the user. Can be cleared by posting empty value. |
Successfully created.
Gets a User Profile by Key.
user_key required | string Unique user key |
Successful.
Update a User.
user_key required | string Unique user key |
account_role | string The user’s role within the parent account. Possible values are |
device_events | boolean User subscribed for device notifications. |
string User email address. | |
email_notification | boolean User subscribed to receive notifications via email. |
first_name | string First name |
hard_braking_events | boolean User subscribed for hard brake notifications. |
last_name | string Last name. |
low_fuel_events | string User subscribed for low fuel notifications. Possible values are |
low_fuel_threshold | integer Default: 15 A number indicating the percentage under which the user receives low fuel notifications. Range of 1 - 50 inclusive. Defaults to 15. |
marketing_opt_out | boolean Default: false User subscribed for Zubie marketing emails. |
over_speed_events | boolean User subscribed for speeding notifications. |
preferred_locale | string The user’s locale preference, optional. |
profile_image | string The URL of the profile image for this user |
push_notification | boolean User subscribed to receive notifications via app push notification. |
sms_phone_number | string User sms phone number. |
speed_threshold | integer Threshold to trigger speeding notifications, if enabled. |
speed_threshold_um | string Unit of measure for speed threshold. Defaul mph. |
trip_events | any User subscribed for trip-end notifications. Possible values are |
vehicle_health_events | boolean A boolean indicating whether the user receives vehicle health notifications. |
vehicle_location_events | string User subscribed for arrival/departure notifications for places where arrival or departure events are enabled. Possible values are |
vehicle_maintenance_events | string User subscribed for scheduled maintenance notifications. Possible values are |
vehicle_schedule_events | string User subscribed for schedule-based notifications (off hour trips). Possible values are |
tag_keys | Array of string Tags assigned to the user. Multiple values can be provided. Can be cleared by posting empty value. |
group_keys | Array of string Groups assigned to the user. Can be cleared by posting empty value. |
Successful update.
The user lacks permission to edit another user.
Deactivates user account.
user_key required | string Unique user key |
Successfully removed user. The response will be empty.
The user lacks permission to remove another user.
Invalid Key
Lists Vehicles in account. Restricted based on API user's group permissions.
q | string Search vehicles by nickname or full VIN. |
tag_keys | Array of string Restrict results to include only vehicles with these tag keys. Multiple tag values may be provided, treated as an OR in filter. |
group_keys | Array of string Restrict results to include only vehicles that are members of these groups (or their descendants). |
cursor | string The cursor string used for pagination, signifying the object ID where to start the results. |
size | string The number of results to return per call. Defaults to 50 if not provided. |
expand | Array of string Default: [] Items Enum:"tags" "groups" "devices" "last_trip" Optional list of expanded properties to include in results |
Successful.
Creates a Vehicle.
fuel_economy | string User defined vehicle fuel economy. |
fuel_type | string User defined vehicle fuel type, overrides style info. |
image_url | string URL of vehicle image. If not defined, falls back to style-based image. |
nickname | string Vehicle nickname |
odometer | integer The current odometer reading. |
odometer_um | string Unit of measure for odometer, mi or km. |
primary_driver_key | string The user key to set as the primary driver of the vehicle attached to the device. Optional. |
schedule_key | string The (optional) schedule associated with this vehicle. See Vehicle Schedules. Can be cleared by posting empty value. |
tag_keys | Array of string Tags assigned to the vehicle. Multiple values can be provided in the array. Can be cleared by posting empty value. |
group_keys | string Group assigned to the vehicle. If groups aren't used, or vehicle belongs to the account (not a sub-group), leave empty. Only ONE group should be assigned to a vehicle. Can be cleared by posting empty value. |
vin | string Vehicle Identification Number, either detected by system or entered by user. |
Successfully created.
The user lacks permission to create a vehicle.
vehicle_key required | string Unique vehicle key |
Successful.
Update a Vehicle.
vehicle_key required | string Unique vehicle key |
fuel_economy | string User defined vehicle fuel economy. |
fuel_type | string User defined vehicle fuel type, overrides style info. |
image_url | string URL of vehicle image. If not defined, falls back to style-based image. |
nickname | string Vehicle nickname |
odometer | integer The current odometer reading. |
odometer_um | string Unit of measure for odometer, mi or km. |
primary_driver_key | string The user key to set as the primary driver of the vehicle attached to the device. Optional. |
schedule_key | string The (optional) schedule associated with this vehicle. See Vehicle Schedules. Can be cleared by posting empty value. |
tag_keys | Array of string Tags assigned to the vehicle. Multiple values can be provided in the array. Can be cleared by posting empty value. |
group_keys | string Group assigned to the vehicle. If groups aren't used, or vehicle belongs to the account (not a sub-group), leave empty. Only ONE group should be assigned to a vehicle. Can be cleared by posting empty value. |
vin | string Vehicle Identification Number, either detected by system or entered by user. |
Successful update.
The user lacks permission to update the vehicle.
Deactivates vehicle in account.
vehicle_key required | string Unique vehicle key |
Successfully removed vehicle. The response will be empty.
The vehicle lacks permission to remove the vehicle.
Invalid Key
Get list of nearby vehicles, using a given GPS point. Restricted based on API user's group permissions.
lat required | string Latitude of the point. |
lon required | string Longitude of the point. |
cursor | string The cursor string used for pagination, signifying the object ID where to start the results. |
size | string The number of results to return per call. Default 5 if not provided. |
Successful.
Get list of battery levels as reported through vehicle heartbeats. Heartbeat events are sent at the beginning of a trip, and periodically when the vehicle is not in a trip.
vehicle_key required | string Unique vehicle key |
cursor | string The cursor string used for pagination, signifying the object ID where to start the results. |
size | string The number of results to return per call. Default 50 if not provided. |
since | string Look for battery levels reported on Heartbeats starting on or after this time. ISO8601 formatted datetime, e.g. 2014-10-01T00:00:00-06:00. (optional) Default is now UTC - 7 days. |
until | string Look for battery levels reported on Heartbeats starting on or before this time. ISO8601 formatted datetime. (optional) Default uses now UTC. |
order_by | string Determines timestamp order to return heartbeats, |
Successful.
Access events or user-subscribed notifications generated from driving activity and other system events.
This endpoint is useful to retrieve events of a specific type for exception-based workflows.
event required | string Filter results by event type.
|
cursor | string The cursor string used for pagination, signifying the object ID where to start the results. |
size | string The number of results to return per call. Default 10 if not provided. |
after | string Datetime to query events after (inclusive). |
before | string Datetime to query events before (exclusive). |
Successful.
Get a list of trips for the account. A trip is the logical grouping of all points that are recorded from the time the vehicle’s engine is started to the time the engine is turned off.
user_key | string Default: "SampleUserKey" Filter results to visits to a single driver. Optional. |
vehicle_key | string Default: "SampleVehicleKey" Filter results to a single vehicle. Optional. |
started_after | string Filter results to only include trips that started on or after this timestamp. ISO8601 format (if no offset provided, assumed UTC). Optional. |
started_before | string Filter results to only include trips that started on or before this timestamp. ISO8601 format (if no offset provided, assumed UTC). Optional. |
tag_keys | Array of string Restrict results to include only vehicles with these tag keys. Multiple tag values may be provided. Takes precedence over tags query param if both provided. |
cursor | string The cursor string used for pagination, signifying the object ID where to start the results. |
size | string The number of results to return per call. Default 10 if not provided. |
expand | Array of string Default: ["user","vehicle","tags"] Items Enum:"user" "vehicle" "tags" Optional list of expanded properties to include in results |
Successful.
Get the details for a single trip.
trip_key required | string Default: "SampleTripKey" Key for individual trip. |
Successful.
Modify the tags or driver associated with a trip.
trip_key required | string Default: "SampleTripKey" Key for individual trip. |
user_key | string Change the driver associated with this trip. New user must be in an account with access to trip. |
tag_keys | Array of string List of tags keys to tag the trip with. |
Successful.
Get the detailed GPS points and event details for a given trip.
trip_key required | string Default: "SampleTripKey" Key for individual trip. |
cursor | string The cursor string used for pagination, signifying the object ID where to start the results. |
size | string The number of results to return per call. Default 200 if not provided. |
Successful.
Get a a list of visits to all places for a given driver, vehicle or place. A visit begins at the trip point a car enters a geofence, and ends at the point they exit.
driver_key | string Default: "SampleDriverKey" Filter results to visits to a single driver. Optional. |
vehicle_key | string Default: "SampleVehicleKey" Filter results to a single vehicle. Optional. |
place_key | string Default: "SamplePlaceKey" Filter results to a single place. Optional. |
entry_after | string Filter results to only include visits that started after this timestamp. Optional. |
entry_before | string Filter results to only include visits that started before this timestamp. Optional. |
cursor | string The cursor string used for pagination, signifying the object ID where to start the results. |
size | string The number of results to return per call. Default 10 if not provided. |
Successful.