Getting Started


Each API resource semantically corresponds to some entity, for example: geofences, rules, objects, etc. The API calls for CRUD and other operations with these entities have similar names regardless the resource used: list/read/create/delete.

Standard workflow (example)

Let's describe standard workflow for API developer using very simple and most common example - requesting the track points data:
1. Determine URL to API calls:
   1. for iTrack ServerMate it will be http(s)://
   2. for On-Premise instances it will be http(s)://api.your_domain/
2. Authorize with user/auth(...). This API method will return the hash you should use for all your next API calls.
3. Get objects lists with tracker/list()
4. Get track lists with track/list(...)
5. Get the track itself: track/read(...)

In other words, to start working with API, the developers should have API call description (as provided herein), and know user login and password.

API Calls Format

Notation used in this doc:


Which means that you should use the following URL:


with named parameters:
  • parameter1
  • parameter2
  • parameter3 is optional

Parameters can be passed in HTTP POST (application/x-www-form-urlencoded) or GET requests (POST is highly recommended):


(hash is required for most API calls to identify user session)

Typical actions:

  • list - list all resource entities with IDs and minimum additional info
  • read - read one entity by ID
  • update - update one entity by ID
  • delete - delete one entity by ID


Common errors (should be handled for all API calls): 1-100

Resource or action specific errors: 101-200

Request and response format

To execute resource/action() send http GET or POST request to http://${API_URL}/${RESOURCE}/${ACTION}/

Response is (almost) always application/json.

On errors response will be in form:

      "success": false,
      "status": {
         "code": 1, // error code
         "description": "Database error" // error description

See Error Codes

For example to read all user's notify methods use and get response:

      "success": true,
      "notifies": [
          "id": 1,
           "notify_name": "test",
           "phones": "+493514223894,+493514222180",
            "emails": "",
            "sms_numbers": "+493514223894"
          "id": 2,
           "notify_name": null,
           "phones": "+493514222180",
           "emails": "",
           "sms_numbers": null

Or if hash is wrong:

      "success": false,
      "status": {
         "code": 4,
         "description": "User not found or session ended"

HTTP Codes

If "success" is true, HTTP code is always 200 OK (unless otherwise stated).

If there is an error, HTTP code is 400 BAD REQUEST (may vary depending on error type).

Authorization and access levels

Unless otherwise noted, every API call requires a valid user session hash (A String containing 32 hexademical characters) as "hash" parameter (see example above).

Session hash can be obtained via user/auth(login, password, [dealer_id]) API call.

Example: (GET method is used for demonstration purposes only!)

Data Types

  • bool, boolean - logical type: true of false.

  • byte - signed 8 bits integer in range [-128 .. 128].

  • short - signed 16 bits integer in range [-32,768 .. 32,767].

  • int, integer - signed 32 bits integer in range [-2,147,483,648 .. 2,147,483,647].

  • long - signed 64 bits integer in range [-9,223,372,036,854,775,808 .. 9,223,372,036,854,775,807].

  • float - signed 32 bits float number [3.40282347 x 10^38, 1.40239846 x 10^-45].

  • double - signed 64 bits float number [1.7976931348623157 x 10^308, 4.9406564584124654 x 10^-324].

  • string - string literals.

  • enum - string literals from predefined set.

  • date/time - is a string containing date/time in "yyyy-MM-dd HH:mm:ss" format (in user's timezone).

  • local_time - is a string containing local time in "HH:mm:ss" format.

  • location - is json object contains geographical coordinates

    "lat": 56.827, // latitude
    "lng": 60.594296 // longitude

  • locale - string in format "language[country]", where language is [ISO 639 alpha-2]( language code, and country is ISO 3166 alpha-2 country code, e.g. en_US or ru. User interface support only language codes: 'ru', 'en', 'es', 'ar', 'de', 'pt', 'ro' and 'uk'.

Message Formats

Format for requests and responses

To make API call, for example, resource/action() send http GET or POST request to

The response will be given in application/json format. Response fields and object structure is specific to API call.

Ensuring compatibility

Our API evolves over time, and new methods and JSON object fields are being added. We are doing our best to ensure our API remains backwards compatible with legacy API clients. However, you must ensure that any JSON object fields which are not supported by your app are ignored, and that in event if new JSON fields are returned, your application will not break. Also, sometimes, to reduce response size, JSON fields which are NULL are omitted. Your JSON parser should handle missing JSON fields as if they were NULL.

Error handling

If an error occurs, API returns special error response. You can also detect error by checking HTTP response code. If it's not 200 OK, you should parse and handle response body as an error response. In the event of error occurs, the response will be in the following format:

"success": false,
"status": {
      "code": 1, // error code
      "description": "Database error" // error description

Error codes

Default HTTP code is 400.

codedescriptionHTTP code
1Database error500
2Service Auth error403
3Wrong user hash
4User not found or session ended
5Wrong request format
6Unexpected error500
7Invalid parameters
8Queue service error, try again later503
9Too large request412
11Access denied403
12Dealer not found
13Operation not permitted403
14Database unavailable503
15Too many requests (rate limit exceeded)429
101In demo mode this function is disabled403
102Wrong login or password
103User not activated
111Wrong handler
112Wrong method
201Not found in database
202Too many points in zone
203Delete entity associated with
204Entity not found404
206Login already in use
207Invalid captcha
208Device blocked403
209Failed sending email
210Geocoding failed
211Requested time span is too big
212Requested limit is too big
213Cannot perform action: the device is offline
214Requested operation or parameters are not supported by the device
215External service error
217List contains nonexistent entities
218Malformed external service parameters
219Not allowed for clones of the device403
220Unknown device model
221Device limit exceeded403
222Plugin not found
223Phone number already in use
224Device ID already in use
225Not allowed for this legal type403
226Wrong ICCID
227Wrong activation code
228Not supported by sensor
229Requested data is not ready yet404
230Not supported for this entity type
231Entity type mismatch409
232Input already in use
233No data file
234Invalid data format
235Missing calibration data
236Feature unavailable due to tariff restrictions402
237Invalid tariff
238Changing tariff is not allowed403
239New tariff doesn't exist404
240Not allowed to change tariff too frequently403
241 Cannot change phone to bundled sim. Contact tech support.
242There were errors during content validation
243Device already connected.
244Duplicate entity label.
245New password must be different
246Invalid user ID
247Entity already exists409
248Wrong password
249Operation available for clones only403
250Not allowed for deleted devices403
251Insufficient funds403
252Device already corrupted
253Device has clones
254Cannot save file500
255Invalid task state
256Location already actual
257Registration forbidden403
258Bundle not found404
259Payments count not comply with summary
260Payments sum not comply with summary
261Entity has external links403
262Entries list is missing some entries or contains nonexistent entries
263No change needed, old and new values are the same
264Timeout not reached403
265Already done403
266Cannot perform action for the device in current status403
267Too many entities
268Over quota402
269Invalid file state
270Too many sensors of same type already exist


  • maxHistoryLimit = 1000 - maximum count of history entries from listing requests
  • maxReportTimeSpan = 120 days - maximum interval in for most requests

If you have more questions please contact our support team

Ready for the most innovative GPS tracking software?

Explore our products using demo access, or talk to our live sales team.

 Launch Demo  

Try iTrack for free

Sign up and get your own GPS tracking platform instantly! A full-featured trial version will be available within 30 days and you'll be personally guided by one of our experts

Get Started