Zubie API (v2.1)

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.


Base URL

  • The base URL is https://api.zubiecar.com/api/v2/zinc.
    • All API requests must use HTTPS. Calls made over HTTP will fail.
    • Successful requests return a JSON dictionary.

Authentication

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}

AccountApiKey

API Key generated by Zubie for account-level access.

Security scheme type: API Key
header parameter name: Zubie-Api-Key

OAuth

Oauth Token.

Security scheme type: OAuth2
authorizationCode OAuth Flow
Authorization URL: https://login.zubiecar.com/authorize
Token URL: https://login.zubiecar.com/oauth/token
Scopes:

    Responses and Errors

    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.

    Pagination

    Services that may return a long list of results can be paginated, by providing an optional list size, and a cursor that defines an identifier to fetch the next page.

    Query Parameters

    • size - The number of results to return per call. The default varies per service.
    • cursor - The cursor string signifying where to start the results

    Response Data

    • cursor - If more results are available, this root level response value will be the next cursor string to be passed back. If no more results are available, this field will be absent.

    Account

    Manage account settings and subscriptions.

    Get Account settings

    The response will be a dictionary containing the account’s data.

    Authorizations:

    Responses

    200

    Successful.

    get /account
    https://api.zubiecar.com/api/v2/zinc/account

    Response samples

    application/json
    Copy
    Expand all Collapse all
    {
    • "billing_info":
      {
      },
    • "city": "Bloomington",
    • "created": "2018-02-20 12:00:00",
    • "external_id": "3828919",
    • "key": "SampleKey",
    • "nickname": "Trucking Fleet",
    • "owner_key": "SampleKey",
    • "partner_key": "SampleKey",
    • "partner_name": "Zubie Fleet Connect",
    • "partner_tier":
      {
      },
    • "setup_complete": "2018-02-20 12:00:00",
    • "state": "MN",
    • "street": "8000 Penn Ave",
    • "updated": "2018-02-20T12:00:00+00:00",
    • "user_count": 24,
    • "zipcode": "55435"
    }

    Update Account settings

    Update account-wide settings.

    Authorizations:
    Request Body schema: application/json
    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.

    Responses

    200

    Successful update.

    post /account
    https://api.zubiecar.com/api/v2/zinc/account

    Request samples

    application/json
    Copy
    Expand all Collapse all
    {
    • "nickname": "Trucking Fleet",
    • "external_id": "3828919",
    • "street": "1234 Oak Street",
    • "city": "Minneapolis",
    • "state": "MN",
    • "zipcode": "55555"
    }

    Get Subscriptions List

    Lists the subscriptions associated with the account. All devices with the same plan will be grouped under the same subscription.

    Authorizations:

    Responses

    200

    Successful.

    get /subscriptions
    https://api.zubiecar.com/api/v2/zinc/subscriptions

    Response samples

    application/json
    Copy
    Expand all Collapse all
    {
    • "subscriptions":
      [
      ]
    }

    Devices

    Manage vehicle-connected hardware.

    Get List of Devices

    Lists all active and pending devices (vehicle connected hardware) in account.

    Authorizations:
    query Parameters
    q
    string

    Search devices by serial.

    Responses

    200

    Successful.

    get /devices
    https://api.zubiecar.com/api/v2/zinc/devices

    Response samples

    application/json
    Copy
    Expand all Collapse all
    {
    • "devices":
      [
      ]
    }

    Get a Device

    Authorizations:
    path Parameters
    key
    required
    string

    Unique device key.

    Responses

    200

    Successful.

    get /device/{key}
    https://api.zubiecar.com/api/v2/zinc/device/{key}

    Response samples

    application/json
    Copy
    Expand all Collapse all
    {
    • "key": "SampleKey",
    • "serial": "ZU9999999",
    • "status": "installed",
    • "vehicle_key": "SampleKey",
    • "is_connected": true,
    • "disconnected_timestamp": "2018-03-01T01:02:03+00:00",
    • "last_transmission": "2018-03-01T01:02:03+00:00"
    }

    Update Device

    Update a Device subscription status.

    Authorizations:
    path Parameters
    key
    required
    string

    Unique device key.

    Request Body schema: application/json
    subscription_status
    string

    Specify value canceled to mark a device as "Do Not Renew" or active to "un-cancel" a canceled device.

    Responses

    200

    Successful update.

    post /device/{key}
    https://api.zubiecar.com/api/v2/zinc/device/{key}

    Request samples

    application/json
    Copy
    Expand all Collapse all
    {
    • "subscription_status": "canceled"
    }

    Groups

    Manage account hierarchy using groups.

    Get List of Groups

    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.

    Authorizations:
    query Parameters
    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.

    Responses

    200

    Successful.

    get /groups
    https://api.zubiecar.com/api/v2/zinc/groups

    Response samples

    application/json
    Copy
    Expand all Collapse all
    {
    • "groups":
      [
      ]
    }

    Create Group

    Create a new group.

    Authorizations:
    Request Body schema: application/json
    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.

    Responses

    201

    Successfully created.

    post /groups
    https://api.zubiecar.com/api/v2/zinc/groups

    Request samples

    application/json
    Copy
    Expand all Collapse all
    {
    • "name": "Midwest Region",
    • "parent_group_key": "SampleKey"
    }

    Get a group by key

    Authorizations:
    path Parameters
    group_key
    required
    string

    Unique group key

    Responses

    200

    Successful.

    get /group/{group_key}
    https://api.zubiecar.com/api/v2/zinc/group/{group_key}

    Response samples

    application/json
    Copy
    Expand all Collapse all
    {
    • "active": true,
    • "children":
      [
      ],
    • "created": "2018-02-20 12:00:00",
    • "key": "SampleKey",
    • "member_counts":
      {
      },
    • "name": "Midwest Region",
    • "tree_depth": 1,
    • "updated": "2018-02-20 12:00:00"
    }

    Update Group

    Update a Group name or status.

    Authorizations:
    path Parameters
    group_key
    required
    string

    Unique group key

    Request Body schema: application/json
    name
    string

    Group name.

    Responses

    200

    Successful update.

    post /group/{group_key}