Getting Started
General
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)://api.itrack.live/v2/
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:
/resource/sub_resource/action(parameter1,parameter2,[parameter3])
Which means that you should use the following URL:
http(s)://api.itrack.live/v2/resource/sub_resource/action
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):
parameter=value&meter=value&hash=a6aa75587e5c59c32d347da438505fc3
(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
Errors
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
}
}
{
"success": true,
"notifies": [
{
"id": 1,
"notify_name": "test",
"phones": "+493514223894,+493514222180",
"emails": "test@gmail.com",
"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:
http://api.itrack.live/v2/user/auth?login=demo&password=demo (GET method is used for demonstration purposes only!)
Format for requests and responses
To make API call, for example, resource/action() send http GET or POST request to http://api.itrack.live/v2/resource/action/
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.
| code | description | HTTP code |
| 1 | Database error | 500 |
| 2 | Service Auth error | 403 |
| 3 | Wrong user hash | |
| 4 | User not found or session ended | |
| 5 | Wrong request format | |
| 6 | Unexpected error | 500 |
| 7 | Invalid parameters | |
| 8 | Queue service error, try again later | 503 |
| 9 | Too large request | 412 |
| 11 | Access denied | 403 |
| 12 | Dealer not found | |
| 13 | Operation not permitted | 403 |
| 14 | Database unavailable | 503 |
| 15 | Too many requests (rate limit exceeded) | 429 |
| 101 | In demo mode this function is disabled | 403 |
| 102 | Wrong login or password | |
| 103 | User not activated | |
| 111 | Wrong handler | |
| 112 | Wrong method | |
| 201 | Not found in database | |
| 202 | Too many points in zone | |
| 203 | Delete entity associated with | |
| 204 | Entity not found | 404 |
| 206 | Login already in use | |
| 207 | Invalid captcha | |
| 208 | Device blocked | 403 |
| 209 | Failed sending email | |
| 210 | Geocoding failed | |
| 211 | Requested time span is too big | |
| 212 | Requested limit is too big | |
| 213 | Cannot perform action: the device is offline | |
| 214 | Requested operation or parameters are not supported by the device | |
| 215 | External service error | |
| 217 | List contains nonexistent entities | |
| 218 | Malformed external service parameters | |
| 219 | Not allowed for clones of the device | 403 |
| 220 | Unknown device model | |
| 221 | Device limit exceeded | 403 |
| 222 | Plugin not found | |
| 223 | Phone number already in use | |
| 224 | Device ID already in use | |
| 225 | Not allowed for this legal type | 403 |
| 226 | Wrong ICCID | |
| 227 | Wrong activation code | |
| 228 | Not supported by sensor | |
| 229 | Requested data is not ready yet | 404 |
| 230 | Not supported for this entity type | |
| 231 | Entity type mismatch | 409 |
| 232 | Input already in use | |
| 233 | No data file | |
| 234 | Invalid data format | |
| 235 | Missing calibration data | |
| 236 | Feature unavailable due to tariff restrictions | 402 |
| 237 | Invalid tariff | |
| 238 | Changing tariff is not allowed | 403 |
| 239 | New tariff doesn't exist | 404 |
| 240 | Not allowed to change tariff too frequently | 403 |
| 241 | Cannot change phone to bundled sim. Contact tech support. | |
| 242 | There were errors during content validation | |
| 243 | Device already connected. | |
| 244 | Duplicate entity label. | |
| 245 | New password must be different | |
| 246 | Invalid user ID | |
| 247 | Entity already exists | 409 |
| 248 | Wrong password | |
| 249 | Operation available for clones only | 403 |
| 250 | Not allowed for deleted devices | 403 |
| 251 | Insufficient funds | 403 |
| 252 | Device already corrupted | |
| 253 | Device has clones | |
| 254 | Cannot save file | 500 |
| 255 | Invalid task state | |
| 256 | Location already actual | |
| 257 | Registration forbidden | 403 |
| 258 | Bundle not found | 404 |
| 259 | Payments count not comply with summary | |
| 260 | Payments sum not comply with summary | |
| 261 | Entity has external links | 403 |
| 262 | Entries list is missing some entries or contains nonexistent entries | |
| 263 | No change needed, old and new values are the same | |
| 264 | Timeout not reached | 403 |
| 265 | Already done | 403 |
| 266 | Cannot perform action for the device in current status | 403 |
| 267 | Too many entities | |
| 268 | Over quota | 402 |
| 269 | Invalid file state | |
| 270 | Too many sensors of same type already exist | |
Constants
- 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