TrackFlo
Start Here

Getting Started with the Integration API

Updated today

You need an API key, your tenant slug and a status mapping, all issued by TrackFlo at onboarding. Then post a carrier, a load, its legs, its stops and its updates, in that order.

What you need

  1. An API key and your tenant slug (company_permalink), both issued by TrackFlo at onboarding. The key is shown once; store it in a secret store.

  2. A status mapping agreed with TrackFlo: which of your TMS statuses mean planned, in transit, delivered and so on. You send statuses exactly as your TMS names them; TrackFlo maps them.

  3. The base URL: https://integration-api.trackflo.tech

The five endpoints

Order

Endpoint

One row per…

1

POST /api/v1/carriers/upsert

carrier

2

POST /api/v1/loads/upsert

order / BOL

3

POST /api/v1/loadlegs/upsert

route / movement on a load

4

POST /api/v1/stops/upsert

pickup or delivery on a leg

5

POST /api/v1/loadupdates/upsert

check call, GPS ping or status remark

Post them in that order the first time so every reference already exists. After that, post whatever changed.

Every object is identified by a native_system_*_permalink you build as <your id>-<company_permalink>. For tenant acme, order 1083452 becomes 1083452-acme. Posting the same permalink again updates the record. Load updates are the exception: they are append-only, and a repeated permalink is answered with status: duplicate and left unchanged.

Your first request

curl -X POST https://integration-api.trackflo.tech/api/v1/loads/upsert \
  -H "X-API-Key: $TRACKFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Trackflo-Ingest-Source: pull" \
  -d '{
    "company_permalink": "acme",
    "native_system_load_permalink": "1083452-acme",
    "native_system_load_id": "1083452",
    "native_system_load_status": "Available",
    "customer_name": "Example Foods",
    "origin_stop_id": "5001",
    "origin_stop_id_permalink": "5001-acme",
    "destination_stop_id": "5002",
    "destination_stop_id_permalink": "5002-acme"
  }'

A successful call answers 200:

{ "status": "processed", "message": "Load processed", "permalink": "1083452-acme" }

Two inputs worth sending every time

  • Trackflo-Ingest-Source header: pull for scheduled polling, webhook for event-driven pushes. TrackFlo monitors the health of each path separately, so a stalled poller is noticed even while webhooks keep flowing.

  • sync_run_time query parameter (loads, legs, stops): the ISO-8601 UTC time your sync run started. If the record changed in TrackFlo after that moment (a user edit, a fresher webhook), the upsert is answered status: skipped instead of overwriting newer data. Send it on every batch upsert.

Reading the reference

Every field in the API reference starts its description with its importance (x-trackflo-importance in the spec):

  • required: the API rejects the request without it.

  • recommended: a TrackFlo feature depends on it (the description says which).

  • optional: stored and shown, nothing depends on it.

Field descriptions are being filled in; if one is missing, the field name follows the TrackFlo data model in Data model.

Was this helpful?
Was this helpful?