What is RESTful API?

When two systems need to interface with one another, they need a common language. One of the most popular methods for two systems to talk is RESTful API. For those new to these concepts and without software development experience, we recommend downloading and using a service like Postman to make collections of API commands and store authentications.

What Asset Details Can I Get via the TG API?

The TG API will return a JSON array off all assets in your specified organisation, with the following data for each asset:

{
        "departmentId": <yourdepartmentid>,
        "projectId": <yourprojectid>,
        "statusHumanized": "<Parked at Soandso, Placename for X weeks, Y days>",
        "isTripBased": <true/false>,
        "deviceTypeId": <devicetypeid>,
        "deviceSerial": "<serialnumber>",
        "odometerMeters": <odo in meters>,
        "runSeconds": <run hours in seconds>,
        "runSeconds2": <secondary run hours in seconds>,
        "ratePerHour": <dollar rate per hour of usage>,
        "ratePerKM": <dollar rate per km of usage>,
        "organisationId": <yourorgid>,
        "inOrEnteringRecoveryMode": <true/false>,
        "immobilisedOrAboutToBeImmobilised": <true/false>,
        "id": <yourassetid>,
        "assetTypeId": <assettypeid>,
        "name": "<yourassetname>",
        "code": <yourassetcode>,
        "speedKmH": <lastknownspeed>,
        "inTrip": <true/false>,
        "batteryLevelStatus": <0>,
        "lastConnectedUtc": "<datetime>",
        "allocatedDriverId": <yourdriverid>,
        "lastLatitude": <lastknownlatvalue>,
        "lastLongitude": <lastknownlongvalue>,
        "isEnabled": <true/false>,
        "heading": <degrees>
    },

You will always get every asset and all data fields for all assets in your org.

Getting Authenticated

If permitted by your organisation’s security policies, consider using a long-lived API key. Instructions for generating one can be found in the Generating an API Key guide.

Alternatively, you can authenticate with the TG API using a 24-hour bearer token, noting this will need to be refreshed every 24 hours. This token is obtained by submitting a valid TG username and password.

Here is the POST request endpoint to get your bearer token:

https://{{Instance}.telematics.guru/user/authenticate

Your instance will be the underlying server that hosts your Organisations on TG prefixed with “api-”. For example: “api-apac03” or “api-emea02”.

The body should contain:

password = your TG password

username = your TG username

grant_type = password

otp = your OTP (make sure you enter it quickly as they expire within a number of seconds!)

The response will look like this:

{
    "access_token": "eyJ0eXAiYiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1bmlxdWVfbmFtZSI6IjUzNCIsImF1dGgiOiJwd2QiLCJpYXQiOjE3NDE5MjE4MDAsImlzcyI6IlFBIiwiYXVkIjoiYWxsIiwiZXhwIjoxNzQyDDA4MjAwLCJuYmYiOjE3NDE5MjE4MDB9.pH1yU-hsY2DtUul7PT8Ag2D9IKmg3Z8vyeRG7V1WV1U",
    "token_type": "bearer",
    "expires_in": 86399
}

The access_token is used for all subsequent TG API calls.

Finding Your Organisation ID

Before you can request details from your organisation, you will need your organisation id. This can be found in the response to another request.

Here is the GET request endpoint to get a list of org id's:

http://{{Instance}}.telematics.guru/v2/user/organisations

Your instance will be the underlying server that hosts your Organisations on TG prefixed with “api-”. For example: “api-apac03” or “api-emea02”.

Your authorisation should use the API key auth, or the Bearer Token and contain the access token from the authorisation step.

The body should be empty.

The response will look like this:

[{"noAssets":1,"id":1,"name":"WonkaChocFactory"},{"noAssets":1,"id":3,"name":"MatildaInc"},{"noAssets":1,"id":4,"name":"BFG"},{"noAssets":1,"id":26,"name":"James&GiantPeachLLC"},{"noAssets":1,"id":27,"name":"WitchesCo"},{"noAssets":1,"id":32,"name":"FantasticFox"},{"noAssets":1,"id":41,"name":"Twits"},{"noAssets":1,"id":42,"name":"BoyCorp"},{"noAssets":1,"id":45,"name":"MagicFinger"}]

you can extract the “id” from your desired org for use in the Asset Details request.

Requesting Asset Details

Here is the GET request endpoint to get a list of org id's:

https://{{Instance}}.telematics.guru/v3/assets/{{yourorgid}}

Your instance will be the underlying server that hosts your Organisations on TG prefixed with “api-”. For example: “api-apac03” or “api-emea02”. Your org id should be taken from the organisations list request above and will be an integer.

Example: 

https://api-apac02.telematics.guru/v3/assets/123

Your authorisation should use the API key auth, or the Bearer Token and contain the access token from the authorisation step.

The body should be empty.

The response will look like this:

[
    {
        "departmentId": null,
        "projectId": null,
        "statusHumanized": "Parked at Brakfontein Road, Louwlardia for 1 week, 3 days",
        "isTripBased": true,
        "deviceTypeId": 7,
        "deviceSerial": "123456",
        "odometerMeters": 8203365,
        "runSeconds": 3483678,
        "runSeconds2": null,
        "ratePerHour": 0.0,
        "ratePerKM": 0.0,
        "organisationId": 26,
        "inOrEnteringRecoveryMode": false,
        "immobilisedOrAboutToBeImmobilised": false,
        "id": 213,
        "assetTypeId": 43,
        "name": "Jimbo's Hunk of Junk",
        "code": null,
        "speedKmH": 0,
        "inTrip": false,
        "batteryLevelStatus": 0,
        "lastConnectedUtc": "2026-07-25T13:51:14.973",
        "allocatedDriverId": null,
        "lastLatitude": -25.9119644,
        "lastLongitude": 28.1685365,
        "isEnabled": true,
        "heading": 0
    },
    {
        "departmentId": null,
        "projectId": null,
        "statusHumanized": "Parked at Brakfontein Road, Louwlardia for 4 mins",
        "isTripBased": true,
        "deviceTypeId": 7,
        "deviceSerial": "987654",
        "odometerMeters": 2514477,
        "runSeconds": 631655,
        "runSeconds2": null,
        "ratePerHour": 0.0,
        "ratePerKM": 0.0,
        "organisationId": 26,
        "inOrEnteringRecoveryMode": false,
        "immobilisedOrAboutToBeImmobilised": false,
        "id": 215,
        "assetTypeId": 43,
        "name": "Galardo #8",
        "code": null,
        "speedKmH": 0,
        "inTrip": false,
        "batteryLevelStatus": 0,
        "lastConnectedUtc": "2058-07-21T02:37:53.393",
        "allocatedDriverId": null,
        "lastLatitude": -25.9123652,
        "lastLongitude": 28.170571,
        "isEnabled": true,
        "heading": 0
    }

Need to Update Asset Details in Bulk?

Updating Asset Details via the Telematics Guru API  will assist you to update your asset details in bulk.

What Next?

Another option for integrating is to use alerts to generate webhooks. This is useful when you want to receive targeted event information.