TrackFlo shows a route while it is Active in Mastery and covered by a carrier. A route that isn't covered yet or is on Hold reads Inactive, and Complete or Cancelled routes leave the board. A route that hasn't changed since the connection went live appears the next time Mastery publishes a change to it.
Mastery (MasterMind) Integration Guide
Updated last week
TrackFlo connects to Mastery (MasterMind) in both directions. It reads your loads from Mastery's event stream (the Kafka egress topics) as changes happen, re-reads active routes from the Mastery REST API every hour, and writes your team's tracking work back to the same route through that API. TrackFlo opens every connection, so there is no webhook for Mastery to call.
What TrackFlo reads
Each Mastery route becomes one load in TrackFlo, and the route number is its load number.
Orders, as they change: route status, stops and appointments, facility names and notes, customer, mode, equipment, commodities, temperature range, order and stop reference numbers, and the reps on the order.
Carrier coverage, as it changes: the carrier on the route (including a bounced carrier), the carrier reps, the empty location and time, and the load's carrier contact (the rate confirmation's recipient first, then the carrier's Dispatch contact, then its primary tracking contact; your own team's addresses are skipped).
Driver and equipment assignments, as they change: up to two drivers with phone numbers, tractor, trailer, tracking method and whether tracking is enabled.
Stop arrivals and departures, as they're recorded.
Trace notes, as they're posted, including location and ETA updates from MacroPoint, FourKites or Samsara. Each one lands on the load's TrackFlo timeline with its source.
Active routes, every hour, read back from the API (carrier, drivers, equipment, stops, appointments, arrivals and departures), so a stop event or driver change the stream missed is caught up.
Carriers, every night: name, DOT and MC numbers, tracking and after-hours contacts, and tracking instructions.
Customer, facility and employee (rep) details are read from the API the first time a load references them, then kept for reuse (see Things to know for how long).
What TrackFlo writes
Trace notes on the route, for every check call or update your team logs in TrackFlo, including AI and automated updates. Each carries the update type the tracker picked as its action term (
Check Callwhen none applies), the location when there is one, and the ETA in the note's ETA field. The note starts with the tracker's name and ends in(via TrackFlo).Stop arrivals and departures, as the stop's driver arrival and driver departure, with a late reason on an arrival when the tracker picks one. Clearing a time in TrackFlo clears it in Mastery.
Driver assignment: driver and second driver with phone numbers, tractor, trailer, ELD vehicle ID, tracking method, the tracking checkbox, and the empty (ready) location and time.
Dispatch: dispatching a load in TrackFlo marks the route dispatched in Mastery and adds a
Plannedtrace note with the dispatch comment and ETA.The carrier's tracking link, in the route's
TrackingLinkreference, whenever a tracker adds, changes or clears it in TrackFlo.A link to the load's public TrackFlo tracking page, once per route: as a
TrackFloTrackingLinkroute reference and as aPlannedtrace note readingPublic load link: <url> (via TrackFlo). An hourly job adds both to active routes that have a carrier. The page stays available for 90 days after the load is created.
TrackFlo does not set the route's status directly. Proof of delivery is emailed to your team, not filed in Mastery.
What your Mastery admin sets up
Most of this comes from your Mastery account team or whoever manages your MasterMind API access. If you have a Mastery test environment, a second set of everything below for it lets us exercise each write there before production.
1. An API client
TrackFlo authenticates with an OAuth 2.0 client credentials grant: it posts the client ID and secret, form-encoded, to your token URL and sends the access token as a Bearer header, reusing it until shortly before it expires. Send us:
The API base URL, for example
https://api.<tenant>.mastermindtms.com.The token URL.
The client ID and client secret.
The client needs access to these endpoints. TrackFlo sends the Accept-Version shown for each.
Endpoint | Version | Used for |
|---|---|---|
| 2.1.0 | Hourly refresh, driver assignment read-back, reference and trace-note checks |
| 2.1.0 | Carrier details |
| 2.1.0 | Customer name |
| 2.1.0 | Facility name and notes |
| 2.1.0 | Rep names and emails |
| 2.0.0 | Trace notes |
| 2.1.0 | Arrivals and departures |
| 2.0.0 | Driver assignment and dispatch |
| 2.1.0 | Route references (tracking links) |
2. Event stream access
TrackFlo reads five topics from Mastery's egress Kafka over TLS with SASL/PLAIN, and only reads: it never publishes to the stream. Send us the bootstrap servers, an API key and secret, the full topic names as your environment publishes them, and a consumer group prefix.
Topic | What it keeps current |
|---|---|
| Orders: status, stops, appointments, references, reps, customer, freight |
| The carrier on the route, carrier reps, empty location and time |
| Arrivals and departures |
| Trace notes, including telematics locations and ETAs |
| Drivers, tractor, trailer, tracking method, dispatch |
The order, carrier and trace-note topics have no fallback: if one isn't read, that data never reaches TrackFlo. Arrivals, departures and driver assignments are also picked up by the hourly refresh, at up to an hour's delay.
TrackFlo runs one consumer group per topic, named with your prefix plus the topic's short name (<prefix>.load, <prefix>.route-vendor, <prefix>.stop-event-actual, <prefix>.tracking-update, <prefix>.resource-assignment). The API key needs read access to the five topics and to consumer groups starting with that prefix.
3. Network access
Every connection is outbound from TrackFlo: HTTPS to the API and token URL, and TLS to the Kafka bootstrap servers. Nothing needs to be opened inbound. If your API or event platform only accepts known source addresses, tell us during onboarding.
4. Your Mastery terms
Several values TrackFlo reads and writes are terms from your Mastery data dictionary, and a term's ID often differs from the name Mastery's screens show (InYard for In-yard, for example). We match TrackFlo to your terms during onboarding:
Trace-note action terms. These become the update types your trackers pick from in TrackFlo, so send the term IDs as well as the display names.
Late reasons. The reasons trackers can attach to a late arrival. TrackFlo sends each one with both its term and its outbound code.
Route reference types.
TrackingLinkfor the carrier's link andTrackFloTrackingLinkfor the TrackFlo page.Carrier contact types.
PrimaryTrackingContactandAfterhourscontacts become the carrier's tracking and after-hours contacts in TrackFlo, andDispatchcontacts feed the load's carrier contact.Carrier identifiers (optional). A
TrackingPreferencesidentifier becomes the carrier's tracking instructions in TrackFlo.
Check that it's working
In Mastery, post a trace note on a route that is active and covered by a carrier.
In TrackFlo, search for the route number and open the load. The note should be on its timeline within a few minutes.
Add a check call to the same load in TrackFlo. It should appear on the route in Mastery as a trace note ending in
(via TrackFlo).
A load in Mastery isn't on the TrackFlo board
Trace notes from Mastery, including MacroPoint pings, never show up in TrackFlo
The trace-note topic isn't being read. Check that the API key can read egress.tracking-update and the <prefix>.tracking-update consumer group, and that we have the topic's full name.
Arrivals, departures or driver changes from Mastery show up, but up to an hour late
That is the hourly refresh catching them, which means the matching topic isn't reaching TrackFlo: egress.stop-event-actual for arrivals and departures, egress.resource-assignment for drivers and equipment. Check the key's access to that topic and its consumer group.
A check call logged in TrackFlo never reaches Mastery
Mastery requires a carrier on every trace note, so TrackFlo can't post one to a route that has no carrier yet. The tracker who logged it gets an email when an update to Mastery fails.
Driver info saved, but the tracking box in Mastery isn't ticked
Each tracking method needs its matching field: a driver-cell method needs the driver's phone number and an ELD method needs the ELD vehicle ID. When that field is missing, TrackFlo still sends the driver assignment but leaves the method off, because Mastery would otherwise discard the whole assignment. Add the phone number or ELD vehicle ID and save again.
TrackFlo won't let a tracker enter a stop time
The route hasn't been dispatched. Mastery only advances a route's status from arrivals and departures once it is dispatched, so TrackFlo asks for the dispatch first. Dispatch it from TrackFlo or Mastery, then enter the time.
Things to know
TrackFlo reads the stream from the moment the connection goes live and skips events more than 24 hours old, so it does not replay older history. A load already in progress at go-live appears the first time Mastery publishes a change to it.
Search. The route number is the TrackFlo load number. The order number, BOL, PO, pickup number and every other order reference are searchable too.
Status mapping. An Active route that is Covered, Driver Assigned, Dispatched, Arrived At Stop or Departed Stop is Active in TrackFlo. Complete is Complete, Cancelled is Cancelled, and Hold or anything earlier than Covered is Inactive.
Mastery accepts writes before applying them. Most write endpoints answer with an acknowledgement and process the change afterwards, so a change Mastery later discards isn't reported back to TrackFlo. A write that fails outright is retried, then the tracker gets an email.
Trace notes from TrackFlo. Every one is posted with Info From set to Driver. TrackFlo's own notes come back on the stream and are recognized by the
(via TrackFlo)suffix, so they aren't duplicated. Keep that suffix intact if anything in Mastery edits note text.Reps. TrackFlo reads four rep types: Customer Sales, Customer Account Manager, Carrier Sales and Carrier Manager. When an order has more than one of a type, the rep flagged main wins. Reps arrive on both order and carrier events, and the most recent event wins.
Cached details. Edits to a rep's name or email in Mastery reach TrackFlo within about a day, and edits to a customer's name or a facility's name or notes within about two weeks. Ask us to refresh one sooner.
Mastery owns carrier tracking instructions and tracking links. Tracking instructions typed in TrackFlo are replaced the next time TrackFlo refreshes the carrier from Mastery. A tracking link set in TrackFlo is written to Mastery, and a link set in Mastery replaces TrackFlo's on the next order update.
Removed stops. Mastery sends no deletion signal, so TrackFlo compares each order's stops against the ones it holds and removes any Mastery no longer lists.