Edit on GitHub


Requests made to the MyAdmin API are performed using HTTPS. The URL your web application will send its requests to is:


API request parameters and the results are transported in the lightweight JSON format. The Reference contains a listing of the methods that can be invoked, the parameters they expect, and the results they return. Requests to the API can be invoked using HTTP POST. HTTP POST requests use the JSON-RPC standard. The following sections explain how to construct HTTP POST requests to the MyAdmin API.


When using HTTP POST request to invoke an API method, the following endpoint is used:


However, instead of encoding the method name and parameters in the query string, it is passed in the HTTP body using the JSON-RPC format. The MyAdmin API supports JSON-RPC version 1.0. The following is a JavaScript example that shows how HTTP POST can be used to invoke a method.

This can be done from any language that has support for HTTP, for example the java.net.HttpUrlConnection class in Java or System.Net.HttpWebRequest in Microsoft .NET.

var request = new XMLHttpRequest();
request.open("POST", "https://myadminapi.geotab.com/v2/MyAdminApi.ashx", true);
request.setRequestHeader("Content-Type", "application/x-www-form-urlencoded");
request.onreadystatechange = function () {
   if (request.readyState === 4) {
      if (request.status === 200) {
         var json = JSON.parse(request.responseText);
         if (json.result) {
            // Work with your result
            // Simple example just alerts its presence
            alert("Received Data");
// Send the HTTP BODY in the JSON-RPC format. ID is ignored
// and can be set to -1.
// This example demonstrates authentication using HTTP POST.
var authenticateParams = {
   "id" : -1,
   "method" : "Authenticate",
   "params" : {
request.send("JSON-RPC=" + encodeURIComponent(JSON.stringify(authenticateParams)));

// Send the HTTP BODY in the JSON-RPC format. ID is ignored
// and can be set to -1.
// The method being called is “GetDevicePlans”.
// The “GetDevicePlans” method’s parameters are then passed in the “params” property
var apiMethod = {
   "id" : -1,
   "method" : "GetDevicePlans",
   "params" : {
request.send("JSON-RPC=" + encodeURIComponent(JSON.stringify(apiMethod)));

Results & Errors

A successful call to the server will result in an object with property “result”, like this:

   {"id":1,"level":1,"validForOrder":true,"name":"Pro Mode"},
   {"id":3,"level":3,"validForOrder":true,"name":"Base Mode"},
   {"id":4,"level":99,"validForOrder":false,"name":"Suspend Mode"},
   {"id":5,"level":9999,"validForOrder":false,"name":"Terminate Mode"}

However, when the call is incorrect or an error is triggered on the server, the error will be returned as an object with property “error”:

   "message":"'UnknownUser: user@geotab.com'",
      "message":"'UnknownUser: user@geotab.com'"

The properties of the error object are:

nameFor all JSON-RPC errors this is always “JSONRPCError”.
messageThe description of the likely root cause of the error.
errorsAn array of individual errors that were caught. Usually, there is at least one error in this array.

The properties for objects in the “errors” array are:

nameThe name of the server exception. For example, “SecurityException”, “NullReferenceException”, etc.
messageThe description associated with the server exception.

Session expiry is an example of a case where it is useful to catch and handle errors.

Working with dates

When exchanging dates as parameters to API methods, you must ensure that they are formatted properly as an ISO 8601 string. In addition, all dates will have to first be converted to UTC in order to ensure timezone information and daylight savings times are accounted for correctly.