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

The TG API requires the use of a bearer token, which lasts for 24 hours and can be obtained by providing a valid TG username and password. 

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

https://{{Instance}}/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}}/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 Bearer Token auth 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}}/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/v3/assets/123

Your authorisation should use Bearer Token auth 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.