Skip to main content

​
Summary

Trailflow’s Partner API is the partner-facing HTTP contract for approved external companies that need operational access to loads, tracking visibility, reference data, and webhook events. This portal is intentionally partner-facing:
  • it explains how approved partners authenticate and integrate
  • it describes how test and live access work
  • it publishes the canonical OpenAPI contract and examples
  • it avoids internal runbooks, staff-only operations, and pilot-only workflow details

​
Product Model

​
Who this API is for

  • external partner systems that need server-to-server access to Trailflow data and workflows
  • approved integration teams onboarding with Trailflow support

​
Who this API is not for

  • individual end users
  • unapproved customer admins issuing credentials without Trailflow approval
  • public self-serve marketplace developers

​
Canonical Design

The public v1 contract is Trailflow-first and partner-agnostic. Canonical resources:
  • loads
  • load status updates
  • customers lookup
  • carriers lookup
  • tracking visibility state
  • webhook subscriptions
Partner-specific payload shapes remain in adapter modules rather than defining the core contract.

​
Access Model

Trailflow manages partner access centrally.
  • each customer organization must be explicitly approved for Partner API access
  • new integrations should start with test keys
  • once test access is enabled, approved partner admins may self-serve additional test keys from the authenticated partner portal
  • Trailflow may also provide the first test key during onboarding when that is easier for the integration team
  • live keys are issued only for approved production use
  • live access and live credentials remain Trailflow-managed
Today Trailflow uses one production base URL with scoped credentials rather than a separate hosted sandbox. Test-mode keys are the default path for UAT and partner validation.

​
Route Surface

Current public routes:
  • GET /health/api
  • GET /v1/loads
  • POST /v1/loads
  • POST /v1/loads/upsert
  • GET /v1/loads/{id}
  • POST /v1/loads/{id}/status
  • GET /v1/customers
  • GET /v1/carriers
  • GET /v1/tracking/{loadId}
  • POST /v1/webhooks
  • GET /v1/webhooks
  • DELETE /v1/webhooks/{id}

​
Auth And Limits

Partner access stages:
  • not enabled
  • test access enabled
  • live access enabled
  • disabled
API key modes:
  • test
  • live
Allowed scopes:
  • loads:read
  • loads:write
  • customers:read
  • carriers:read
  • tracking:read
  • webhooks:manage
Server-side issuance validation rejects unknown scopes and rejects rate limits outside the 1 to 600 requests-per-minute range.

​
Supporting Docs

Concrete examples live under the examples and payloads guide.