Examples And Payloads - Trailflow Partner API

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.

Documentation Index

​Purpose

​How to use this page

​What these samples help you validate

​Endpoint coverage map

​List Loads Response

​Get Load Response

​Get Tracking Response

​Create Webhook Request

​Create Webhook Response

​Create Load Request

​Create Load Response

​Upsert Load Request

​Upsert Load Response

​Update Load Status Request

​Update Load Status Response

​List Customers Response

​List Carriers Response

​List Webhooks Response

​Delete Webhook Response

​Example Sync Request

​Example Error Response

​Notes