Skip to main content

​
Purpose

This page collects representative Partner API request and response examples that match the canonical contract. Use them together with the API reference and OpenAPI contract published in this portal.

​
How to use this page

Read the endpoint map first, then compare each example against the corresponding schema in the API reference before you build or update an integration. The examples below are intentionally realistic enough to support implementation, debugging, and AI-assisted tooling. They show the fields most integrators need to reason about request shape, response shape, identifiers, timestamps, pagination, and webhook payload handling.

​
What these samples help you validate

  • required scopes before you call an endpoint
  • stable identifiers and payload fields you should persist
  • the difference between list, detail, tracking, and webhook flows
  • the minimum shape an agent or integration should expect before automating work

​
Endpoint coverage map

  • GET /v1/loads and GET /v1/loads/{id} are read flows for loads:read
  • POST /v1/loads, POST /v1/loads/upsert, and POST /v1/loads/{id}/status are write flows for loads:write
  • GET /v1/customers and GET /v1/carriers are lookup flows for their respective read scopes
  • GET /v1/tracking/{loadId} reads the latest tracking state for tracking:read
  • POST /v1/webhooks, GET /v1/webhooks, and DELETE /v1/webhooks/{id} are subscription-management flows for webhooks:manage

​
List Loads Response

Representative GET /v1/loads response: 
{
  "data": [
    {
      "id": "load_123",
      "externalId": "tt_456",
      "orderNumber": "ORD-1001",
      "status": "IN_TRANSIT",
      "eligibleForTracking": true,
      "rate": 2450,
      "notes": "Driver checked in at pickup.",
      "customerId": "customer_1",
      "carrierId": "carrier_1",
      "vehicleId": "vehicle_1",
      "customer": {
        "id": "customer_1",
        "customerCode": "CUST-1",
        "customerName": "Acme Foods",
        "status": "active",
        "email": "shipping@acmefoods.example",
        "phone": "+1-415-555-0100"
      },
      "carrier": {
        "id": "carrier_1",
        "carrierName": "Reliable Freight",
        "company": "Reliable Freight LLC",
        "email": "dispatch@reliablefreight.example",
        "phone": "+1-415-555-0110",
        "active": true
      },
      "stops": [
        {
          "id": "stop_1",
          "sequence": 0,
          "kind": "pickup",
          "address": "123 Market St, San Francisco, CA 94105",
          "latitude": 37.7936,
          "longitude": -122.3958,
          "scheduledDate": 1710806400000,
          "scheduledTime": "08:00",
          "scheduledEndTime": "10:00",
          "timezone": "America/Los_Angeles",
          "contactName": "Pickup Dock",
          "email": "pickup@acmefoods.example",
          "phone": "+1-415-555-0101",
          "status": "completed",
          "notes": "Bring reference ORD-1001."
        },
        {
          "id": "stop_2",
          "sequence": 1,
          "kind": "delivery",
          "address": "456 Delivery Ave, Sacramento, CA 95814",
          "latitude": 38.5816,
          "longitude": -121.4944,
          "scheduledDate": 1710810000000,
          "scheduledTime": "14:00",
          "scheduledEndTime": "16:00",
          "timezone": "America/Los_Angeles",
          "contactName": "Receiving Desk",
          "email": "receiving@customer.example",
          "phone": "+1-916-555-0102",
          "status": "scheduled",
          "notes": "Call 30 minutes before arrival."
        }
      ],
      "tracking": {
        "loadId": "load_123",
        "externalId": "tt_456",
        "status": "IN_TRANSIT",
        "eligibleForTracking": true,
        "eligibilityReason": null,
        "routeCount": 2,
        "lastKnownLocation": {
          "latitude": 37.7,
          "longitude": -122.4,
          "recordedAt": 1710808200000,
          "source": "motive"
        }
      },
      "createdAt": 1710802000000,
      "updatedAt": 1710808200000
    }
  ],
  "nextCursor": "eyJ1cGRhdGVkQXQiOjE3MTA4MDgyMDAwMDAsImV4Y2x1ZGVkSWRzIjpbImxvYWRfMTIzIl19",
  "requestId": "req_123"
}

​
Get Load Response

Representative GET /v1/loads/{id} response: 
{
  "data": {
    "id": "load_123",
    "externalId": "tt_456",
    "orderNumber": "ORD-1001",
    "status": "ASSIGNED",
    "eligibleForTracking": true,
    "rate": 2450,
    "notes": "Assigned to primary driver.",
    "customerId": "customer_1",
    "carrierId": "carrier_1",
    "vehicleId": "vehicle_1",
    "customer": {
      "id": "customer_1",
      "customerCode": "CUST-1",
      "customerName": "Acme Foods",
      "status": "active",
      "email": "shipping@acmefoods.example",
      "phone": "+1-415-555-0100"
    },
    "carrier": {
      "id": "carrier_1",
      "carrierName": "Reliable Freight",
      "company": "Reliable Freight LLC",
      "email": "dispatch@reliablefreight.example",
      "phone": "+1-415-555-0110",
      "active": true
    },
    "vehicle": {
      "id": "vehicle_1",
      "unitNumber": "TRK-1",
      "type": "tractor",
      "status": "active"
    },
    "stops": [
      {
        "id": "stop_1",
        "sequence": 0,
        "kind": "pickup",
        "address": "123 Market St, San Francisco, CA 94105",
        "latitude": 37.7936,
        "longitude": -122.3958,
        "scheduledDate": 1710806400000,
        "scheduledTime": "08:00",
        "scheduledEndTime": "10:00",
        "timezone": "America/Los_Angeles",
        "contactName": "Pickup Dock",
        "email": "pickup@acmefoods.example",
        "phone": "+1-415-555-0101",
        "status": "scheduled",
        "notes": "Bring reference ORD-1001."
      }
    ],
    "tracking": {
      "loadId": "load_123",
      "externalId": "tt_456",
      "status": "ASSIGNED",
      "eligibleForTracking": true,
      "eligibilityReason": null,
      "routeCount": 1,
      "lastKnownLocation": null
    },
    "createdAt": 1710802000000,
    "updatedAt": 1710805000000
  },
  "requestId": "req_124"
}

​
Get Tracking Response

Representative GET /v1/tracking/{loadId} response for an ineligible load: 
{
  "data": {
    "loadId": "load_123",
    "externalId": "tt_456",
    "status": "DRAFT",
    "eligibleForTracking": false,
    "eligibilityReason": "load_status_not_trackable",
    "routeCount": 2,
    "lastKnownLocation": null
  },
  "requestId": "req_125"
}

​
Create Webhook Request

Representative POST /v1/webhooks request body: 
{
  "url": "https://partner.example/webhooks/trailflow",
  "eventTypes": ["load.created", "load.status_changed"]
}

​
Create Webhook Response

Representative POST /v1/webhooks response: 
{
  "data": {
    "id": "whsub_123",
    "url": "https://partner.example/webhooks/trailflow",
    "eventTypes": ["load.created", "load.status_changed"],
    "signingSecret": "tfwhsec_example_secret"
  },
  "requestId": "req_126"
}

​
Create Load Request

Representative POST /v1/loads request body: 
{
  "externalId": "tt_456",
  "orderNumber": "ORD-1001",
  "status": "ASSIGNED",
  "customerCode": "CUST-1",
  "carrierName": "Reliable Freight",
  "rate": 2450,
  "notes": "Initial dispatch created from partner TMS."
}

​
Create Load Response

Representative POST /v1/loads response: 
{
  "data": {
    "id": "load_123",
    "externalId": "tt_456",
    "orderNumber": "ORD-1001",
    "status": "ASSIGNED",
    "eligibleForTracking": true,
    "rate": 2450,
    "notes": "Initial dispatch created from partner TMS.",
    "customerId": "customer_1",
    "carrierId": "carrier_1",
    "vehicleId": "vehicle_1",
    "createdAt": 1710802000000,
    "updatedAt": 1710802000000
  },
  "requestId": "req_127"
}

​
Upsert Load Request

Representative POST /v1/loads/upsert request body: 
{
  "externalId": "tt_456",
  "orderNumber": "ORD-1001",
  "status": "IN_TRANSIT",
  "carrierName": "Reliable Freight"
}

​
Upsert Load Response

Representative POST /v1/loads/upsert response: 
{
  "data": {
    "id": "load_123",
    "externalId": "tt_456",
    "orderNumber": "ORD-1001",
    "status": "IN_TRANSIT",
    "eligibleForTracking": true,
    "rate": 2450,
    "notes": "Partner upsert refreshed the latest operational state.",
    "customerId": "customer_1",
    "carrierId": "carrier_1",
    "vehicleId": "vehicle_1",
    "createdAt": 1710802000000,
    "updatedAt": 1710808200000
  },
  "requestId": "req_128"
}

​
Update Load Status Request

Representative POST /v1/loads/{id}/status request body: 
{
  "status": "DELIVERED"
}

​
Update Load Status Response

Representative POST /v1/loads/{id}/status response: 
{
  "data": {
    "id": "load_123",
    "externalId": "tt_456",
    "orderNumber": "ORD-1001",
    "status": "DELIVERED",
    "eligibleForTracking": false,
    "rate": 2450,
    "notes": "Marked delivered by partner dispatch.",
    "customerId": "customer_1",
    "carrierId": "carrier_1",
    "vehicleId": "vehicle_1",
    "createdAt": 1710802000000,
    "updatedAt": 1710810000000
  },
  "previousStatus": "IN_TRANSIT",
  "requestId": "req_129"
}

​
List Customers Response

Representative GET /v1/customers response: 
{
  "data": [
    {
      "id": "customer_1",
      "customerCode": "CUST-1",
      "customerName": "Acme Foods",
      "status": "active",
      "email": "shipping@acmefoods.example",
      "phone": "+1-415-555-0100",
      "updatedAt": 1710805000000
    }
  ],
  "requestId": "req_130"
}

​
List Carriers Response

Representative GET /v1/carriers response: 
{
  "data": [
    {
      "id": "carrier_1",
      "carrierName": "Reliable Freight",
      "company": "Reliable Freight LLC",
      "email": "dispatch@reliablefreight.example",
      "phone": "+1-415-555-0110",
      "active": true,
      "updatedAt": 1710805000000
    }
  ],
  "requestId": "req_131"
}

​
List Webhooks Response

Representative GET /v1/webhooks response: 
{
  "data": [
    {
      "id": "whsub_123",
      "url": "https://partner.example/webhooks/trailflow",
      "eventTypes": ["load.created", "load.status_changed"],
      "status": "active",
      "createdAt": 1710802000000
    }
  ],
  "requestId": "req_132"
}

​
Delete Webhook Response

Representative DELETE /v1/webhooks/{id} response: 
{
  "deleted": true,
  "requestId": "req_133"
}

​
Example Sync Request

Example incremental polling request: 
curl --request GET \
  --url 'https://api.trailflow.ai/v1/loads?eligibleOnly=true&updatedAfter=1710806400000&statuses=ASSIGNED,IN_TRANSIT&include=tracking,customer,carrier,stops&limit=100' \
  --header 'Authorization: Bearer <api key>'

​
Example Error Response

Representative error envelope: 
{
  "error": {
    "code": "idempotency_conflict",
    "message": "Idempotency-Key was reused with a different payload"
  },
  "requestId": "req_999"
}

​
Notes

  • These examples are representative and should be used together with the endpoint schemas in the API reference.
  • The API reference remains the source of truth for field requirements, enum values, and response shapes.