0 mins to read•
Custom Telematics Devices and MyGeotab
0 mins to read•
Learn how to integrate custom telematics devices onto the MyGeotab platform, access additional resources to support custom telematics integration, and browse frequently asked questions about the integration process and device administration.
Reseller and Partner Guide
This document provides a high level overview of the process Resellers and Partners need to follow to integrate Custom Telematics Device data onto the MyGeotab platform.
MyGeotab accepts data logging from both Geotab GO devices and telematics devices not manufactured by Geotab (Custom Telematics Devices), at the same time. MyGeotab provides a unified interface, allowing fleets to manage vehicles and other operations, regardless of the telematics hardware that is installed.
Custom Telematics Device integrations are made possible by sending device data to Geotab’s Data Intake Gateway APIs. Custom Telematics Devices are managed using the MyAdmin APIs. This is illustrated in the following application integration workflow:
Each custom telematics device requires a unique Geotab serial number. Geotab serial numbers for custom telematics devices are generated as needed by the integrator using the ProvisionDevice MyAdmin API calls. A Product ID that is unique to your hardware will be provided by Geotab to use with this API call.
Your telematics unit will likely have an IMEI or other unique identifier, but this is not used by the MyGeotab platform or Data Intake Gateway (DIG). Integrators must maintain a mapping of device IMEI/serial number to Geotab serial number so that data for your telematics unit can be sent to the correct MyGeotab asset using DIG. The below diagram shows an example of how device identifiers and serial numbers are used in each environment.
When building the integration, the following resources are required::
Integrating Custom Telematics Devices with MyGeotab requires the use of Geotab APIs and collaboration between Resellers and/or Partners and the Geotab Solutions Team.
Fill out the Custom Telematics Device Information Request Form, providing as much detail on the integration you wish to build as possible. Once you submit this form, a member of Geotab’s Solutions team will contact you and take you through a vetting/onboarding process. Once this is complete, you will be provided with a Product ID to use to create serial numbers to allow your Custom Telematics Device to exist in the MyGeotab environment.
If you are a Reseller and you have Custom Telematics Devices to integrate into a customer’s database:
Please refer to the Integrator as Reseller Billing Process Flow for more information on integration workflow as a Reseller.
If you are a Partner beginning the implementation process for a Custom Telematics Device integration:
Register a new Partner account in MyAdmin. Notify the solutions engineer fielding your request from the Product ID form of the account you created, and they will work with you to ensure proper MyAdmin access.
Please refer to the Partner to Reseller Billing Process Flow for more information on integration workflow as a Partner.
Contact your assigned member from Geotab’s Solutions team to assist with adding the necessary MyAdmin API roles to your MyAdmin accounts.
Please see the Service Account Best Practice section for additional information.
Develop software that authenticates via MyAdmin, then provisions custom telematics devices and sends their data points to MyGeotab. Note that device administration, specifically the software to provision devices mentioned above, is completed via the MyAdmin API. Additionally, device data must be sent via the Data Intake Gateway. For more information, please refer to the Data Intake Gateway Guide.
Geotab’s Solutions team will:
As best practice, integrators should set up two service accounts:
This ensures that the account that sends data to DIG is isolated from other service accounts that would interact with the MyAdmin API. In situations where Resellers are working with Integrators and/or Partners, this best practice can be used to allow Resellers to control device management, while allowing Integrators and/or Partners to handle sending custom telematics data.
✱ NOTE: The required device management roles are still required for a reseller’s account when provisioning devices through MyAdmin.
A Custom Telematics Device is terminated using the TerminateDeviceBilling MyAdmin API method.
✱ NOTE: Terminating a Custom Telematics Device using the API only stops billing. You must also stop sending telematics data to complete termination. Billing will be restarted automatically if you continue to send data after terminating billing.
Custom Telematics Device (CTD) integrations rely on the MyAdmin API to manage devices and the DIG API to push device data to Geotab systems. To maintain data privacy, Geotab has limited visibility of the records submitted through the DIG APIs. We recommend that integrators maintain logs of the records submitted to DIG to aid with support and troubleshooting that may be required. We recommend storing the following:
Use the InvalidRecords workflow with DIG to check for rejected records. Log responses from this endpoint as well.
Navigate to https://myadmin.geotab.com/login/register to create an account. Refer to the for more information.
Use Reseller or Partner account types for Custom Telematics Device integrations. Please choose what is applicable based on your professional relationship with Geotab.
After you submit the Custom Telematics Device Information Request Form you will be contacted by a member of Geotab’s Solutions team who will assist with adding roles to your MyAdmin account.
These MyAdmin roles are needed for the following purposes:
A Product ID is a unique identifier provided by Geotab to the Integrator which enables the Integrator to send data to the MyGeotab platform. This also allows Geotab to identify the Integrator of each Custom Telematics Device.
A Product ID is needed to provision serial numbers.
A serial number is needed for each Custom Telematics Device. The serial number is similar to a standard Geotab GO device serial number. It consists of a 12-digit alphanumeric string and contains two pieces of important information:
For example, a serial number for a Custom Telematics Device looks like this:
where C1 indicates the custom device type, and 800-000-0001 is the unique identifier.
Once these serial numbers are made, they can be added to a MyGeotab database and data can be associated with that serial number in MyGeotab.
A new Product ID is required whenever a new integration is built or when a new device model is integrated. This allows Geotab to better track and understand various custom telematics integrations.
There is a monthly fee associated with each active Custom Telematics Device. For more information on pricing, please contact your Partner Account Manager or Business Development Manager.
Geotab will support and consult for the partners’ development of a new integration at no charge.
It is recommended that Integrators read the documents listed under Integrator Resources. After the Custom Telematics Device Information Request Form is submitted, a member of Geotab’s Solution engineering team is assigned to answer questions and provide resources as needed. Additionally, you can reach out to firstname.lastname@example.org for technical assistance.
These two terms refer to how the telematics device will be presented on MyGeotab’s vehicle page. A CustomVehicleDevice allows for more fields to be associated with the device. The properties associated with these options are available on the MyGeotab SDK site, as well as additional information about Geotab’s device options.
Please see the DIG API Reference section of the Data Intake Gateway Guide, which includes a link to the OpenYAML specification for all the supported record type models, and the appendix of DIG API Endpoint Workflow Guide, which provides additional context and content documentation for some record types.
ApiUser = Authenticate(string userName, string password)
This method authenticates the user with the MyAdmin API and returns an ApiUser object. It requires the username and password of a MyAdmin account with MyAdmin API privileges. (The syntax is also available in the MyAdmin reference API)
Note that sessions will expire after a period of time. Calling a method with an expired sessionId will throw a SessionExpiredException. If this occurs, call Authenticate to obtain a new sessionId.
Below is an example of a request made to the MyAdmin API to authenticate a user:
curl --request POST \
--url https://myadmin.geotab.com/v2/MyAdminApi.ashx \
--header 'content-type: application/json' \
✱ NOTE: When performing the Authenticate call, we expect you to use the POST HTTP method to pass sensitive username and password information to Geotab.
If authentication is successful, you will see a response similar to the following:
"comments":"Special user for MyAdminApi",
✱ NOTE: The sessionID expires in approximately 20 minutes. Receiving a "SessionExpiredException" error as a result of a standard API call will require you to re-authenticate.
These methods are used to provision new devices in MyAdmin and generate new serial numbers for your devices. You will have to use only one of them:
ProvisionResult = ProvisionDevice (Guid apiKey, Guid sessionId, int productId, str promoCode)
This is a provisioning call that adds a device to MyAdmin and generates a serial number under the user’s ERP to be used for referencing or viewing the device in MyGeotab. (The syntax is also available in the MyAdmin reference API.)
ProvisionResult = ProvisionDeviceToAccount (Guid apiKey, Guid sessionId, int productId, str erpNo, str promoCode)
This is a provisioning call that adds a device to MyAdmin under the specified ERP account number to be used for referencing or viewing the device in MyGeotab. (The syntax is also available in the MyAdmin reference API.)
When the user in MyAdmin that will make this call is under more than one ERP account (or if you are not sure) use the ProvisionDeviceToAccount so you can specify the ERP account in the call.
✱ NOTE: Either of these methods only needs to be run once for each Custom Telematics Device you wish to integrate into MyGeotab.
Based on the userID, the key used to authenticate the session. This is the result.userId property from the Authenticate response above.
Identification used with the apiKey to authenticate the session. This is also found in the result.sessionId property from the authenticate response above.
Account number for new activation.
Only for ProvisionDeviceToAccount method
Optional. Applies a promo code to modify pricing if available.
See MyAdmin SDK for more details.
The following is an example of parameters that can be used to call ProvisionDevice within MyAdmin:
curl --request POST \
--url https://myadmin.geotab.com/v2/myadminapi.ashx \
--header 'Content-Type: application/json' \
If successful, the request will return a result similar to:
The returned serialNo value can now be used to add a vehicle to your MyGeotab database using the steps below.
Once your API calls are returning successfully, you can provide the end user with the serial number (the number that was returned by the ProvisionDevice method) for their Custom Telematics Device.
The end user or reseller can verify that your integration is operational by logging in to their MyGeotab database and doing the following: