API Reference — WebSocket and API Methods

Base URL: https://portal-apis.telematicssdk.com/realtime/api/v1

All endpoints require JWT authentication unless otherwise noted:

Authorization: Bearer YOUR_JWT_TOKEN

REST API

Device Position

Retrieve the last known position for a device.

GET /devices/{device_token}/position

Query Parameters:

Response Fields:

Device Tracks

Retrieve the current trip's waypoint data.

GET /devices/{device_token}/tracks

Query Parameters:

Device Trip Details

Retrieve details about the device's latest trip.

GET /devices/{device_token}/stats

Device Metadata API

Manage device display names and profile data. See the Driver Display Names guide for a full walkthrough.

Get Device Metadata

GET /devices/{device_token}/metadata?instance_id={instance_id}

Returns: display_field, display_value, profile

List All Device Metadata

GET /devices/metadata?instance_id={instance_id}&limit=50&offset=0

Paginated list of all devices with metadata in the instance.

Set Display Field

PATCH /devices/{device_token}/metadata/display-field?instance_id={instance_id}

{ "display_field": "nickname" }

Allowed values: full_name, first_name, last_name, nickname, email, phone, client_id

Bulk Set Display Fields

POST /devices/metadata/display-field/bulk?instance_id={instance_id}

{
  "mappings": [
    { "device_token": "token-1", "display_field": "full_name" },
    { "device_token": "token-2", "display_field": "email" }
  ]
}

Refresh Device Metadata

Fetch the latest profile from the Telematics User Service and recompute display names.

Single device:

POST /devices/{device_token}/metadata/refresh?instance_id={instance_id}

All devices (or a subset):

POST /devices/metadata/refresh?instance_id={instance_id}

Optional body to limit the refresh:

{ "device_tokens": ["token-1", "token-2"] }

Location Sharing API

Create and manage live tracking links for third parties. See the Location Sharing guide for a full walkthrough.

Admin Endpoints (JWT Required)

Create Share Session

POST /sharing/sessions

{
  "device_token": "1e653223-8efe-4904-baaa-23f0972924e0",
  "instance_id": "your-instance-id",
  "expires_in_hours": 4,
  "recipient_name": "Jane Doe",
  "notes": "Your package is on the way!",
  "order_id": "ORD-2024-1234",
  "destination": {
    "latitude": 51.5074,
    "longitude": -0.1278,
    "label": "123 Main Street, London"
  },
  "share_config": {
    "show_speed": true,
    "show_heading": true,
    "show_eta": true,
    "show_destination_on_map": true
  }
}

Response (201 Created):

{
  "id": "664a1f...",
  "share_token": "Ef0XtIPPXp",
  "share_url": "https://your-frontend.com/share/Ef0XtIPPXp",
  "links": {
    "map_url": "https://your-frontend.com/share/Ef0XtIPPXp",
    "api_url": "https://your-api.com/api/v1/share/Ef0XtIPPXp",
    "ws_url": "wss://your-api.com/api/v1/share/Ef0XtIPPXp/live"
  },
  "device_token": "1e653223-...",
  "instance_id": "your-instance-id",
  "status": "active",
  "created_at": 1776000000,
  "expires_at": 1776014400
}

List Sessions

GET /sharing/sessions?instance_id={id}

Get Session

GET /sharing/sessions/{session_id}?instance_id={id}

Update Session

PATCH /sharing/sessions/{session_id}?instance_id={id}

Updatable fields: destination, share_config, notes, recipient_name, order_id

Complete Session

POST /sharing/sessions/{session_id}/complete?instance_id={id}

Cancel Session

DELETE /sharing/sessions/{session_id}?instance_id={id}

Public Endpoints (No Authentication)

These endpoints are accessed by share link recipients. No JWT is required — the share token itself serves as the access credential.

Get Shared Position

GET /share/{share_token}

Response:

{
  "status": "active",
  "driver": {
    "latitude": 51.5074,
    "longitude": -0.1278,
    "heading": 245.0,
    "speed": 12.5
  },
  "destination": { "latitude": 51.52, "longitude": -0.08, "label": "..." },
  "eta_seconds": 840,
  "order_id": "ORD-2024-1234",
  "recipient_name": "Jane Doe",
  "notes": "Your package is on the way!",
  "driver_display_name": "John Smith",
  "last_updated": 1776001200
}

Live Position Stream (WebSocket)

wss://portal-apis.telematicssdk.com/realtime/api/v1/share/{share_token}/live

• Sends initial position on connect
• Pushes position updates at the configured interval (default: every 5 seconds)
• Accepts {"type": "ping"}, responds with {"type": "pong"}
• Sends {"type": "session_ended", "reason": "..."} when session terminates
• Close code 4001: invalid or expired share token

Position message:

{
  "type": "position",
  "latitude": 51.5074,
  "longitude": -0.1278,
  "heading": 245.0,
  "speed": 12.5,
  "driver_display_name": "John Smith",
  "eta_seconds": 840,
  "timestamp": 1776001200
}

WebSocket Real-Time Streaming

For real-time tracking of all devices in an instance, connect to the main WebSocket endpoint:

wss://portal-apis.telematicssdk.com/realtime/api/v1/ws/realtime

Connection Protocol

1. Connect to the WebSocket URL
2. Authenticate by sending a JSON message with your credentials:

{
  "type": "authenticate",
  "jwt": "YOUR_JWT_TOKEN",
  "instance_id": "YOUR_INSTANCE_ID",
  "units": "metric",
  "timezone": "UTC",
  "date_format": "unix"
}

3. Receive a welcome message confirming authentication
4. Listen for real-time device position updates

Message Types

Position Update Fields

Health Check

GET /health

Returns service status. No authentication required.