EasyTrack API reference

Every endpoint you can integrate into your own system or external app: authentication, trackers, real-time GPS positions, vehicles, geofences, agent assignments, alerts, reports and share-links.

Overview

The EasyTrack API is a JSON REST API hosted on Cloudflare (edge, EU region). All requests use HTTPS. Responses are application/json (except CSV/PDF exports). Real-time tracking data comes from Teltonika / FMC trackers and is available a few seconds after the server receives it.

Base URL & formats

https://api.easytrack.ch

Every endpoint below is relative to this base. Example: GET /devices → https://api.easytrack.ch/devices.

Authentication

Almost every endpoint requires a Bearer token. You obtain the token in two steps: request an OTP code by email, then verify the code. Then add the Authorization header to every request:

Authorization: Bearer <your_token>
Content-Type: application/json

Your first call

1 · Request a code

curl -X POST https://api.easytrack.ch/auth/request-code \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.ch","lang":"en"}'

2 · Verify the code and get the token

curl -X POST https://api.easytrack.ch/auth/verify-code \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.ch","code":"123456"}'
# => { "success": true, "token": "…", "expires_at": "…", "user": { … } }

3 · List your trackers

curl https://api.easytrack.ch/devices \
  -H "Authorization: Bearer <token>"

In JavaScript (fetch):

const res = await fetch("https://api.easytrack.ch/devices", {
  headers: { Authorization: `Bearer ${token}` }
});
const { devices } = await res.json();

Endpoint families

Authentication — login & session

{
  "email": "you@example.ch",
  "lang":  "en"          // optional (fr, de, en, it…)
}

{ "success": true, "message": "Code sent", "expires_in": 600 }

{ "email": "you@example.ch", "code": "123456" }

{
  "success": true,
  "token": "…",
  "expires_at": "2026-08-01T10:00:00.000Z",
  "user": { "id": 42, "email": "you@example.ch", "role": "client", "two_factor_enabled": false }
}

{ "success": true, "requires_2fa": true, "pending_token": "…" }

{ "pending_token": "…", "code": "654321" }

{ "email": "you@example.ch" }

Authentication — 2FA & profile

Trackers (devices)

A device is a GPS tracker identified by its imei. The endpoints below only return the trackers on your account (and those shared with you).

{
  "success": true,
  "source": "known_devices",
  "devices": [
    {
      "id": 12, "imei": "350612073912345", "name": "Truck 1",
      "status": "online",
      "last_latitude": 46.204, "last_longitude": 6.143,
      "last_speed": 0, "last_heading": 180, "last_battery": 87,
      "last_position_at": "2026-07-11 06:12:33",
      "vehicle_plate": "GE 123456", "vehicle_name": "Van",
      "device_type": "FMC003", "tracker_model": "FMC003",
      "fuel_level_percent": 64, "fuel_level_litres": 32.4,
      "odometer_km_real": 84520, "odometer_km_calculated": 84310,
      "consumption_l_per_100km": 7.4,
      "active_agent_name": null, "is_shared": false
    }
  ]
}

{ "imei": "350612073912345", "name": "Truck 1" }   // name optional

{
  "name": "Truck 1", "is_active": true,
  "vehicle_plate": "GE 123456", "vehicle_name": "Van",
  "vehicle_type": "van", "vehicle_model": "Ford Transit",
  "vehicle_color": "#2563eb", "vehicle_assigned_to": "John"
}

GPS positions

{ "success": true, "imei": "…", "page": 0, "page_size": 5000,
  "count": 5000, "has_more": true, "positions": [ … ] }

Position fields

OBD and vehicle telemetry

OBD trackers (FMC003 and the same family) send the latest onboard values. GET /devices already includes device_type and the summary below. GET /devices/imei/{imei}/obd returns every raw AVL value plus the same summary.

Summary fields

Other OBD values stay in values, keyed by Teltonika AVL id: VIN 256, RPM 36, coolant 32, engine load 31, throttle 41, fuel rate 60, DTC count 30, fault codes 281, hybrid battery 411 and battery consumption 412 (kWh/100 km).

The hours endpoint uses from and to as YYYY-MM-DD HH:MM:SS. Without a saved schedule, the whole day counts as inside.

Position export (GET /positions/export) returns the raw rows. In the manager, CSV and JSON exports let you choose which columns to keep. GeoJSON, GPX and KML always keep the geometry.

Vehicles

Vehicle record linked to a tracker (plate, model, color, assigned person).

Body (POST/PUT)

{
  "plate": "GE 123456", "name": "Van",
  "vehicle_type": "van", "vehicle_model": "Ford Transit",
  "color": "#2563eb", "device_id": 12, "assigned_to": "John"
}

Geofences

Circular zones, drawn polygons, or an official outline (country, region, municipality, city). Entry and exit can each raise an alert.

kind is country, region, commune or city. Pass the hit (source, osmId or layer + featureId) to the geometry endpoint. The rings are [lat, lng]. Save them as polygon.

Body (POST/PUT)

{
  "name": "Geneva depot",
  "latitude": 46.204, "longitude": 6.143, "radius": 150,
  "polygon": [[[6.14, 46.20], [6.16, 46.20], [6.16, 46.22], [6.14, 46.20]]],
  "type": "vehicle",
  "vehicle_id": 12,
  "color": "#ef4444",
  "alert_on_enter": true, "alert_on_exit": true,
  "description": "Parking zone"
}

A circle uses latitude, longitude and radius (metres). A polygon or a place outline uses polygon. Latitude and longitude are then optional: the centre is computed from the ring.

Agent assignments

Manage your agents (promoters/drivers) and the allocation of trackers to an agent for a session.

Alerts

Notification rules (low battery, speeding, zone enter/exit, etc.).

Share-links (public sharing)

Create temporary share links that let anyone follow certain trackers without an account.

Reports

Scheduled reports (PDF) and tracking of their runs.

Notifications & settings

Public sharing

{ "success": true, "devices": [ … ], "imeis": ["…"], "expires_at": "…" }

Conventions — JSON responses

Successful responses usually carry success: true and the resource (or a list).

{ "success": true, "devices": [ … ] }

Errors

Errors return an appropriate HTTP status and a { "error": "message" } body.

Pagination

Position lists are limited via limit. The history export (/positions/export) is paginated in pages of 5000 points: iterate over page while has_more is true.

Dates & time zones

• Tokens/sessions use ISO 8601 UTC (2026-07-11T06:12:33.000Z).
• Position timestamps (server_timestamp) use the YYYY-MM-DD HH:MM:SS format in UTC.
• The from/to filters accept the same format as the target field.