The Telematics Guru Client API v3.0 lets you manage drivers programmatically: create, edit, bulk-import, enable or disable, delete, and control which assets a driver may use. This includes setting Driver ID data such as iButton, RFID, Wiegand, Bluetooth, or PIN identifiers. Use it for initial data migrations or scheduled syncs from an external HR or fleet system.

Before You Start

Interactive documentation for every endpoint and schema is available in the Swagger UI for your instance. First find your instance (for example apac01, amer03), then open:

https://api-<yourinstance>.telematics.guru/swagger/index.html?urls.primaryName=3.0

You will need your organisation ID for every driver call. If you don't know it, retrieve it from the GraphQL API using the organisations query.

Authentication

All endpoints require a Bearer token in the Authorization header:

Authorization: Bearer {your_token}

Obtain a 24-hour token from the authenticate endpoint:

POST https://api-<yourinstance>.telematics.guru/v3/user/authenticate

The request body should contain:

• username: your TG username
• password: your TG password
• grant_type: password
• otp: your one-time passcode, if your account has one (enter it quickly, as it expires within seconds)

The response contains an access_token (plus token_type and expires_in). Use the access_token value as the Bearer token for all subsequent calls. For long-lived integrations you can instead generate a TG API key so your application does not rely on frequently regenerating a 24-hour token.

Create or Edit a Driver

A single endpoint handles both creating and editing (an "upsert"):

POST /v3/organisation/{organisationId}/driver

• Omit driverId (or send 0) to create a new driver.
• Provide the ID of an existing driver to update it instead.

Example request body creating an iButton driver:

{
  "name": "Jane Doe",
  "idType": 2,
  "idData": "01000002A1B2C3D4",
  "isEnabled": true
}

The request is validated for: a name; a driver code within the allowed length; a department that belongs to the organisation; and a supported idType / idData combination. Creating a driver whose idType and idData match a driver already in the organisation is rejected rather than merged.

isEnabled is optional. Omit it on an update and the driver keeps its current enabled state, so a sync that does not manage enablement will not accidentally re-enable a retired driver. A new driver is created enabled unless you send false.

Driver ID Data (including iButton)

Driver ID identifiers are set with two fields: idType (which kind of identifier) and idData (the identifier value). The exact ID types available to your organisation are returned by:

GET /v3/organisation/{organisationId}/drivers/idtypes

Build any picker in your integration from this endpoint rather than hardcoding numbers, since supported types can change between releases. Each type includes an isHex flag that tells you how to format idData:

• isHex: true: idData is an uppercase hex string, for example an iButton value like 01000002A1B2C3D4.
• isHex: false: idData is plain text, for example 1234 for a 4-digit PIN.

A typical response looks like this:

Values returned by the read endpoints use the same format the create and update endpoints accept (hex types uppercase), so a value read from the API can be sent straight back without conversion. For help formatting a specific identifier, contact the Digital Matter team.

Worked Example (cURL)

Authenticate, then create an iButton driver:

# 1. Authenticate
curl -X POST "https://api-<yourinstance>.telematics.guru/v3/user/authenticate" \
  -H "Content-Type: application/json" \
  -d '{ "username": "you@example.com", "password": "***", "grant_type": "password", "otp": "123456" }'
# returns { "access_token": "***", "token_type": "bearer", "expires_in": 86399 }

# 2. Create an iButton driver
curl -X POST "https://api-<yourinstance>.telematics.guru/v3/organisation/238/driver" \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Jane Doe", "idType": 2, "idData": "01000002A1B2C3D4", "isEnabled": true }'
# returns { "success": true, "driverId": 4567, "message": null }

Bulk Import

To create or update many drivers at once, use the bulk endpoint (up to 1,500 drivers per call):

POST /v3/organisation/{organisationId}/drivers/bulk

Each entry follows the same rules as the single-driver endpoint: created when driverId is omitted or 0, updated otherwise, with the same validation and the same optional isEnabled behaviour.

Entries that fail validation, for example a bad department, an unsupported ID type, or a name that is too long, are reported individually with their own error message, and a failing entry does not stop the rest of the batch from being processed. However, all valid entries are saved together in a single transaction: if the save fails for any reason, none are persisted. Always check the top-level success flag as well as each item's result before assuming the batch completed.

Enable/Disable vs. Delete

To retire a driver, disable them rather than deleting:

PATCH /v3/organisation/{organisationId}/driver/{driverId}/enabled

Disabling preserves the driver's trip and time-and-attendance data for reporting. Note that disabling a driver also removes their allowed-asset assignments; if you re-enable them later, set the asset list again using the assets endpoint below.

Deleting is permanent and destructive:

DELETE /v3/organisation/{organisationId}/driver/{driverId}

Assign Assets to a Driver

List the assets available for assignment, each with an allowedToDrive flag for this driver:

GET /v3/organisation/{organisationId}/driver/{driverId}/assets

Set the assets a driver may drive:

POST /v3/organisation/{organisationId}/driver/{driverId}/assets

This replaces the driver's entire asset list. It is not an incremental add or remove, so include every asset ID the driver should be able to drive, not just the new ones. Submitting an empty list removes all of the driver's asset assignments. Only assets configured for custom driver-list management can be assigned; other or disabled assets are rejected with an error identifying the problem.

Reading Drivers

To retrieve drivers, either use the REST list endpoint:

GET /v3/organisation/{organisationId}/drivers

This returns every driver, including disabled ones. It is not paginated, so for a very large organisation consider caching the response. Alternatively, use the GraphQL API and its drivers connection when you need field selection, filtering, or pagination.

Related Articles

• Driver Management in Telematics Guru: managing drivers in the web app.
• Driver ID Options: reader interfaces and hardware (iButton, Wiegand, RFID, Bluetooth, keypads).
• GraphQL API for Telematics Guru: reading and filtering telematics data.