Live truck position, one API key

Live truck driver position over an API. The driver connects from an SMS link in about a minute. No corporate account, no ELD provider, no annual contract.

What the agent can do

One key lets your AI agent or software work with your loads: create loads, read live positions and confirm deliveries — billed to your prepaid PingPoint balance. Free operations work at zero balance.

Getting a key

1. Sign up at pingpoint.suverse.io (e-mail or Google/GitHub).
2. In the cabinet open Integrations → Agent API and press Issue key.
3. The key arrives by e-mail. PingPoint never sees or stores the secret — if it's lost, re-issue a new one from the same page.

Paid operations debit your prepaid balance — top it up in the cabinet under Billing.

Access

Create a load

POST/v1/agent/loads

POST https://api.suverse.io/v1/agent/loads
Authorization: Bearer sup_agent_…
Content-Type: application/json

{
  "driverPhone": "+15551234567",
  "pickups": [
    { "facilityName": "General Mills DC", "address": "6492 Tower Lane",
      "city": "Claremore", "state": "OK", "zip": "74017" }
  ],
  "deliveries": [
    { "facilityName": "Caldwell Park Warehouse", "address": "6499 Caldwell Park Dr",
      "city": "Charlotte", "state": "NC", "zip": "28269" }
  ],
  "customerRef": "PO-483920",
  "shipperName": "General Mills",
  "carrierName": "Best Carrier LLC",
  "equipmentType": "VAN",
  "rate": 1450,
  "weight": 24000
}

Required: pickups, deliveries (address, city, state, zip each) and driverPhone — the load link is sent to that number. Everything else is optional. A load may have several pickups and deliveries. Loads are created under your account (the key identifies you) and are billed from your balance. Optional extras: shipperName, carrierName, equipmentType, customerRef (doubles as a dedup key — re-sending it returns the existing load instead of creating a duplicate), rate, weight, truckNumber, per-stop lat/lng and date, and an Idempotency-Key header for safe retries.

The response carries loadNumber, a public trackingLink for your customer and the driver app links.

Read a position

GET/v1/agent/loads/{loadNumber} — $0.02 per request

curl -H "Authorization: Bearer sup_agent_…" \
  https://api.suverse.io/v1/agent/loads/LD-2026-042317

Returns the load's live state: status, GPS track (last 500 points), stop timeline with arrival/departure timestamps, distance covered, on-time flag, dwell times and an ETA block:

{
  "loadNumber": "LD-2026-042317",
  "status": "IN_TRANSIT",
  "createdAt": "2026-08-18T14:02:11.000Z",
  "deliveredAt": null,
  "distanceMiles": 412.7,
  "onTime": null,
  "delayMinutes": null,
  "pickupDwellMinutes": 38,
  "deliveryDwellMinutes": null,
  "stops": [
    { "type": "PICKUP", "sequence": 1, "city": "Claremore", "state": "OK",
      "windowFrom": "2026-08-18T15:00:00.000Z", "windowTo": "2026-08-18T19:00:00.000Z",
      "arrivedAt": "2026-08-18T15:47:31.000Z", "departedAt": "2026-08-18T16:25:09.000Z" },
    { "type": "DELIVERY", "sequence": 2, "city": "Charlotte", "state": "NC",
      "windowFrom": "2026-08-20T12:00:00.000Z", "windowTo": "2026-08-20T16:00:00.000Z",
      "arrivedAt": null, "departedAt": null }
  ],
  "gpsTrack": [
    { "lat": 36.3126, "lng": -95.6161, "speed": 63.4, "heading": 291,
      "ts": "2026-08-18T16:25:09.000Z" }
  ],
  "pingCount": 214,
  "eta": {
    "nextStop": { "type": "DELIVERY", "sequence": 2, "city": "Charlotte", "state": "NC" },
    "receivingWindow": { "from": "2026-08-20T12:00:00.000Z", "to": "2026-08-20T16:00:00.000Z" },
    "distanceToNextStopMi": 611.4,
    "driveTimeHours": 11.2,
    "moving": true,
    "stoppedForMinutes": null,
    "etaWindow": { "from": "2026-08-20T13:05:00.000Z", "to": "2026-08-20T15:40:00.000Z" },
    "tracking": { "state": "pinging", "noDataForMinutes": null },
    "reason": null
  }
}

gpsTrack shortened here for readability — the 500 most recent points, oldest first; speed is mph, heading is degrees (0–359). Don't poll in a loop — every call is billed.

Other endpoints

Webhooks

PingPoint pushes load events to your endpoint. Self-serve: in the cabinet open Integrations → Webhooks, paste your HTTPS URL and flip the switch — no approval step, no extra cost.

Each event is a POST to your URL with a JSON body:

{
  "event": "pingpoint.status.changed",
  "version": "1.0",
  "id": "a3f1c2e4-…",                          // unique per delivery
  "createdAt": "2026-08-19T14:02:11.000Z",
  "account": { "userId": "…", "email": "broker@example.com", "name": "Acme Logistics" },
  "data": {
    "loadId": "…",
    "loadNumber": "LD-2026-042317",
    "reference": "PO-8841",                     // your customerRef, null if none
    "status": "DELIVERED",
    "previousStatus": "AT_DELIVERY",            // status.changed / completed only
    "rateAmount": "1850", "currency": "USD",
    "equipmentType": "VAN",
    "shipperName": "…", "carrierName": "…",
    "stops": [
      { "sequence": 1, "type": "PICKUP", "facilityName": "…", "city": "Dallas", "state": "TX",
        "windowFrom": null, "windowTo": null,
        "arrivedAt": "2026-08-18T16:40:00.000Z", "departedAt": "2026-08-18T17:05:00.000Z" }
    ]
  }
}

Verifying the signature

Every delivery carries two headers:

X-PingPoint-Event:     pingpoint.status.changed
X-PingPoint-Signature: hex(HMAC-SHA256(secret, raw request body))

Compute HMAC-SHA256 over the raw request body with your webhook signing secret from the cabinet and compare it to the header:

const expected = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
const valid = expected === req.headers["x-pingpoint-signature"];

TypeScript SDK

npm install @suverselabs/pingpoint-sdk

const pp = new PingPointAgent({ apiKey: "sup_agent_…" });
const load = await pp.createLoad({ driverPhone, pickups, deliveries });
const pos  = await pp.getPosition(load.loadNumber);

MCP server (for AI agents)

claude mcp add pingpoint --env PINGPOINT_AGENT_KEY=sup_agent_… -- npx -y @suverselabs/pingpoint-mcp

"pingpoint": { "command": "npx", "args": ["-y", "@suverselabs/pingpoint-mcp"],
  "env": { "PINGPOINT_AGENT_KEY": "sup_agent_…" } }

Error codes