Skip to main content

​
Purpose

GET /v1/loads is the canonical pull route for partner load synchronization. The route is designed for incremental polling, deterministic paging, and shipment-scoped tracking visibility. Recommended flow:
  1. Poll GET /v1/loads with eligibleOnly=true.
  2. Use updatedAfter for incremental sync windows.
  3. Use statuses=ASSIGNED,LOADED,IN_TRANSIT when only actively trackable freight is needed.
  4. Use include=tracking,customer,carrier,stops only when those related objects are required in the same response.
  5. If nextCursor is present, continue paging with cursor=<nextCursor>.
  6. Stop paging when nextCursor is null.
Example query: 
GET /v1/loads?eligibleOnly=true&updatedAfter=1710806400000&statuses=ASSIGNED,IN_TRANSIT&include=tracking,customer,carrier,stops&limit=100

​
Query Parameters

Supported query parameters:
  • updatedAfter Returns only loads updated on or after the provided Unix timestamp in milliseconds.
  • statuses Comma-separated list of load statuses to include.
  • externalId Returns the load mapped to the partner-facing external identifier.
  • include Comma-separated related objects to embed: customer, carrier, vehicle, stops, tracking.
  • eligibleOnly When true, returns only loads currently eligible for shipment-scoped tracking visibility.
  • cursor Opaque cursor returned by the previous page.
  • limit Page size from 1 to 100.

​
Pagination Contract

GET /v1/loads returns:
  • data
  • nextCursor
  • requestId
Example: 
{
  "data": [
    {
      "id": "load_123",
      "externalId": "tt_456",
      "orderNumber": "ORD-1001",
      "status": "IN_TRANSIT",
      "eligibleForTracking": true
    }
  ],
  "nextCursor": "eyJ1cGRhdGVkQXQiOjE3MTA4MDgyMDAwMDAsImV4Y2x1ZGVkSWRzIjpbImxvYWRfMTIzIl19",
  "requestId": "req_123"
}
Treat nextCursor as opaque. Do not parse, modify, or persist assumptions about its internal format.

​
Identifier Behavior

Trailflow uses two identifier types on the load surface:
  • id Canonical Trailflow load identifier
  • externalId Partner-facing mapped identifier when one exists
GET /v1/loads/{id} accepts either:
  • the canonical Trailflow id
  • the mapped partner externalId
GET /v1/tracking/{loadId} follows the same identifier behavior.

​
Tracking Eligibility

eligibleForTracking appears on both load and tracking responses. Trackable statuses:
  • LOADED
  • ASSIGNED
  • IN_TRANSIT
When a load is not eligible for tracking, the tracking response returns:
  • eligibleForTracking: false
  • eligibilityReason: "load_status_not_trackable"

​
Include Expansion

Use include only when the integration needs related records inline. Supported values:
  • customer
  • carrier
  • vehicle
  • stops
  • tracking
Including related objects can reduce round-trips, but it also increases response size. For continuous polling, start with the smallest shape that satisfies the integration. For an initial backfill:
  1. pick the approved start timestamp
  2. request a bounded page size such as 100
  3. keep paging with nextCursor
  4. once paging finishes, store the newest observed updatedAt
  5. switch to incremental sync using updatedAfter
For steady-state polling, the simplest safe default is: 
curl --request GET \
  --url 'https://api.trailflow.ai/v1/loads?eligibleOnly=true&updatedAfter=<unix-ms>&limit=100' \
  --header 'Authorization: Bearer <api key>'

​
Failure Handling

If a partner reports missed or duplicate rows, verify:
  • the last successful updatedAfter value
  • whether paging continued until nextCursor became null
  • whether statuses or eligibleOnly filters excluded the expected rows
  • whether the partner is mixing canonical id and externalId incorrectly
  • the affected requestId values