Trace REST API

Read your assets, shipments, carriers, alerts and devices from your own systems: an ERP, a TMS, a data warehouse or a customer portal. The API is read-only and answers in JSON.

Base URL

https://trace.verticalware.io/api/v1

Times are ISO 8601 in UTC. Tracker times (lastReceivedAt, receivedAt) are when Trace received the report.

Authentication

Create an API key in Trace under Settings → API Keys (account admins only). The key is shown once: store it like a password. Send it with every request in the Authorization header.

A key belongs to your account and reads what your account's logins see. A customer key reads the customer's records. An End-User key reads only that End-User's records. Revoke a key in Settings → API Keys, and anything using it stops working right away.

Header

Authorization: Bearer trace_live_xxxxxxxxxxxxxxxxxxxx

Pagination

Lists take page (from 1) and limit (up to 100, default 50). The records are in data. Keep asking for the next page while hasMore is true.

Location history uses a cursor instead: pass the next value back as after until it is null.

List response

{
  "data": [
    "…"
  ],
  "pagination": {
    "page": 2,
    "limit": 50,
    "total": 137,
    "hasMore": true
  }
}

Errors

Errors use HTTP status codes, with a message in detail.

400: A parameter is invalid, e.g. a time that isn't ISO 8601.
401: No API key, or the key is invalid or revoked.
403: The account is suspended, or the app (Shipments, Alerts) isn't enabled for it.
404: No such record in your account.
422: A parameter has the wrong type, e.g. limit=abc.
429: Too many requests. Wait for the seconds in the Retry-After header.

Response · 404

{
  "detail": "Asset not found"
}

Rate limits

Each key can make 120 requests a minute. Every response says how many are left. Over the limit, the API answers 429 with a Retry-After header in seconds.

Response headers

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117

Account

The account the API key belongs to: a customer, or one of a customer's End-Users.

Get the account

GET/api/v1/account

Who the key belongs to, which apps the account has, and the key's rate limit. Useful to test a key.

Request

curl "https://trace.verticalware.io/api/v1/account" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response · 200

{
  "type": "customer",
  "customerId": "66f0a1b2c3d4e5f607182930",
  "customerName": "Universal Food Trailers",
  "endUserId": null,
  "endUserName": null,
  "apiKey": {
    "id": "671c0000a1b2c3d4e5f60b00",
    "name": "ERP integration",
    "last4": "x9Qa"
  },
  "apps": [
    "operations",
    "assets",
    "shipments",
    "reporting",
    "alerts"
  ],
  "rateLimit": {
    "limit": 120,
    "window": "1 minute"
  }
}

Assets

Trailers, containers, equipment and anything else you track. Each asset has a primary tracker (deviceId) and can have a backup tracker.

List assets

GET/api/v1/assets

All assets in the account, by asset number.

Query parameters

searchstring: Only assets whose name contains this text.
deviceIdstring: Only the asset with this tracker.
typestring: Only assets of this type, e.g. "20 Ft. Food Trailer".
pageinteger: Page number, starting at 1. Default 1.
limitinteger: Records per page, 1 to 100. Default 50.

Request

curl "https://trace.verticalware.io/api/v1/assets" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response · 200

{
  "data": [
    {
      "id": "6712f0c4a1b2c3d4e5f60718",
      "assetNumber": 12,
      "name": "Food Trailer 12",
      "type": "16 Ft. Food Trailer",
      "status": "Active",
      "assetStatus": "Rented",
      "serialNumber": "1UFT16A12P0001234",
      "owner": null,
      "condition": "Good",
      "tags": [
        "texas"
      ],
      "deviceId": "359746163544708",
      "backupDeviceId": null,
      "siteId": "66f1a2b3c4d5e6f708192a3b",
      "endUserId": null,
      "location": {
        "latitude": 29.7604,
        "longitude": -95.3698,
        "address": "1200 Main St, Houston, TX 77002",
        "speed": 0,
        "heading": 180
      },
      "batteryLevel": 87,
      "temperature": 24.5,
      "lastReceivedAt": "2026-10-25T14:02:11+00:00",
      "customFields": {
        "VIN": "1UFT16A12P0001234"
      },
      "notes": null,
      "createdAt": "2026-10-07T16:20:00+00:00",
      "updatedAt": "2026-10-25T14:02:11+00:00"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 1,
    "hasMore": false
  }
}

Retrieve an asset

GET/api/v1/assets/{id}

One asset by its id.

Path parameters

idstringrequired: The asset's id.

Request

curl "https://trace.verticalware.io/api/v1/assets/ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response · 200

{
  "id": "6712f0c4a1b2c3d4e5f60718",
  "assetNumber": 12,
  "name": "Food Trailer 12",
  "type": "16 Ft. Food Trailer",
  "status": "Active",
  "assetStatus": "Rented",
  "serialNumber": "1UFT16A12P0001234",
  "owner": null,
  "condition": "Good",
  "tags": [
    "texas"
  ],
  "deviceId": "359746163544708",
  "backupDeviceId": null,
  "siteId": "66f1a2b3c4d5e6f708192a3b",
  "endUserId": null,
  "location": {
    "latitude": 29.7604,
    "longitude": -95.3698,
    "address": "1200 Main St, Houston, TX 77002",
    "speed": 0,
    "heading": 180
  },
  "batteryLevel": 87,
  "temperature": 24.5,
  "lastReceivedAt": "2026-10-25T14:02:11+00:00",
  "customFields": {
    "VIN": "1UFT16A12P0001234"
  },
  "notes": null,
  "createdAt": "2026-10-07T16:20:00+00:00",
  "updatedAt": "2026-10-25T14:02:11+00:00"
}

Asset location history

GET/api/v1/assets/{id}/locations

Every position the asset's trackers reported while on the asset, oldest first. If there are more than limit, the response has a next value: pass it as after to get the next positions.

Path parameters

idstringrequired: The asset's id.

Query parameters

fromdatetime: Only positions at or after this time (ISO 8601).
todatetime: Only positions at or before this time (ISO 8601).
limitinteger: Positions per call, 1 to 5000. Default 1000.
afterstring: The next value from the previous call, for the following positions.

Request

curl "https://trace.verticalware.io/api/v1/assets/ID/locations" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response · 200

{
  "data": [
    {
      "latitude": 29.7411,
      "longitude": -95.3312,
      "speed": 0,
      "heading": 0,
      "altitude": 14,
      "deviceId": "359746163544708",
      "receivedAt": "2026-10-25T13:30:05+00:00"
    },
    {
      "latitude": 29.7425,
      "longitude": -95.3401,
      "speed": 38,
      "heading": 270,
      "altitude": 15,
      "deviceId": "359746163544708",
      "receivedAt": "2026-10-25T13:45:07+00:00"
    }
  ],
  "next": null
}

Shipments

Loads moving from one place to another, in one or more legs. Needs the Shipments app. An End-User's key sees only the shipments where it is the customer.

List shipments

GET/api/v1/shipments

All shipments, newest first. delayed is true when an open shipment is past its arrival time.

Query parameters

statusstring: Planned, In Transit, Delivered or Cancelled.
searchstring: Only shipments whose Shipment Number or Reference contains this text.
pageinteger: Page number, starting at 1. Default 1.
limitinteger: Records per page, 1 to 100. Default 50.

Request

curl "https://trace.verticalware.io/api/v1/shipments" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response · 200

{
  "data": [
    {
      "id": "671b9e0fa1b2c3d4e5f60999",
      "shipmentNumber": "PO-48213",
      "traceId": "SHP-000042",
      "reference": "BOL 99812",
      "status": "In Transit",
      "delayed": false,
      "endUserId": "66fe0a1b2c3d4e5f60718293",
      "endUserName": "AM Home Delivery",
      "travelMode": "Land",
      "carrierId": "66fa1b2c3d4e5f6071829304",
      "carrierName": "Lone Star Freight",
      "currentCarrierName": "Lone Star Freight",
      "shipFrom": {
        "siteId": "66f1a2b3c4d5e6f708192a3b",
        "name": "Houston Yard",
        "address": "500 Industrial Blvd, Houston, TX",
        "latitude": 29.74,
        "longitude": -95.33
      },
      "shipTo": {
        "siteId": "66f1a2b3c4d5e6f708192a3b",
        "name": "Dallas DC",
        "address": "2200 Commerce St, Dallas, TX",
        "latitude": 32.78,
        "longitude": -96.79
      },
      "departureAt": "2026-10-25T12:00:00+00:00",
      "arrivalAt": "2026-10-25T18:30:00+00:00",
      "inTransitAt": "2026-10-25T12:14:03+00:00",
      "deliveredAt": null,
      "deliveredAuto": false,
      "routeApproved": true,
      "cancelReason": null,
      "cancelledAt": null,
      "deviceId": "865413050123456",
      "location": {
        "latitude": 30.6,
        "longitude": -96.1,
        "lastReceivedAt": "2026-10-25T14:01:40+00:00"
      },
      "legs": [
        {
          "id": "seg_1",
          "kind": "leg",
          "status": "In Progress",
          "from": {
            "siteId": "66f1a2b3c4d5e6f708192a3b",
            "name": "Houston Yard",
            "address": "500 Industrial Blvd, Houston, TX",
            "latitude": 29.74,
            "longitude": -95.33
          },
          "to": {
            "siteId": "66f1a2b3c4d5e6f708192a3b",
            "name": "Dallas DC",
            "address": "2200 Commerce St, Dallas, TX",
            "latitude": 32.78,
            "longitude": -96.79
          },
          "travelMode": "Land",
          "carrierId": "66fa1b2c3d4e5f6071829304",
          "carrierName": "Lone Star Freight",
          "bol": "BOL 99812",
          "departureAt": "2026-10-25T12:00:00+00:00",
          "arrivalAt": "2026-10-25T18:30:00+00:00",
          "startedAt": "2026-10-25T12:14:03+00:00",
          "arrivedAt": null,
          "departedAt": null,
          "completedAt": null,
          "notes": null
        }
      ],
      "notes": null,
      "createdAt": "2026-10-24T20:11:00+00:00",
      "updatedAt": "2026-10-25T12:14:03+00:00"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 1,
    "hasMore": false
  }
}

Retrieve a shipment

GET/api/v1/shipments/{id}

One shipment with its legs and stops, in order. Each leg and stop is Planned, In Progress or Completed.

Path parameters

idstringrequired: The shipment's id.

Request

curl "https://trace.verticalware.io/api/v1/shipments/ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response · 200

{
  "id": "671b9e0fa1b2c3d4e5f60999",
  "shipmentNumber": "PO-48213",
  "traceId": "SHP-000042",
  "reference": "BOL 99812",
  "status": "In Transit",
  "delayed": false,
  "endUserId": "66fe0a1b2c3d4e5f60718293",
  "endUserName": "AM Home Delivery",
  "travelMode": "Land",
  "carrierId": "66fa1b2c3d4e5f6071829304",
  "carrierName": "Lone Star Freight",
  "currentCarrierName": "Lone Star Freight",
  "shipFrom": {
    "siteId": "66f1a2b3c4d5e6f708192a3b",
    "name": "Houston Yard",
    "address": "500 Industrial Blvd, Houston, TX",
    "latitude": 29.74,
    "longitude": -95.33
  },
  "shipTo": {
    "siteId": "66f1a2b3c4d5e6f708192a3b",
    "name": "Dallas DC",
    "address": "2200 Commerce St, Dallas, TX",
    "latitude": 32.78,
    "longitude": -96.79
  },
  "departureAt": "2026-10-25T12:00:00+00:00",
  "arrivalAt": "2026-10-25T18:30:00+00:00",
  "inTransitAt": "2026-10-25T12:14:03+00:00",
  "deliveredAt": null,
  "deliveredAuto": false,
  "routeApproved": true,
  "cancelReason": null,
  "cancelledAt": null,
  "deviceId": "865413050123456",
  "location": {
    "latitude": 30.6,
    "longitude": -96.1,
    "lastReceivedAt": "2026-10-25T14:01:40+00:00"
  },
  "legs": [
    {
      "id": "seg_1",
      "kind": "leg",
      "status": "In Progress",
      "from": {
        "siteId": "66f1a2b3c4d5e6f708192a3b",
        "name": "Houston Yard",
        "address": "500 Industrial Blvd, Houston, TX",
        "latitude": 29.74,
        "longitude": -95.33
      },
      "to": {
        "siteId": "66f1a2b3c4d5e6f708192a3b",
        "name": "Dallas DC",
        "address": "2200 Commerce St, Dallas, TX",
        "latitude": 32.78,
        "longitude": -96.79
      },
      "travelMode": "Land",
      "carrierId": "66fa1b2c3d4e5f6071829304",
      "carrierName": "Lone Star Freight",
      "bol": "BOL 99812",
      "departureAt": "2026-10-25T12:00:00+00:00",
      "arrivalAt": "2026-10-25T18:30:00+00:00",
      "startedAt": "2026-10-25T12:14:03+00:00",
      "arrivedAt": null,
      "departedAt": null,
      "completedAt": null,
      "notes": null
    }
  ],
  "notes": null,
  "createdAt": "2026-10-24T20:11:00+00:00",
  "updatedAt": "2026-10-25T12:14:03+00:00"
}

Shipment location history

GET/api/v1/shipments/{id}/locations

The positions recorded for the shipment, oldest first. Works like asset location history.

Path parameters

idstringrequired: The shipment's id.

Query parameters

fromdatetime: Only positions at or after this time (ISO 8601).
todatetime: Only positions at or before this time (ISO 8601).
limitinteger: Positions per call, 1 to 5000. Default 1000.
afterstring: The next value from the previous call, for the following positions.

Request

curl "https://trace.verticalware.io/api/v1/shipments/ID/locations" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response · 200

{
  "data": [
    {
      "latitude": 29.7411,
      "longitude": -95.3312,
      "speed": 0,
      "heading": 0,
      "altitude": 14,
      "deviceId": "359746163544708",
      "receivedAt": "2026-10-25T13:30:05+00:00"
    },
    {
      "latitude": 29.7425,
      "longitude": -95.3401,
      "speed": 38,
      "heading": 270,
      "altitude": 15,
      "deviceId": "359746163544708",
      "receivedAt": "2026-10-25T13:45:07+00:00"
    }
  ],
  "next": null
}

Carriers

The trucking companies, railroads and forwarders the account ships with. Needs the Shipments app. An End-User's key sees the carriers that serve it.

List carriers

GET/api/v1/carriers

All carriers, by name.

Query parameters

searchstring: Only carriers whose name contains this text.
pageinteger: Page number, starting at 1. Default 1.
limitinteger: Records per page, 1 to 100. Default 50.

Request

curl "https://trace.verticalware.io/api/v1/carriers" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response · 200

{
  "data": [
    {
      "id": "66fa1b2c3d4e5f6071829304",
      "name": "Lone Star Freight",
      "status": "Active",
      "scac": "LSFT",
      "dotNumber": "1234567",
      "mcNumber": "MC-765432",
      "contactName": "Dispatch",
      "phone": "+1 713 555 0100",
      "email": "dispatch@example.com",
      "truckLicense": null,
      "trailerLicense": null,
      "brokerName": null,
      "brokerPhone": null,
      "notes": null,
      "createdAt": "2026-09-30T15:00:00+00:00",
      "updatedAt": "2026-10-02T09:12:00+00:00"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 1,
    "hasMore": false
  }
}

Retrieve a carrier

GET/api/v1/carriers/{id}

One carrier by its id.

Path parameters

idstringrequired: The carrier's id.

Request

curl "https://trace.verticalware.io/api/v1/carriers/ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response · 200

{
  "id": "66fa1b2c3d4e5f6071829304",
  "name": "Lone Star Freight",
  "status": "Active",
  "scac": "LSFT",
  "dotNumber": "1234567",
  "mcNumber": "MC-765432",
  "contactName": "Dispatch",
  "phone": "+1 713 555 0100",
  "email": "dispatch@example.com",
  "truckLicense": null,
  "trailerLicense": null,
  "brokerName": null,
  "brokerPhone": null,
  "notes": null,
  "createdAt": "2026-09-30T15:00:00+00:00",
  "updatedAt": "2026-10-02T09:12:00+00:00"
}

Alerts

Alerts raised by trackers and alert rules: geofences, temperature, battery, tampering and more. Needs the Alerts app. subject is what the alert is about: a shipment, an asset or a device.

List alerts

GET/api/v1/alerts

Alerts, newest first. To collect new alerts, poll with since set to the time of your last call.

Query parameters

acknowledgedboolean: true for acknowledged alerts only, false for open ones only.
severitystring: info, warning or critical.
sincedatetime: Only alerts raised at or after this time (ISO 8601).
untildatetime: Only alerts raised at or before this time (ISO 8601).
pageinteger: Page number, starting at 1. Default 1.
limitinteger: Records per page, 1 to 100. Default 50.

Request

curl "https://trace.verticalware.io/api/v1/alerts" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response · 200

{
  "data": [
    {
      "id": "671ba01ca1b2c3d4e5f60aaa",
      "type": "Geofence exit",
      "severity": "warning",
      "message": "Food Trailer 12 left Houston Yard",
      "ruleName": "Left the yard",
      "subject": {
        "kind": "asset",
        "id": "6712f0c4a1b2c3d4e5f60718",
        "label": "Food Trailer 12"
      },
      "deviceId": "359746163544708",
      "location": {
        "latitude": 29.741,
        "longitude": -95.331,
        "address": "500 Industrial Blvd, Houston, TX"
      },
      "triggeredAt": "2026-10-25T13:40:22+00:00",
      "lastReportedAt": "2026-10-25T13:40:22+00:00",
      "repeatCount": 1,
      "active": null,
      "acknowledged": false,
      "acknowledgedAt": null,
      "acknowledgedBy": null
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 1,
    "hasMore": false
  }
}

Retrieve an alert

GET/api/v1/alerts/{id}

One alert by its id.

Path parameters

idstringrequired: The alert's id.

Request

curl "https://trace.verticalware.io/api/v1/alerts/ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response · 200

{
  "id": "671ba01ca1b2c3d4e5f60aaa",
  "type": "Geofence exit",
  "severity": "warning",
  "message": "Food Trailer 12 left Houston Yard",
  "ruleName": "Left the yard",
  "subject": {
    "kind": "asset",
    "id": "6712f0c4a1b2c3d4e5f60718",
    "label": "Food Trailer 12"
  },
  "deviceId": "359746163544708",
  "location": {
    "latitude": 29.741,
    "longitude": -95.331,
    "address": "500 Industrial Blvd, Houston, TX"
  },
  "triggeredAt": "2026-10-25T13:40:22+00:00",
  "lastReportedAt": "2026-10-25T13:40:22+00:00",
  "repeatCount": 1,
  "active": null,
  "acknowledged": false,
  "acknowledgedAt": null,
  "acknowledgedBy": null
}

Devices

The trackers in the account. assetId is the asset the device is on.

List devices

GET/api/v1/devices

All devices, by Device ID.

Query parameters

searchstring: Only devices whose Device ID, Friendly Name or IMEI contains this text.
pageinteger: Page number, starting at 1. Default 1.
limitinteger: Records per page, 1 to 100. Default 50.

Request

curl "https://trace.verticalware.io/api/v1/devices" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response · 200

{
  "data": [
    {
      "id": "6712ef00a1b2c3d4e5f60700",
      "deviceId": "359746163544708",
      "friendlyName": "Trailer 12 tracker",
      "manufacturer": "Digital Matter",
      "deviceType": "GPS Tracker",
      "model": "Yabby3",
      "profile": "yabby3",
      "firmware": "1.4",
      "status": "Active",
      "imei": "359746163544708",
      "iccid": "8988228066601234567",
      "tags": [],
      "assetId": "6712f0c4a1b2c3d4e5f60718",
      "endUserId": null,
      "batteryLevel": 87,
      "temperature": 24.5,
      "location": {
        "latitude": 29.7604,
        "longitude": -95.3698,
        "address": "1200 Main St, Houston, TX 77002"
      },
      "lastReceivedAt": "2026-10-25T14:02:11+00:00",
      "createdAt": "2026-10-07T16:18:00+00:00",
      "updatedAt": "2026-10-25T14:02:11+00:00"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 1,
    "hasMore": false
  }
}

Retrieve a device

GET/api/v1/devices/{id}

One device, by its id or by its Device ID (IMEI or serial number).

Path parameters

idstringrequired: The device's id, or its Device ID.

Request

curl "https://trace.verticalware.io/api/v1/devices/ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response · 200

{
  "id": "6712ef00a1b2c3d4e5f60700",
  "deviceId": "359746163544708",
  "friendlyName": "Trailer 12 tracker",
  "manufacturer": "Digital Matter",
  "deviceType": "GPS Tracker",
  "model": "Yabby3",
  "profile": "yabby3",
  "firmware": "1.4",
  "status": "Active",
  "imei": "359746163544708",
  "iccid": "8988228066601234567",
  "tags": [],
  "assetId": "6712f0c4a1b2c3d4e5f60718",
  "endUserId": null,
  "batteryLevel": 87,
  "temperature": 24.5,
  "location": {
    "latitude": 29.7604,
    "longitude": -95.3698,
    "address": "1200 Main St, Houston, TX 77002"
  },
  "lastReceivedAt": "2026-10-25T14:02:11+00:00",
  "createdAt": "2026-10-07T16:18:00+00:00",
  "updatedAt": "2026-10-25T14:02:11+00:00"
}

Device location history

GET/api/v1/devices/{id}/locations

Every position the device reported, oldest first. Works like asset location history.

Path parameters

idstringrequired: The device's id, or its Device ID.

Query parameters

fromdatetime: Only positions at or after this time (ISO 8601).
todatetime: Only positions at or before this time (ISO 8601).
limitinteger: Positions per call, 1 to 5000. Default 1000.
afterstring: The next value from the previous call, for the following positions.

Request

curl "https://trace.verticalware.io/api/v1/devices/ID/locations" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response · 200

{
  "data": [
    {
      "latitude": 29.7411,
      "longitude": -95.3312,
      "speed": 0,
      "heading": 0,
      "altitude": 14,
      "deviceId": "359746163544708",
      "receivedAt": "2026-10-25T13:30:05+00:00"
    },
    {
      "latitude": 29.7425,
      "longitude": -95.3401,
      "speed": 38,
      "heading": 270,
      "altitude": 15,
      "deviceId": "359746163544708",
      "receivedAt": "2026-10-25T13:45:07+00:00"
    }
  ],
  "next": null
}