APIs and Integrations

If you have been provided with API permissions, you will be able to create API Tokens, and access our API Documentation. The API has the same permissions as your user. You will not be able to access any additional data through the API, that your user can not see already in Sensium Connect+.

Sensium API's are all GraphQL. GraphQL queries vary from traditional REST endpoints in that you build your own layered request, for only the specific data that you require. In most cases, this dramatically reduces the number of API calls you will need to make to get the end data that you require.

Sensium is constantly developing, and our API is subject to change. We recommend you always refer to the API Explorer for available Querys, and Mutations. If you find something not working as expected, please contact your Sensium Integration Expert via email.

You should keep your Personal Access Tokens private, and secure, as they provide access to your account.

Accessing API Tokens And Documentation

To access your Sensium Connect+ API Personal Access Tokens, once logged into Sensium Connect+, navigate to your initials in the top right hand corner, and select API Keys from the dropdown menu.

If API Keys is not an option, your user has not been granted the required permissions for API Access. Please speak to your Sensium Connect+ administrator.

From this page you can learn more about how GraphQL functions, visit the Sensium Connect+ live explorer, and read our other documentation.

Creating a Personal Access Token

From the API page, select "Create New Token"

Provide a name for your Token, and then click "Create Token".

Sensium recommends using a Token per integration system you're building, and therefore naming the individual Token as something similar to the integration system. In the below screenshot, I have named the new token "Example Token"

Your Personal Access Token will now appear on the API Keys page for your user, along with any other existing tokens you have already created.

You should keep your Personal Access Tokens private, and secure, as they provide access to your account.

You should;

• Never hard code your Personal Access Token.

• Never share your Personal Access Token.

• Never submit it to a code repository, for example, in a .env file.

If you feel your token is no longer secure, you should delete it immediately, and create a new token.

Deleting a Personal Access Token

Deleting a Personal Access Token is not reversible. If you delete the wrong token, you will need to create a new token, and update your integration system with the token.

To delete a Personal Access Token, on the right hand side beside the token, click the Trash Can in the red square.

Confirm from the pop up message that you've selected the correct Personal Access Token to delete by checking the Name of the token, and then click "Ok" to proceed.

Creating your Queries

Our recommendation is that you start to build out your API Calls in the API Explorer before you start writing code.

By using the API Explorer, you can rest assure that everything is being handled correctly in the request, and state management of the session, and you only need to worry about creating a valid Query or Mutation.

The power of GraphQL queries is shown in the below code snippet, where in one query, we are able to retrieve;

• Account ID, Account Name, Account Contact Name, and Account Country

• All fleets available for the user, and associated with the account, the ID of the fleet, the name of the fleet.

• Each Asset available to each fleet, associated with the account. The ID of the asset, and the name of the asset.

• The Places associated with the account, and their IDs, Name, and type of Place.

Please feel free to copy all of the below into your own Code Explorer, and run it.

Please be aware, any of the mutations you run in the Code Explorer, are executed on your live account. If you require a sandbox testing account, please contact a Sensium Integration Expert.

query SampleQuery {
  account {
    id
    name
    contactname
    country
    fleets {
      id
      name
      assets {
        id
        name
      }
    }
    places {
      id
      name
      placetype
    }
  }
}

As a simple comparison to a typical REST API, to retrieve the same data would typically require a minimum of 3 API calls, plus an additional API call per fleet.

If you had 10 fleets, that would require 13 API calls.

In addition, you would end up with all data associated with each endpoint, whereas GraphQL allowed us to select only a small portion of the data.

The above equates to less bandwidth, and faster queries.