Skip to content
English
Customer portal
Go to Tai Software
  • There are no suggestions because the search field is empty.

Trucker Tools (Smart Capacity) Integration

How the Tai TMS uses Trucker Tools for capacity matching, carrier sync, load tracking, Book It Now, and posting, and the settings each one needs.

How the Tai TMS connects to Trucker Tools for carrier capacity matching, carrier sync, load tracking, Book It Now, and load posting, and exactly which credentials and source settings each capability requires.

Overview

Trucker Tools is a carrier-facing platform that the Tai TMS integrates with to help brokers find and book capacity. Through this connector the Tai TMS provides four capabilities: capacity matching (Smart Capacity), which surfaces carriers likely to haul a given load and is kept supplied by a carrier sync; load tracking (Load Track); Book It Now, which lets a matched carrier accept a load at a posted rate; and load posting, which publishes loads to Trucker Tools.

The connector is configured on a Trucker Tools integration source record. Some values live in the standard credential fields on that record (User Name, License Key, Account Number), and others are entered as named source settings (for example secretkey and smartcapacity). Setup starts from the Tai App Store and is completed with Tai Client Success, who provisions the source and enters the values supplied by Trucker Tools. This article describes what each field does and which capability it enables, so staff can validate a configuration and troubleshoot failures.

How it works

Trucker Tools identifies the account with the same three fields from the integration source — License Key, Account Number, and User Name — but the exact authentication differs by capability:

  • Capacity matching (Smart Capacity) sends the License Key as an apiKey query-string parameter and a signature query-string parameter. The signature is the string accountId= &userName= encrypted with the secretkey source setting and encoded for the web address. This path requires User Name, License Key, Account Number, and secretkey. The Tai TMS keeps the top 30 carriers Trucker Tools returns, ordered by confidence percentage and then by company name.
  • Carrier sync (pushing your broker carriers to Trucker Tools so they can be matched) sends the License Key as an x-api-key request header and the secretkey value itself as the x-signature request header; the Account Number travels in the request body. Sync requires the License Key and secretkey. The scheduled sync job additionally requires the source to have an Account Number and smartcapacity = true. Each run sends only broker carriers changed since the previous run (the first run looks back 3 days).
  • Load posting, covered-load updates, and Book It Now send the License Key as an x-api-key request header and the string accountId= &userName= as an x-signature request header. Here the x-signature is the plain string — it is not encrypted with secretkey — so these paths require User Name, License Key, and Account Number, but not secretkey.
  • Load tracking (Load Track) is identified by a system-level Partner ID (configured inside Tai, not entered on the source record) together with the Account Number in the request. It does not use the License Key, User Name, or secretkey.

Because the capacity-matching signature depends on the account number and the user name, Smart Capacity needs all four of License Key, Account Number, User Name, and secretkey. If any is missing the Tai TMS raises a clear, user-facing error before it ever calls Trucker Tools (for example "Integration Source Account Number cannot be null.", "Integration Source User Name cannot be null.", "Integration Source License Key cannot be null.", or "Integration Source Parameter: secretKey cannot be null."). Load posting and Book It Now likewise block with a specific "cannot be null" error if Account Number, License Key, or User Name is blank, and load tracking stops with "Load track requires an Account Number to be set on the integration source." when the Account Number is blank.

The base addresses for the Trucker Tools API are fixed in the Tai TMS rather than entered by staff. Capacity-matching and carrier-sync calls go to the production Smart Capacity host by default, or to a staging host when the testing source setting is turned on. The load-posting address comes from an internal Tai application configuration value, not from the source record, and Book It Now always uses the production address. Enabling a capability is done with the source settings described below: smartcapacity turns on Smart Capacity, and bookItNow turns on Book It Now.

What triggers a Trucker Tools update. For a Truckload shipment on an organization whose Trucker Tools source has smartcapacity = true, the Tai TMS posts the load when the shipment moves into Committed status (or Quote status when submitquoted = true). After a posting exists, later status changes keep Trucker Tools in step: a canceled shipment deletes the posted load, a shipment that has a carrier on its linehaul leg sends a "covered" update, and otherwise the load is posted again as available.

Business rules & limits

  • Required credential fields on the source record: User Name, License Key, and Account Number. For capacity matching and load posting all three are used to authenticate; the License Key is the API key, and the account number plus user name form the signature string.
  • secretkey source setting — the signing key issued by Trucker Tools. It must be entered manually. It is required for Smart Capacity (capacity matching) and for carrier sync; without it those fail with an "Integration Source Parameter: secretKey cannot be null." error. Load posting, covered-load updates, Book It Now, and load tracking do not use secretkey.
  • Password is not used. A User Name / Password pair exists on the record, but the Trucker Tools connector never reads or requires the password. Do not spend time chasing a "missing password"; it is not part of this integration.
  • The Account Number is plaintext, not an encrypted key. It is a normal identifier that feeds into the signature (it is one of the two values that get signed). It is not itself an encrypted or hashed secret, and it is not the API key. The License Key is the API key; the secretkey setting is the signing secret.
  • smartcapacity = true enables Smart Capacity (capacity matching), lets the shipment status trigger pick up loads for the source, and switches on the scheduled carrier sync. Enter the value as lowercase true.
  • bookItNow = true enables Book It Now (the value is matched without regard to case). A carrier can also be marked with the carrier setting "Trucker Tools Book It Now", which is included when the carrier is synced to Trucker Tools. Book It Now is declined (and the reason is written to the shipment activity log) when the shipment has no carrier, or when the carrier requires compliance and is missing authority, insurance, safety, or a carrier packet.
  • submitquoted = true makes the connector submit loads at Quote status rather than the default Committed status.
  • testing = true routes capacity-matching and carrier-sync calls to the Trucker Tools staging host instead of production. Leave it off (or absent) for live accounts. It does not change Book It Now, which always uses the production address.
  • contactEmail supplies the broker contact email. Posted loads read any setting whose name begins with ContactEmail (not case-sensitive). Load tracking reads the setting named exactly contactEmail (lowercase c), so use that spelling if the same address should appear on both.
  • initiatedby = true (load tracking) makes the dispatcher on the load track the user who started the tracking. Without it, Tai uses the staff member most recently assigned as carrier rep on the shipment, falling back to the user who started the tracking.
  • Optional status. settings (for example status.LDUF) whose value is the display name of an existing shipment alert add that alert when Trucker Tools reports that status. The setting name is read exactly as written.
  • Any tracking source that carries a setting named smartcapacity — whatever its value, even false — is not offered in the load-track source list. Load tracking needs its own Trucker Tools source (with an Account Number) that has no smartcapacity setting at all.
  • Capacity matching and Book It Now apply to Truckload shipments; the status trigger that updates Trucker Tools ignores non-Truckload shipment types.
  • Enter flag-style settings as plain lowercase true / false. The setting names smartcapacity, bookItNow, submitquoted, testing, and secretkey are matched without regard to case, but a few load-tracking settings (contactEmail, initiatedby, and the status. settings) are read exactly as spelled here.
  • If Trucker Tools is temporarily unreachable while starting tracking, canceling tracking, or sending a driver comment, the user sees "Trucker Tools is temporarily unavailable. Please try starting tracking again shortly." (with "canceling tracking" or "sending the comment" in place of the last action) instead of a raw error. Retry after a short wait.

Frequently asked questions

Which fields are actually required to make Trucker Tools work in the Tai TMS?

On the integration source record you always need the User Name, the License Key (this is the API key), and the Account Number for capacity matching and load posting. For capacity matching (Smart Capacity) you also need the secretkey source setting (the signing key) plus smartcapacity = true to turn it on. Load posting and Book It Now use the same three record fields but do not need secretkey. Load tracking needs only the Account Number on the record. If a required field is blank, the Tai TMS blocks the request with a specific "cannot be null" error before contacting Trucker Tools.

The account says it has no password. Is that the problem?

No. The Trucker Tools connector does not read or use the password at all, even though the record has a User Name / Password pair. Authentication is done with the License Key (API key) and a signature built from the account number and user name using the secretkey setting. A blank password will never cause a Trucker Tools failure. Look instead at License Key, Account Number, User Name, and secretkey.

Is the Account Number an encrypted key or the API key?

Neither. The Account Number is plain text and is simply one of the inputs that get signed (account number plus user name) to produce the request signature. The API key is the License Key field, and the secret used to sign is the secretkey source setting. If someone reports "the account number looks like it should be encrypted," that is a misunderstanding — it is meant to be readable.

What does secretkey do, and where does it come from?

secretkey is the shared signing key that Trucker Tools issues for the account. For capacity matching (Smart Capacity) the Tai TMS uses it to encrypt and sign the account-number-and-user-name value, producing the signature query parameter on those requests; carrier sync sends the key itself as the signature header. It is entered manually as a source setting. Note that load posting, Book It Now, and load tracking do not use it — posting and Book It Now send the account-and-user-name string as a plain x-signature header instead, and load tracking uses the system Partner ID plus the Account Number. A missing secretkey produces an "Integration Source Parameter: secretKey cannot be null." error on capacity matching and carrier sync.

A broker enabled Trucker Tools but no carriers/capacity show up. What should I check?

Confirm smartcapacity = true is present on the source (entered as lowercase true), and that User Name, License Key, Account Number, and secretkey are all filled in. Confirm the shipment is a Truckload — the trigger ignores other shipment types. If it is a brand-new or test account, check whether testing = true is set: that points calls at the Trucker Tools staging host, which will not return production capacity. Remove or disable testing for a live account. Matching returns at most 30 carriers per load.

Why is my Trucker Tools source missing from the load-track list?

A source that has a smartcapacity setting (even set to false) is deliberately left out of the list of tracking sources. Use a separate Trucker Tools source for load tracking — one with the Account Number filled in and no smartcapacity setting at all.

Loads are posting at the wrong status. How do I control that?

The submitquoted setting controls it. With submitquoted = true, the connector submits at Quote status; without it, the default is Committed status. Set it to match how the broker wants loads pushed to Trucker Tools.

How do I switch an account between the Trucker Tools test environment and production?

Use the testing source setting. testing = true sends capacity-matching and carrier-sync calls to the Trucker Tools staging host; removing it (or setting it to false) uses the production host. The base URLs themselves are fixed inside the Tai TMS, so this toggle is the only staff-facing control for environment. Note the load-posting endpoint is driven by an internal Tai application setting rather than the source record, and Book It Now always uses production.

What email appears as the broker contact on a posted load or a load track?

Whatever is entered in the contact email source setting. Posted loads read any setting whose name begins with ContactEmail (not case-sensitive). Load tracking reads the setting named exactly contactEmail. Entering contactEmail with the broker's contact address as the value satisfies both.

Book It Now did not post. Why?

Check that bookItNow = true is on the Trucker Tools source and that the shipment has a carrier assigned. If the carrier is set to require compliance, it must have authority, insurance, safety, and a carrier packet on file; otherwise the Tai TMS declines the post and records the reason in the shipment activity log.