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",
      "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

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 triggering alerts on enter and/or exit.

Body (POST/PUT)

{
  "name": "Geneva depot",
  "latitude": 46.204, "longitude": 6.143, "radius": 150,
  "type": "vehicle",            // or "general"
  "vehicle_id": 12,             // required if type = "vehicle"
  "color": "#ef4444",
  "alert_on_enter": true, "alert_on_exit": true,
  "description": "Parking zone"
}

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.