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.

Base URLhttps://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.

API token

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.

FormatJSON in, JSON out
DatesISO 8601 UTC, e.g. 2026-11-17T08:00:00Z
Speedknots (× 1.852 = km/h)
Distancemeters

Authentication

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:

Example
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.

Example
curl -u "you@company.com:password" https://api.pinme.io/api/devices

3. 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.

Example
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/devices
Use a dedicated API user that only has the vehicles your integration needs. Every list endpoint returns only what that user is allowed to see, and a readonly 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

CodeMeaning
200Success. The body holds the object or list.
202Command accepted and queued. The device is offline and gets it when it reconnects.
204Success, no body (deletes, logout, emailed reports).
400The request was understood but refused: bad parameter, missing permission, device limit reached, or read-only user. The body is a plain-text reason.
401Missing or wrong credentials.
404Object 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.

Example
wss://api.pinme.io/api/socket

Authenticate in one of two ways:

  • Session cookie: call POST /api/session first and open the socket with the same JSESSIONID cookie.
  • 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:

Example
{
  "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, ... } ]
}
Example
// 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));
};
The connection closes after 10 minutes without traffic. Reconnect automatically, and expect the full position snapshot again after each reconnect.

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:

KeyMeaning
ignitionIgnition on (true) or off
motionVehicle is moving
totalDistanceOdometer computed by the platform, meters
odometerOdometer reported by the vehicle (CAN/OBD), meters
distanceDistance since the previous position, meters
hoursEngine hours, milliseconds
powerVehicle supply voltage, volts
batteryLevelInternal battery, percent
fuelFuel level, liters (when a fuel sensor is fitted)
sat / rssiGPS satellites in use / GSM signal
driverUniqueIdDriver identification (iButton, RFID, card)
input / outputDigital input and output states
blockedEngine immobilizer active
alarmAlarm raised on this position (see below)
adasAlarmType / dmsAlarmTypeCamera (ADAS / driver monitoring) alarm type, e.g. fatigue, distraction, phone, smoking
adasAlarmLevel / dmsAlarmLevelSeverity level reported by the camera with that alarm
alarmIdentifierUnique id of a camera alarm (hex string). Use it to fetch the alarm's photos and video
videoResourcesReply 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.

TypeAttributesWhat it does
videoListindex (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.
videoStartserver, port, index (channel)Starts a live stream to server:port.
videoStopindex (channel)Stops the live stream on that channel.
videoPlaybackserver, port, index, startTime, endTime, resourceType, streamType, storageTypeStreams 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.