Fleetmap API Reference
Read live vehicle positions, pull trip and stop reports, manage devices and geofences, and send commands to trackers. Camera photos and clips use a second prefix.
https://api.pinme.io/REST routes start with /api and take a bearer token, Basic auth, or a session cookie. Camera routes start with /pinmeapi and only accept the session cookie.
Sent as Authorization: Bearer when you try an endpoint. Login and camera routes use the session cookie instead. The token stays in this browser tab, and every request goes to the live API.
2026-11-17T08:00:00ZAuthentication
Every endpoint except the session calls needs credentials. A request without them returns 401 Unauthorized. Pick one method:
1. API token (recommended for integrations)
Call POST /api/session with your email and password. The user it returns includes a token (created on first login if the account did not have one). Send that value as a bearer token on later calls:
curl https://api.pinme.io/api/devices \
-H "Authorization: Bearer YOUR_TOKEN"A token is at least 16 characters of letters, digits and hyphens. GET /api/session returns the same user, and the same token, while you are logged in. Try it on this page fills the box above from a successful login.
2. HTTP Basic
Your Fleetmap login email and password. Simple, but it sends the password on every call, so prefer a token for anything long-running.
curl -u "you@company.com:password" https://api.pinme.io/api/devices3. Session cookie
Call POST /api/session once and reuse the JSESSIONID cookie it returns. This is what the WebSocket, the web app, and camera routes use. The same response includes the user's token (created if missing), which you can send as a bearer token instead of the cookie.
curl -c cookies.txt -d "email=you@company.com&password=secret" \
https://api.pinme.io/api/session
curl -b cookies.txt https://api.pinme.io/api/devicesreadonly user cannot create, change or delete anything.Conventions
Repeated query parameters
Filters that take several values repeat the name: ?deviceId=12&deviceId=15&groupId=3.
Status codes
| Code | Meaning |
|---|---|
| 200 | Success. The body holds the object or list. |
| 202 | Command accepted and queued. The device is offline and gets it when it reconnects. |
| 204 | Success, no body (deletes, logout, emailed reports). |
| 400 | The request was understood but refused: bad parameter, missing permission, device limit reached, or read-only user. The body is a plain-text reason. |
| 401 | Missing or wrong credentials. |
| 404 | Object not found, or no active session on GET /api/session. |
Attributes
Most objects carry an attributes map for extra data. On positions it holds the tracker's sensor values; on devices, users and groups it holds settings. Unknown keys are kept as-is.
Real-time updates (WebSocket)
To follow vehicles live, open a WebSocket instead of polling /api/positions.
wss://api.pinme.io/api/socketAuthenticate in one of two ways:
- Session cookie: call
POST /api/sessionfirst and open the socket with the sameJSESSIONIDcookie. - Token: open the socket without a cookie and send your API token as the first text message.
The server first sends the latest position of every vehicle, then pushes a message whenever something changes. Each message is a JSON object with one or more of these keys:
{
"positions": [ { "deviceId": 1042, "fixTime": "2026-11-17T09:12:03.000+00:00",
"latitude": 38.7223, "longitude": -9.1393, "speed": 23.2, ... } ],
"devices": [ { "id": 1042, "status": "online", "lastUpdate": "..." } ],
"events": [ { "type": "geofenceEnter", "deviceId": 1042, "geofenceId": 77, ... } ]
}// Browser or Node (ws) example
const ws = new WebSocket("wss://api.pinme.io/api/socket");
ws.onopen = () => ws.send("YOUR_TOKEN");
ws.onmessage = (m) => {
const data = JSON.parse(m.data);
(data.positions || []).forEach(p => console.log(p.deviceId, p.latitude, p.longitude));
};Data models
The main objects returned by the API. Every object also has an id (number) and an attributes map.
Common position attributes
What appears in position.attributes depends on the tracker model. These keys are the most common:
| Key | Meaning |
|---|---|
| ignition | Ignition on (true) or off |
| motion | Vehicle is moving |
| totalDistance | Odometer computed by the platform, meters |
| odometer | Odometer reported by the vehicle (CAN/OBD), meters |
| distance | Distance since the previous position, meters |
| hours | Engine hours, milliseconds |
| power | Vehicle supply voltage, volts |
| batteryLevel | Internal battery, percent |
| fuel | Fuel level, liters (when a fuel sensor is fitted) |
| sat / rssi | GPS satellites in use / GSM signal |
| driverUniqueId | Driver identification (iButton, RFID, card) |
| input / output | Digital input and output states |
| blocked | Engine immobilizer active |
| alarm | Alarm raised on this position (see below) |
| adasAlarmType / dmsAlarmType | Camera (ADAS / driver monitoring) alarm type, e.g. fatigue, distraction, phone, smoking |
| adasAlarmLevel / dmsAlarmLevel | Severity level reported by the camera with that alarm |
| alarmIdentifier | Unique id of a camera alarm (hex string). Use it to fetch the alarm's photos and video |
| videoResources | Reply to a videoList command: a JSON string with the recordings found (see Video commands) |
Alarm values
Event types
Used by /api/reports/events?type=, notifications, and WebSocket events.
Command types
Not every tracker supports every command. Pass one of these values as type on POST /api/commands/send.
Video commands (cameras)
Sent with POST /api/commands/send; the parameters go in attributes. A 200 only means the command was sent to the camera. The camera answers later, as a new position of the device, which you can read over the WebSocket or with GET /api/positions.
| Type | Attributes | What it does |
|---|---|---|
| videoList | index (channel, 0 = all), startTime, endTime (ISO 8601), alarmFlag (0 = all recordings) | Lists the recordings on the camera's SD card. The reply is the position attribute videoResources. |
| videoStart | server, port, index (channel) | Starts a live stream to server:port. |
| videoStop | index (channel) | Stops the live stream on that channel. |
| videoPlayback | server, port, index, startTime, endTime, resourceType, streamType, storageType | Streams a recording to server:port. Take the last three values from the videoResources item. |
videoResources is a JSON string holding an array. Each item has channel, startTime and endTime (milliseconds since 1970, UTC), alarmFlag, resourceType, streamType, storageType and fileSize (bytes).
videoStart and videoPlayback make the camera send video in the JT/T 1078 protocol to the server and port you give. That server has to understand JT/T 1078; it is not a file you download from this API. For alarm photos and clips, use Camera media.Questions about API access: Fleetmap support.