Zubie Logo
Documentation Powered by ReDoc

Zubie API (v2.1)

Download OpenAPI specification:Download

License: Zubie Terms of Use

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

    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

    • 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:
    AccountApiKeyOAuth

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

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

    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:
    AccountApiKeyOAuth
    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:
    AccountApiKeyOAuth
    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:
    AccountApiKeyOAuth
    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:
    AccountApiKeyOAuth
    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:
    AccountApiKeyOAuth
    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