Driver Display Names

Overview

When tracking a fleet of devices, raw device tokens like 1e653223-8efe-4904-baaa-23f0972924e0 provide no meaningful context. Driver Display Names replace these tokens with human-readable identifiers — such as a driver's name, email, or your own internal reference — across every surface of the tracking service.

Where display names appear:

• Map marker popups in the embedded tracker
• Share pages seen by your customers (e.g. "Your driver: John Smith")
• API responses when querying device positions
• WebSocket messages in real-time data streams

One-time setup, automatic everywhere. Refresh metadata for your instance once. After that, display names are resolved automatically on every map view, share page, and API call — no additional integration work required.

How It Works

Display names are resolved from driver profiles stored in the Telematics User Service. You choose which profile field to display for each device. If the chosen field is empty, the system automatically tries alternatives using a fallback chain:

1. Your chosen field (e.g. full_name, nickname, email)
2. full_name
3. nickname
4. email
5. client_id
6. Raw device token (last resort)

This ensures every device always has a display name — the system never returns a blank value.

Available Display Fields

Setting Up Display Names

Method 1: Refresh from User Service (Recommended)

Fetch the latest profiles from the Telematics User Service and compute display names automatically. This is the recommended first step when setting up tracking for a new instance.

Refresh all devices in an instance:

curl -X POST "https://portal-apis.telematicssdk.com/realtime/api/v1/devices/metadata/refresh?instance_id=YOUR_INSTANCE" \
  -H "Authorization: Bearer YOUR_JWT"

Refresh a single device:

curl -X POST "https://portal-apis.telematicssdk.com/realtime/api/v1/devices/DEVICE_TOKEN/metadata/refresh?instance_id=YOUR_INSTANCE" \
  -H "Authorization: Bearer YOUR_JWT"

Refresh a specific subset of devices:

curl -X POST "https://portal-apis.telematicssdk.com/realtime/api/v1/devices/metadata/refresh?instance_id=YOUR_INSTANCE" \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{ "device_tokens": ["token-1", "token-2", "token-3"] }'

Method 2: Choose Which Field to Display

If profiles have already been loaded, you can switch which field is shown without re-fetching from the User Service. This is useful for customizing the display per device or across the fleet.

Set the display field for a single device:

curl -X PATCH "https://portal-apis.telematicssdk.com/realtime/api/v1/devices/DEVICE_TOKEN/metadata/display-field?instance_id=YOUR_INSTANCE" \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{ "display_field": "nickname" }'

Set display fields for multiple devices in bulk:

curl -X POST "https://portal-apis.telematicssdk.com/realtime/api/v1/devices/metadata/display-field/bulk?instance_id=YOUR_INSTANCE" \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "mappings": [
      { "device_token": "token-1", "display_field": "full_name" },
      { "device_token": "token-2", "display_field": "email" },
      { "device_token": "token-3", "display_field": "client_id" }
    ]
  }'

Method 3: Read Current Metadata

Retrieve the current display name configuration and full profile for a device:

curl "https://portal-apis.telematicssdk.com/realtime/api/v1/devices/DEVICE_TOKEN/metadata?instance_id=YOUR_INSTANCE" \
  -H "Authorization: Bearer YOUR_JWT"

Response:

{
  "device_token": "1e653223-8efe-4904-baaa-23f0972924e0",
  "instance_id": "your-instance-id",
  "display_field": "full_name",
  "display_value": "John Smith",
  "profile": {
    "full_name": "John Smith",
    "first_name": "John",
    "last_name": "Smith",
    "email": "[email protected]",
    "phone": "+1 555 123 4567",
    "nickname": null,
    "client_id": "DRV-0042"
  }
}

List all devices with metadata (paginated):

curl "https://portal-apis.telematicssdk.com/realtime/api/v1/devices/metadata?instance_id=YOUR_INSTANCE&limit=50&offset=0" \
  -H "Authorization: Bearer YOUR_JWT"

Where Display Names Appear

Recommended Workflow

1. Initial setup — Call the bulk refresh endpoint to load profiles for all devices in your instance
2. Customize (optional) — Use the display field endpoints to switch individual devices to a different field (e.g. nickname for some, client_id for others)
3. Done — Display names are now resolved automatically on all tracking surfaces

If driver profiles change in the Telematics User Service, call the refresh endpoint again to pick up the updates.

API Endpoint Summary

All endpoints require instance_id as a query parameter and Authorization: Bearer {jwt} header.